feat: introduce ComputeStrategy interface and extract AgentCoreComputeStrategy

Refactor the orchestrator to use a strategy pattern for compute backends,
as specified in the design docs. Extract AgentCore-specific session logic
(invoke/poll/stop) into AgentCoreComputeStrategy, resolved via a factory
based on blueprintConfig.compute_type. State transitions remain in the
handler. Pure refactor — no behavior or CloudFormation template changes.

Author: MichaelWalker-git

docs/src/content/docs/roadmap/Roadmap.md

@@ -19,6 +19,7 @@
 
 import { withDurableExecution, type DurableExecutionHandler } from '@aws/durable-execution-sdk-js';
 import { TaskStatus, TERMINAL_STATUSES } from '../constructs/task-status';
+import { resolveComputeStrategy } from './shared/compute-strategy';
 import {
   admissionControl,
   emitTaskEvent,
@@ -28,7 +29,7 @@ import {
   loadBlueprintConfig,
   loadTask,
   pollTaskStatus,
-  startSession,
+  transitionTask,
   type PollState,
 } from './shared/orchestrator';
 
@@ -87,10 +88,22 @@ const durableHandler: DurableExecutionHandler<OrchestrateTaskEvent, void> = asyn
     }
   });
 
-  // Step 4: Start agent session — invoke runtime and transition to RUNNING
+  // Step 4: Start agent session — resolve compute strategy, invoke runtime, transition to RUNNING
   await context.step('start-session', async () => {
     try {
-      return await startSession(task, payload, blueprintConfig);
+      const strategy = resolveComputeStrategy(blueprintConfig);
+      const handle = await strategy.startSession({ taskId, payload, blueprintConfig });
+
+      await transitionTask(taskId, TaskStatus.HYDRATING, TaskStatus.RUNNING, {
+        session_id: handle.sessionId,
+        started_at: new Date().toISOString(),
+      });
+      await emitTaskEvent(taskId, 'session_started', {
+        session_id: handle.sessionId,
+        strategy_type: handle.strategyType,
+      });
+
+      return handle.sessionId;
     } catch (err) {
       await failTask(taskId, TaskStatus.HYDRATING, `Session start failed: ${String(err)}`, task.user_id, true);
       throw err;

src/handlers/orchestrate-task.ts

@@ -0,0 +1,53 @@
+/**
+ *  MIT No Attribution
+ *
+ *  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy of
+ *  the Software without restriction, including without limitation the rights to
+ *  use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ *  the Software, and to permit persons to whom the Software is furnished to do so.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+import type { BlueprintConfig } from './repo-config';
+import { AgentCoreComputeStrategy } from './strategies/agentcore-strategy';
+
+export interface SessionHandle {
+  readonly sessionId: string;
+  readonly strategyType: string;
+  readonly metadata: Record<string, unknown>;
+}
+
+export type SessionStatus =
+  | { readonly status: 'running' }
+  | { readonly status: 'completed' }
+  | { readonly status: 'failed'; readonly error: string };
+
+export interface ComputeStrategy {
+  readonly type: string;
+  startSession(input: {
+    taskId: string;
+    payload: Record<string, unknown>;
+    blueprintConfig: BlueprintConfig;
+  }): Promise<SessionHandle>;
+  pollSession(handle: SessionHandle): Promise<SessionStatus>;
+  stopSession(handle: SessionHandle): Promise<void>;
+}
+
+export function resolveComputeStrategy(blueprintConfig: BlueprintConfig): ComputeStrategy {
+  const computeType = blueprintConfig.compute_type;
+  switch (computeType) {
+    case 'agentcore':
+      return new AgentCoreComputeStrategy({ runtimeArn: blueprintConfig.runtime_arn });
+    default:
+      throw new Error(`Unknown compute_type: '${computeType}'`);
+  }
+}

src/handlers/shared/compute-strategy.ts

@@ -17,8 +17,6 @@
  *  SOFTWARE.
  */
 
-import { randomUUID } from 'crypto';
-import { InvokeAgentRuntimeCommand, BedrockAgentCoreClient } from '@aws-sdk/client-bedrock-agentcore';
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 import { DynamoDBDocumentClient, GetCommand, PutCommand, UpdateCommand } from '@aws-sdk/lib-dynamodb';
 import { ulid } from 'ulid';
@@ -32,7 +30,6 @@ import { computeTtlEpoch, DEFAULT_MAX_TURNS } from './validation';
 import { TaskStatus, TERMINAL_STATUSES, VALID_TRANSITIONS, type TaskStatusType } from '../../constructs/task-status';
 
 const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));
-const agentCoreClient = new BedrockAgentCoreClient({});
 
 const TABLE_NAME = process.env.TASK_TABLE_NAME!;
 const EVENTS_TABLE_NAME = process.env.TASK_EVENTS_TABLE_NAME!;
@@ -305,43 +302,6 @@ export async function hydrateAndTransition(task: TaskRecord, blueprintConfig?: B
   return payload;
 }
 
-/**
- * Start an AgentCore runtime session and transition task to RUNNING.
- * @param task - the task record.
- * @param payload - the hydrated invocation payload.
- * @param blueprintConfig - optional per-repo blueprint config for runtime ARN override.
- * @returns the session ID.
- */
-export async function startSession(
-  task: TaskRecord,
-  payload: Record<string, unknown>,
-  blueprintConfig?: BlueprintConfig,
-): Promise<string> {
-  // AgentCore requires runtimeSessionId >= 33 chars; UUID v4 is 36 chars.
-  const sessionId = randomUUID();
-  const runtimeArn = blueprintConfig?.runtime_arn ?? RUNTIME_ARN;
-
-  const command = new InvokeAgentRuntimeCommand({
-    agentRuntimeArn: runtimeArn,
-    runtimeSessionId: sessionId,
-    contentType: 'application/json',
-    accept: 'application/json',
-    payload: new TextEncoder().encode(JSON.stringify({ input: payload })),
-  });
-
-  await agentCoreClient.send(command);
-
-  await transitionTask(task.task_id, TaskStatus.HYDRATING, TaskStatus.RUNNING, {
-    session_id: sessionId,
-    started_at: new Date().toISOString(),
-  });
-  await emitTaskEvent(task.task_id, 'session_started', { session_id: sessionId });
-
-  logger.info('Session started', { task_id: task.task_id, session_id: sessionId });
-
-  return sessionId;
-}
-
 /**
  * Poll the task record in DynamoDB to check if the agent wrote a terminal status.
  * Returns the updated PollState; the waitStrategy decides whether to continue.

src/handlers/shared/orchestrator.ts

@@ -0,0 +1,90 @@
+/**
+ *  MIT No Attribution
+ *
+ *  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy of
+ *  the Software without restriction, including without limitation the rights to
+ *  use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ *  the Software, and to permit persons to whom the Software is furnished to do so.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+import { randomUUID } from 'crypto';
+import { BedrockAgentCoreClient, InvokeAgentRuntimeCommand, StopRuntimeSessionCommand } from '@aws-sdk/client-bedrock-agentcore';
+import type { ComputeStrategy, SessionHandle, SessionStatus } from '../compute-strategy';
+import { logger } from '../logger';
+import type { BlueprintConfig } from '../repo-config';
+
+export class AgentCoreComputeStrategy implements ComputeStrategy {
+  readonly type = 'agentcore';
+  private readonly client: BedrockAgentCoreClient;
+  private readonly runtimeArn: string;
+
+  constructor(options: { runtimeArn: string }) {
+    this.runtimeArn = options.runtimeArn;
+    this.client = new BedrockAgentCoreClient({});
+  }
+
+  async startSession(input: {
+    taskId: string;
+    payload: Record<string, unknown>;
+    blueprintConfig: BlueprintConfig;
+  }): Promise<SessionHandle> {
+    // AgentCore requires runtimeSessionId >= 33 chars; UUID v4 is 36 chars.
+    const sessionId = randomUUID();
+    const runtimeArn = input.blueprintConfig.runtime_arn ?? this.runtimeArn;
+
+    const command = new InvokeAgentRuntimeCommand({
+      agentRuntimeArn: runtimeArn,
+      runtimeSessionId: sessionId,
+      contentType: 'application/json',
+      accept: 'application/json',
+      payload: new TextEncoder().encode(JSON.stringify({ input: input.payload })),
+    });
+
+    await this.client.send(command);
+
+    logger.info('AgentCore session invoked', { task_id: input.taskId, session_id: sessionId, runtime_arn: runtimeArn });
+
+    return {
+      sessionId,
+      strategyType: this.type,
+      metadata: { runtimeArn },
+    };
+  }
+
+  async pollSession(_handle: SessionHandle): Promise<SessionStatus> {
+    // Polling is currently done at the orchestrator level via DDB reads.
+    // This method exists for PR 2 where different strategies may poll differently.
+    return { status: 'running' };
+  }
+
+  async stopSession(handle: SessionHandle): Promise<void> {
+    const runtimeArn = handle.metadata.runtimeArn as string | undefined;
+    if (!runtimeArn) {
+      logger.warn('No runtimeArn in session handle, cannot stop session', { session_id: handle.sessionId });
+      return;
+    }
+
+    try {
+      await this.client.send(new StopRuntimeSessionCommand({
+        agentRuntimeArn: runtimeArn,
+        runtimeSessionId: handle.sessionId,
+      }));
+      logger.info('AgentCore session stopped', { session_id: handle.sessionId });
+    } catch (err) {
+      logger.warn('Failed to stop AgentCore session (best-effort)', {
+        session_id: handle.sessionId,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+}

src/handlers/shared/strategies/agentcore-strategy.ts

@@ -27,10 +27,10 @@ jest.mock('@aws-sdk/lib-dynamodb', () => ({
   UpdateCommand: jest.fn((input: unknown) => ({ _type: 'Update', input })),
 }));
 
-const mockAgentCoreSend = jest.fn();
 jest.mock('@aws-sdk/client-bedrock-agentcore', () => ({
-  BedrockAgentCoreClient: jest.fn(() => ({ send: mockAgentCoreSend })),
+  BedrockAgentCoreClient: jest.fn(() => ({ send: jest.fn() })),
   InvokeAgentRuntimeCommand: jest.fn((input: unknown) => ({ _type: 'InvokeAgentRuntime', input })),
+  StopRuntimeSessionCommand: jest.fn(),
 }));
 
 const mockHydrateContext = jest.fn();
@@ -75,7 +75,6 @@ import {
   loadBlueprintConfig,
   loadTask,
   pollTaskStatus,
-  startSession,
   transitionTask,
 } from '../../src/handlers/shared/orchestrator';
 
@@ -192,18 +191,6 @@ describe('hydrateAndTransition', () => {
   });
 });
 
-describe('startSession', () => {
-  test('invokes agent runtime and transitions to RUNNING', async () => {
-    mockAgentCoreSend.mockResolvedValueOnce({}); // InvokeAgentRuntime
-    mockDdbSend.mockResolvedValue({}); // transitionTask + emitTaskEvent
-
-    const sessionId = await startSession(baseTask as any, { repo_url: 'org/repo', task_id: 'TASK001' });
-    // Session ID is a UUID v4 (36 chars), not a ULID
-    expect(sessionId).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/);
-    expect(mockAgentCoreSend).toHaveBeenCalledTimes(1);
-  });
-});
-
 describe('pollTaskStatus', () => {
   test('increments attempt count and reads status', async () => {
     mockDdbSend.mockResolvedValueOnce({ Item: { status: 'RUNNING' } });
@@ -385,21 +372,6 @@ describe('hydrateAndTransition with blueprint config', () => {
   });
 });
 
-describe('startSession with blueprint config', () => {
-  test('uses blueprint runtime ARN override', async () => {
-    mockAgentCoreSend.mockResolvedValueOnce({});
-    mockDdbSend.mockResolvedValue({});
-
-    await startSession(baseTask as any, { repo_url: 'org/repo', task_id: 'TASK001' }, {
-      compute_type: 'agentcore',
-      runtime_arn: 'arn:aws:bedrock-agentcore:us-east-1:123:runtime/custom',
-    });
-
-    const invokeCall = mockAgentCoreSend.mock.calls[0][0];
-    expect(invokeCall.input.agentRuntimeArn).toBe('arn:aws:bedrock-agentcore:us-east-1:123:runtime/custom');
-  });
-});
-
 describe('finalizeTask', () => {
   test('handles already-terminal task', async () => {
     mockDdbSend

test/handlers/orchestrate-task.test.ts

@@ -0,0 +1,45 @@
+/**
+ *  MIT No Attribution
+ *
+ *  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy of
+ *  the Software without restriction, including without limitation the rights to
+ *  use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ *  the Software, and to permit persons to whom the Software is furnished to do so.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+jest.mock('@aws-sdk/client-bedrock-agentcore', () => ({
+  BedrockAgentCoreClient: jest.fn(() => ({ send: jest.fn() })),
+  InvokeAgentRuntimeCommand: jest.fn(),
+  StopRuntimeSessionCommand: jest.fn(),
+}));
+
+import { resolveComputeStrategy } from '../../../src/handlers/shared/compute-strategy';
+import { AgentCoreComputeStrategy } from '../../../src/handlers/shared/strategies/agentcore-strategy';
+
+describe('resolveComputeStrategy', () => {
+  test('returns AgentCoreComputeStrategy for compute_type agentcore', () => {
+    const strategy = resolveComputeStrategy({
+      compute_type: 'agentcore',
+      runtime_arn: 'arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/test',
+    });
+    expect(strategy).toBeInstanceOf(AgentCoreComputeStrategy);
+    expect(strategy.type).toBe('agentcore');
+  });
+
+  test('throws for unknown compute_type', () => {
+    expect(() => resolveComputeStrategy({
+      compute_type: 'unknown-type',
+      runtime_arn: 'arn:test',
+    })).toThrow("Unknown compute_type: 'unknown-type'");
+  });
+});