@aws-blocks/bb-agent 0.3.5 → 0.4.0

package/src/agent.ts

@@ -5,37 +5,80 @@ import { Scope, registerSdkIdentifiers, getSdkIdentifiers } from '@aws-blocks/co
 import type { ScopeParent } from '@aws-blocks/core';
 import { DistributedTable } from '@aws-blocks/bb-distributed-table';
 import { Realtime } from '@aws-blocks/bb-realtime';
-import { AsyncJob } from '@aws-blocks/bb-async-job';
 import { FileBucket } from '@aws-blocks/bb-file-bucket';
 import { Logger } from '@aws-blocks/bb-logger';
 import type { ChildLogger } from '@aws-blocks/bb-logger';
 // Runtime values from `@strands-agents/sdk` are deferred to loadStrands(); only types
 // are imported here (erased at compile time). See loadStrands() / issue #153.
 import type { Agent as StrandsAgent, SnapshotStorage } from '@strands-agents/sdk';
-import { z } from 'zod';
+import type { z } from 'zod';
 import { createStrandsModel, checkModelHealth } from './model-factory.js';
 import { messageSchema, conversationSchema, agentStreamChunkSchema } from './schemas.js';
-import type { AgentConfig, AgentStreamChunk, AgentStreamResult, StreamOptions, Message, Conversation, TokenUsage, ConversationManagerConfig, ModelConfig, JSONValue, InterruptResponse, DefaultToolContext, AgentTool, ToolDefinition } from './types.js';
+import type { AgentConfig, AgentStreamChunk, AgentStreamResult, StreamOptions, Message, Conversation, TokenUsage, ConversationManagerConfig, ModelConfig, JSONValue, InterruptResponse, DefaultToolContext, AgentTool, ToolDefinition, CannedToolHints } from './types.js';
 import { AgentErrors, blocksAgentError, InterruptError } from './errors.js';
-import { INTERACTIVE_JOB_EVENT_SOURCE } from './job-event-source.js';
 import { BB_NAME, BB_VERSION } from './version.js';
 import { ulid } from 'ulid';
 
-/** Payload submitted to the internal AsyncJob BB. */
-const jobPayloadSchema = z.object({
-	message: z.string(),
-	conversationId: z.string().optional(),
-	channelId: z.string(),
-	userId: z.string(),
-	resume: z.boolean().optional(), // Resume fields (for HITL interrupt responses)
-	interruptResponses: z.array(z.object({ interruptId: z.string(), response: z.string() })).optional(),
+/**
+ * A single agent turn to dispatch (initial message or HITL resume). Passed to
+ * {@link AgentBase.dispatchTurn} — run in-process locally, or shipped to the AgentCore Runtime
+ * on AWS as the `InvokeAgentRuntime` payload.
+ *
+ * @internal Internal turn-dispatch seam — not part of the public API. Customers use
+ * `stream()` / `resume()`; this is the shape those hand to the compute layer.
+ */
+export interface AgentTurnPayload<TContext = DefaultToolContext> {
+	/** User prompt. Empty on resume (interruptResponses drive the turn instead). */
+	message: string;
+	/** Conversation to persist to / restore the session from (undefined for inferenceOnly). */
+	conversationId?: string;
+	/** Realtime channel the client subscribes to for this turn's chunks. */
+	channelId: string;
+	/** Conversation owner. */
+	userId: string;
+	/** HITL resume: approval responses to apply instead of a new prompt. */
+	interruptResponses?: Array<{ interruptId: string; response: string }>;
 	/** Per-call tool context, forwarded to tool invocations. JSON-serializable. */
-	context: z.any().optional(),
-});
+	context?: TContext;
+}
 
 /** Key under which the per-call tool context is threaded through Strands `invocationState`. */
 const TOOL_CONTEXT_KEY = '__bbAgentToolContext';
 
+/**
+ * Default runaway-protection caps applied per turn when `AgentConfig` does not
+ * override them. See `AgentConfig.maxLlmCalls` / `maxToolIterations`.
+ *
+ * 20 is a backstop, not a tuned budget: healthy interactive turns in the agent
+ * samples and in Strands' own examples settle at a handful of model/tool calls
+ * (a plan step, one or two tool rounds, a final answer), so 20 leaves roughly an
+ * order of magnitude of headroom before it engages, while still cutting a
+ * reason->act loop off long before it becomes a noticeable Bedrock bill. Agents
+ * that legitimately take more steps are expected to raise the value (or set it
+ * to `false`) deliberately.
+ */
+const DEFAULT_MAX_LLM_CALLS = 20;
+const DEFAULT_MAX_TOOL_ITERATIONS = 20;
+
+/** `appState` keys holding the per-turn cap counters, so they survive `resume()`. */
+const MODEL_CALL_COUNT_KEY = '__bbAgentModelCallCount';
+const TOOL_CALL_COUNT_KEY = '__bbAgentToolCallCount';
+const COUNTED_TOOL_USE_IDS_KEY = '__bbAgentCountedToolUseIds';
+/** Id of the turn the counters belong to, so a new turn can zero them lazily. */
+const TURN_ID_KEY = '__bbAgentCapTurnId';
+
+/**
+ * Validate a runaway-protection cap: a positive integer, `false` to disable, or
+ * `undefined` for the default. Rejects `0`/negatives/non-integers/`NaN`, which
+ * would otherwise either kill every turn or silently disable the cap.
+ */
+function validateCap(name: string, value: number | false | undefined): void {
+	if (value === false || value === undefined) return;
+	if (!Number.isInteger(value) || value < 1) {
+		throw blocksAgentError(AgentErrors.InvalidModelConfig, `'${name}' must be a positive integer or false to disable the cap, got ${String(value)}.`);
+	}
+}
+
 /**
  * Lazily import the Strands SDK runtime, caching the module after the first load.
  *
@@ -56,6 +99,26 @@ function loadStrands(): Promise<typeof import('@strands-agents/sdk')> {
 	return strandsModulePromise;
 }
 
+// ── Agent instance registry ──────────────────────────────────────────────────
+// A module-singleton map of fullId → live Agent instance. The AgentCore Runtime
+// entrypoint (agentcore-entry.ts) imports the app backend (which constructs the
+// Agent, registering it here) and then looks it up by the BB_AGENT_ID the CDK
+// Runtime construct injected, to drive its loop. Because it's a module singleton,
+// the entrypoint and the backend MUST be co-bundled into one module graph (see
+// agentcore-bundle.ts) — otherwise the Agent registers in one copy's map and the
+// lookup reads another's.
+const agentRegistry = new Map<string, AgentBase<any>>();
+
+/** @internal Register a live Agent instance so the AgentCore entrypoint can find it by fullId. */
+export function registerAgentInstance(fullId: string, agent: AgentBase<any>): void {
+	agentRegistry.set(fullId, agent);
+}
+
+/** @internal Look up a registered Agent instance by fullId (used by the AgentCore entrypoint). */
+export function getAgentInstance(fullId: string): AgentBase<any> | undefined {
+	return agentRegistry.get(fullId);
+}
+
 /**
  * The per-call tool factory handed to the `tools` callback. At runtime it's an identity
  * function whose only job is to give TypeScript a single call site per tool where it can
@@ -102,12 +165,14 @@ async function createConversationManager(config?: ConversationManagerConfig) {
 /**
  * Base class for the Agent BB. Extended by agent.mock.ts (model.local) and agent.aws.ts (model.deployed).
  *
- * Creates up to 4 internal BBs depending on mode:
+ * Creates internal BBs depending on mode:
  * - FileBucket: session snapshot storage for Strands SessionManager (always)
  * - DistributedTable: frontend message history (when inferenceOnly = false)
- * - Realtime: streaming chunks to browser + AsyncJob result delivery (always)
- * - AsyncJob: runs Strands agent asynchronously (always)
- * - TODO logging
+ * - Realtime: streaming chunks to browser (always)
+ *
+ * The agent loop runs via {@link dispatchTurn}: in-process locally (mock), and on the
+ * AgentCore Runtime on AWS (the deployed subclass overrides dispatchTurn to invoke it). The
+ * AgentCore Runtime itself is provisioned by the CDK layer (index.cdk.ts → AgentCoreRuntime).
  */
 export class AgentBase<TContext = DefaultToolContext> extends Scope {
 	/** Developer-facing agent configuration. */
@@ -120,8 +185,6 @@ export class AgentBase<TContext = DefaultToolContext> extends Scope {
 	private messages?: DistributedTable<z.infer<typeof messageSchema>, { partitionKey: 'conversationId'; sortKey: 'messageId' }>;
 	/** Realtime pub/sub — streams chunks to browser. */
 	private rt: InstanceType<typeof Realtime>;
-	/** Internal async job — runs the Strands agent in a separate execution context. */
-	private job: AsyncJob<z.infer<typeof jobPayloadSchema>>;
 	/** Which model provider to use. */
 	private modelConfig: ModelConfig | ModelConfig[] | undefined;
 	/** Where to persist Strands agent state (snapshots). */
@@ -142,6 +205,8 @@ export class AgentBase<TContext = DefaultToolContext> extends Scope {
 		super(id, { parent: scope, bbName: BB_NAME, bbVersion: BB_VERSION });
 		this.log = config?.logger ?? new Logger(this, 'logger', { level: 'error' });
 		this.config = config;
+		validateCap('maxLlmCalls', config.maxLlmCalls);
+		validateCap('maxToolIterations', config.maxToolIterations);
 		this.toolMap = resolveTools<TContext>(config.tools);
 		this.modelConfig = modelConfig;
 
@@ -166,29 +231,6 @@ export class AgentBase<TContext = DefaultToolContext> extends Scope {
 			},
 		});
 
-		this.job = new AsyncJob(this, 'job', {
-			schema: jobPayloadSchema,
-			...INTERACTIVE_JOB_EVENT_SOURCE,
-			handler: async (payload) => {
-				try {
-					await this.runAgent(payload.message, payload.conversationId, payload.channelId, payload.userId, payload.interruptResponses, payload.context);
-				} catch (err) {
-					const errorMessage = err instanceof Error ? err.message : String(err);
-					this.log.error('runAgent error', { error: errorMessage });
-					// Best-effort: persist error to conversation history (don't let DB failure block error chunk)
-					try {
-						if (payload.conversationId && this.messages) {
-							await this.messages.put({ conversationId: payload.conversationId, messageId: ulid(), role: 'assistant' as const, content: '', contentType: 'text' as const, userId: payload.userId, createdAt: Date.now(), metadata: JSON.stringify({ error: errorMessage }) });
-						}
-					} catch (persistErr) {
-						this.log.error('Failed to persist error to history', { error: persistErr });
-					}
-					// Publish error chunk so the client doesn't hang. Don't re-throw — AsyncJob would retry a non-idempotent operation.
-					await this.rt.publish('chunks', payload.channelId, { type: 'error', error: errorMessage });
-				}
-			},
-		});
-
 		const identifiers: Record<string, string> = {};
 		if (this.conversations) {
 			identifiers.conversationsTableName = getSdkIdentifiers(this.conversations).tableName;
@@ -199,24 +241,150 @@ export class AgentBase<TContext = DefaultToolContext> extends Scope {
 		identifiers.sessionBucketName = getSdkIdentifiers(this.sessionBucket).bucketName;
 		identifiers.realtimeWsUrl = getSdkIdentifiers(this.rt).wsUrl;
 		identifiers.realtimeCallbackUrl = getSdkIdentifiers(this.rt).callbackUrl;
-		identifiers.jobQueueUrl = getSdkIdentifiers(this.job).queueUrl;
 		registerSdkIdentifiers(this.fullId, identifiers);
+
+		// Register this instance so the AgentCore Runtime entrypoint (agentcore-entry.ts)
+		// can find it by fullId and drive its loop. Harmless in the Lambda/mock paths.
+		registerAgentInstance(this.fullId, this);
+	}
+
+	/**
+	 * Run one agent turn (initial message or HITL resume) and publish its chunks to Realtime.
+	 *
+	 * This is the single execution entry the compute layer invokes: the AgentCore Runtime
+	 * entrypoint (agentcore-entry.ts) calls it as a background async task on AWS, and locally
+	 * {@link dispatchTurn} calls it in-process. Errors are caught and published as an `error`
+	 * chunk (not re-thrown) so the client never hangs and a non-idempotent turn isn't retried.
+	 *
+	 * @param payload - the turn to run (see {@link AgentTurnPayload}).
+	 * @internal Invoked by the compute layer (agentcore-entry / dispatchTurn), not customer API.
+	 */
+	async invokeTurn(payload: AgentTurnPayload<TContext>): Promise<void> {
+		try {
+			await this.runAgent(payload.message, payload.conversationId, payload.channelId, payload.userId, payload.interruptResponses, payload.context);
+		} catch (err) {
+			const errorMessage = err instanceof Error ? err.message : String(err);
+			this.log.error('runAgent error', { error: errorMessage });
+			// Best-effort: persist error to conversation history (don't let DB failure block error chunk)
+			try {
+				if (payload.conversationId && this.messages) {
+					await this.messages.put({ conversationId: payload.conversationId, messageId: ulid(), role: 'assistant' as const, content: '', contentType: 'text' as const, userId: payload.userId, createdAt: Date.now(), metadata: JSON.stringify({ error: errorMessage }) });
+				}
+			} catch (persistErr) {
+				this.log.error('Failed to persist error to history', { error: persistErr });
+			}
+			// Publish error chunk so the client doesn't hang. Don't re-throw — a non-idempotent turn shouldn't be retried.
+			await this.rt.publish('chunks', payload.channelId, { type: 'error', error: errorMessage });
+		}
+	}
+
+	/**
+	 * Dispatch a turn to wherever the agent loop runs, returning promptly so `stream()`/`resume()`
+	 * hand the client a `channelId` without waiting for the turn to finish.
+	 *
+	 * Base (local/mock): run the loop IN-PROCESS, fire-and-forget — chunks flow to the mock
+	 * Realtime as the turn progresses. The deployed (AWS) subclass overrides this to invoke the
+	 * AgentCore Runtime, which runs the loop as a background task and publishes to Realtime.
+	 *
+	 * @internal Internal compute seam (overridden by the AWS subclass); not customer API.
+	 */
+	protected async dispatchTurn(payload: AgentTurnPayload<TContext>): Promise<void> {
+		// Reproduce the AWS wire boundary locally. On AWS, dispatchTurn JSON-serializes `context` into the
+		// InvokeAgentRuntime payload and the container re-parses it (z.unknown passthrough), so a tool
+		// receives a JSON-mangled context (Date→string, Set→{}, undefined dropped) — NOT the live object
+		// it would get here in-process. Round-trip it so a serialization bug fails locally instead of only
+		// after deploy. (A non-JSON-serializable context throws here, mirroring the AWS JSON.stringify.)
+		const context =
+			payload.context === undefined ? undefined : (JSON.parse(JSON.stringify(payload.context)) as TContext);
+		// invokeTurn catches and publishes its own errors, so the floating promise can't reject.
+		void this.invokeTurn({ ...payload, context });
 	}
 
 	/**
 	 * Executes the Strands agent, publishes chunks to Realtime, persists messages to DynamoDB.
 	 *
-	 * Called by: AsyncJob consumer.
-	 * NOT called directly — stream() submits to AsyncJob, which invokes this.
+	 * Called by {@link invokeTurn} (wherever the loop runs — locally in-process, or inside the
+	 * AgentCore Runtime container on AWS). Publishes each event to the Realtime `chunks` channel.
 	 *
-	 * Flow: AsyncJob handler → runAgent() → Strands agent.stream() → publishes chunks to Realtime BB
-	 * TODO add comments for args
+	 * Flow: invokeTurn() → runAgent() → Strands agent.stream() → publishes chunks to Realtime BB
+	 *
+	 * @param message - the user message that starts the turn (ignored on the resume path)
+	 * @param conversationId - conversation to load/persist history for; undefined means no persistence
+	 * @param channelId - Realtime channel the stream chunks are published to
+	 * @param userId - owner of the conversation, stored on every persisted message
+	 * @param interruptResponses - approval responses when resuming a turn paused on a HITL interrupt
+	 * @param context - per-call tool context, threaded to tool handlers via Strands invocationState
 	 */
 	private async runAgent(message: string, conversationId: string | undefined, channelId: string, userId: string, interruptResponses?: Array<{ interruptId: string; response: string }>, context?: TContext): Promise<void> {
-		const { InterruptResponseContent, ModelStreamUpdateEvent, BeforeToolCallEvent, AfterToolCallEvent, AgentResultEvent } = await loadStrands();
+		const { InterruptResponseContent, ModelStreamUpdateEvent, BeforeModelCallEvent, BeforeToolCallEvent, AfterToolCallEvent, AgentResultEvent } = await loadStrands();
 		const strandsAgent = await this.createStrandsAgent(conversationId, context);
 		const startTime = Date.now();
 
+		// Runaway-protection caps (see AgentConfig.maxLlmCalls / maxToolIterations).
+		// Enforced by counting Strands' hooks and cancelling the agent once a cap is
+		// exceeded — cancellation surfaces below as stopReason 'cancelled'.
+		// Registered here (not in createStrandsAgent) so the `capExceeded` reason stays
+		// in scope for the result handling; Strands runs multiple hooks per event, so
+		// this coexists with the HITL hook.
+		// The counters live in `appState`, which the SessionManager persists, so they
+		// keep counting across a HITL interrupt + resume() — the cap bounds a whole
+		// logical turn, not just one execution segment.
+		// The reset is LAZY (inside the hooks), not done here: the SessionManager
+		// restores the snapshot's appState during `stream()`, i.e. after this point, so
+		// a reset written here would be overwritten by the previous turn's counts and
+		// the budget would leak from turn to turn. Instead a fresh turn gets a new turn
+		// id and the first hook to run notices the stored id is stale and zeroes the
+		// counters; a resume passes no id, so it continues on the persisted counts.
+		let capExceeded: string | undefined;
+		const turnId = interruptResponses ? undefined : ulid();
+		const startTurnIfNew = (): void => {
+			if (!turnId || strandsAgent.appState.get(TURN_ID_KEY) === turnId) return;
+			strandsAgent.appState.set(TURN_ID_KEY, turnId);
+			strandsAgent.appState.set(MODEL_CALL_COUNT_KEY, 0);
+			strandsAgent.appState.set(TOOL_CALL_COUNT_KEY, 0);
+			strandsAgent.appState.set(COUNTED_TOOL_USE_IDS_KEY, []);
+		};
+		const bumpCount = (key: string): number => {
+			startTurnIfNew();
+			const next = (Number(strandsAgent.appState.get(key)) || 0) + 1;
+			strandsAgent.appState.set(key, next);
+			return next;
+		};
+		// A tool call paused on a HITL interrupt re-emits BeforeToolCallEvent when the
+		// turn resumes, so count each toolUseId at most once — otherwise an approved
+		// call would be charged twice against the cap.
+		const countToolCall = (toolUseId: string): number => {
+			startTurnIfNew();
+			const seen = (strandsAgent.appState.get(COUNTED_TOOL_USE_IDS_KEY) as string[] | undefined) ?? [];
+			if (seen.includes(toolUseId)) return Number(strandsAgent.appState.get(TOOL_CALL_COUNT_KEY)) || 0;
+			strandsAgent.appState.set(COUNTED_TOOL_USE_IDS_KEY, [...seen, toolUseId]);
+			return bumpCount(TOOL_CALL_COUNT_KEY);
+		};
+		// `false` disables a cap (→ Infinity, never trips); undefined uses the default.
+		// Values are validated in the constructor (positive integer or false).
+		const maxLlmConfig = this.config.maxLlmCalls ?? DEFAULT_MAX_LLM_CALLS;
+		const maxToolsConfig = this.config.maxToolIterations ?? DEFAULT_MAX_TOOL_ITERATIONS;
+		const maxLlm = maxLlmConfig === false ? Number.POSITIVE_INFINITY : maxLlmConfig;
+		const maxTools = maxToolsConfig === false ? Number.POSITIVE_INFINITY : maxToolsConfig;
+		// Both cancels pull weight: `event.cancel` skips this specific over-cap call (so
+		// it never reaches the provider — same mechanism as the deny path in
+		// createStrandsAgent, which uses it alone and lets the turn continue), while
+		// `strandsAgent.cancel()` additionally unwinds the loop so nothing after it runs.
+		strandsAgent.addHook(BeforeModelCallEvent, (event) => {
+			if (bumpCount(MODEL_CALL_COUNT_KEY) > maxLlm) {
+				capExceeded ??= `exceeded maxLlmCalls (${maxLlm})`;
+				event.cancel = 'maxLlmCalls exceeded';
+				strandsAgent.cancel();
+			}
+		});
+		strandsAgent.addHook(BeforeToolCallEvent, (event) => {
+			if (countToolCall(event.toolUse.toolUseId) > maxTools) {
+				capExceeded ??= `exceeded maxToolIterations (${maxTools})`;
+				event.cancel = 'maxToolIterations exceeded';
+				strandsAgent.cancel();
+			}
+		});
+
 		// Only persist user message on initial path (not resume)
 		if (!interruptResponses && conversationId && this.messages) {
 			await this.messages.put({ conversationId, messageId: ulid(), role: 'user' as const, content: message, contentType: 'text' as const, userId, createdAt: Date.now(), metadata: '{}' });
@@ -301,6 +469,30 @@ export class AgentBase<TContext = DefaultToolContext> extends Scope {
 		const latencyMs = Date.now() - startTime;
 		this.log.info('runAgent done', { textLength: fullText.length, latencyMs, interrupted });
 
+		// A runaway-protection cap (maxLlmCalls / maxToolIterations) cancelled the turn.
+		// Cancellation ends the stream normally (no throw, stopReason 'cancelled'), and
+		// `capExceeded` is only ever set by the cap hooks above — so surface it as an
+		// error chunk and skip the final persist + 'done' below.
+		if (capExceeded) {
+			const stoppedError = `Agent stopped: ${capExceeded}.`;
+			this.log.warn('runAgent stopped by cap', {
+				reason: capExceeded,
+				modelCallCount: Number(strandsAgent.appState.get(MODEL_CALL_COUNT_KEY)) || 0,
+				toolCallCount: Number(strandsAgent.appState.get(TOOL_CALL_COUNT_KEY)) || 0,
+			});
+			if (conversationId && this.messages) {
+				// Record why the turn stopped, mirroring the AsyncJob error handler — a
+				// reloaded conversation would otherwise just end without explanation.
+				// The cancelled tool call itself stays paired: Strands still emits
+				// AfterToolCallEvent for a call cancelled via `event.cancel` (carrying the
+				// cancellation as the result), which the loop above persists as
+				// 'tool-result', so no dangling tool_use is left behind for the next turn.
+				await this.messages.put({ conversationId, messageId: ulid(), role: 'assistant' as const, content: fullText, contentType: 'text' as const, userId, createdAt: Date.now(), metadata: JSON.stringify({ error: stoppedError, latencyMs }) });
+			}
+			await this.rt.publish('chunks', channelId, { type: 'error', error: stoppedError });
+			return;
+		}
+
 		// If interrupted, don't persist final message or publish done — agent is paused
 		if (interrupted) return;
 
@@ -346,6 +538,17 @@ export class AgentBase<TContext = DefaultToolContext> extends Scope {
 			}),
 		}));
 
+		// Collect local-dev hints for the canned provider (Strands strips these fields from
+		// tools, so plumb them explicitly). Built only when a tool declares one — otherwise
+		// undefined, so real providers and the common no-hint case carry zero overhead.
+		let cannedHints: Map<string, CannedToolHints> | undefined;
+		for (const t of toolDefs) {
+			if (t.cannedExamples || t.cannedTriggers) {
+				cannedHints ??= new Map();
+				cannedHints.set(t.name!, { examples: t.cannedExamples, triggers: t.cannedTriggers });
+			}
+		}
+
 		const configs = Array.isArray(this.modelConfig) ? this.modelConfig : this.modelConfig ? [this.modelConfig] : [];
 		let resolvedConfig: ModelConfig | undefined;
 		for (const config of configs) {
@@ -355,7 +558,7 @@ export class AgentBase<TContext = DefaultToolContext> extends Scope {
 			const tried = configs.map(c => `${c.provider}${c.modelId ? ` (${c.modelId})` : ''}`).join(', ');
 			throw blocksAgentError(AgentErrors.ModelUnavailable, `No model available. Tried: ${tried}. Check logs for details.`);
 		}
-		const model = await createStrandsModel(resolvedConfig, this.log);
+		const model = await createStrandsModel(resolvedConfig, this.log, cannedHints);
 
 		// SessionManager restores/saves agent state across invocations.
 		// undefined when no conversationId (inference-only calls — no state to persist).
@@ -418,11 +621,17 @@ export class AgentBase<TContext = DefaultToolContext> extends Scope {
 	/**
 	 * Submit a message to the agent. Returns immediately with a channelId.
 	 *
-	 * Flow: stream() → AsyncJob.submit() → returns { channelId }
-	 * The AsyncJob consumer calls runAgent() separately.
-	 * Chunks are published to Realtime on the returned channelId.
+	 * Flow: stream() → dispatchTurn() → returns { channelId }
+	 * dispatchTurn runs the loop where the compute lives (in-process locally; on the AgentCore
+	 * Runtime on AWS) and publishes chunks to Realtime on the returned channelId.
 	 *
 	 * Subscribe to chunks via result.channel, or await result.complete() for the final response.
+	 *
+	 * Errors surface on two paths. Once the turn is dispatched, loop failures arrive as an `error`
+	 * chunk on the channel (and reject `complete()`). A failure to *dispatch* the turn — e.g. on AWS
+	 * when the AgentCore Runtime can't be invoked (unresolved runtime ARN, or an `InvokeAgentRuntime`
+	 * error) — rejects this `stream()` call itself rather than reaching the channel. Always `await`
+	 * `stream()` so a dispatch failure isn't lost.
 	 */
 	async stream(message: string, options?: StreamOptions<TContext>): Promise<AgentStreamResult> {
 		const conversationId = options?.conversationId;
@@ -430,7 +639,7 @@ export class AgentBase<TContext = DefaultToolContext> extends Scope {
 		if (!options?.userId && !this.config.inferenceOnly) throw blocksAgentError(AgentErrors.PersistenceRequired, 'userId is required when persistence is enabled. Pass it via options.userId.');
 		const userId = options?.userId ?? 'anonymous';
 		const context = this.resolveContext(options?.context);
-		await this.job.submit({ message, conversationId, channelId, userId, context });
+		await this.dispatchTurn({ message, conversationId, channelId, userId, context });
 		return {
 			channelId,
 			/** Realtime channel handle — subscribe to streaming chunks or return to client as Transferable. */
@@ -457,8 +666,12 @@ export class AgentBase<TContext = DefaultToolContext> extends Scope {
 
 	/**
 	 * Resume an interrupted agent with user's responses.
-	 * Submits a new AsyncJob that loads the session and continues from the interrupt point.
+	 * Dispatches a new turn that loads the session and continues from the interrupt point.
 	 * Chunks are published to the same channelId — use the existing subscription or call complete() again to wait for the result.
+	 *
+	 * Like `stream()`, errors surface on two paths: loop failures arrive as an `error` chunk on the
+	 * channel once the turn is dispatched, while a failure to *dispatch* (e.g. on AWS when the AgentCore
+	 * Runtime can't be invoked) rejects this `resume()` call itself. Always `await` it.
 	 */
 	async resume(channelId: string, responses: Array<InterruptResponse>, options?: { conversationId?: string; userId?: string; context?: TContext }): Promise<void> {
 		if (!responses.length) throw blocksAgentError(AgentErrors.InterruptRequired, 'resume() requires at least one interrupt response.');
@@ -493,7 +706,7 @@ export class AgentBase<TContext = DefaultToolContext> extends Scope {
 			response: r.response != null ? String(r.response) : r.approved ? (r.trust ? 'trust' : 'yes') : 'no',
 		}));
 		const context = this.resolveContext(options?.context);
-		await this.job.submit({ message: '', conversationId, channelId, userId, resume: true, interruptResponses: translated, context });
+		await this.dispatchTurn({ message: '', conversationId, channelId, userId, interruptResponses: translated, context });
 	}
 
 	/**

package/src/agentcore-bundle.test.ts

@@ -0,0 +1,52 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Unit coverage for the synth-time AgentCore co-bundle (`bundleAgentCoreAsset`).
+ *
+ * The CDK tests bypass this path (they pass a pre-built `agentcoreAssetPath`), so without this
+ * test the intricate esbuild co-bundle — the CJS banner, the `import.meta.url` shim, the `_deps/`
+ * dynamic-require copy, and the `{"type":"commonjs"}` marker — is only ever exercised by a sandbox
+ * e2e deploy. This runs the real bundler over a trivial fixture backend and asserts the asset's
+ * structure, so regressions in the bundle shape fail in CI rather than silently at deploy time.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, readdirSync, existsSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { bundleAgentCoreAsset } from './agentcore-bundle.js';
+
+test('bundleAgentCoreAsset co-bundles a backend into a CJS AgentCore asset', () => {
+	const workDir = mkdtempSync(join(tmpdir(), 'bb-agent-bundle-'));
+	try {
+		// A trivial backend module — bundling is static, so it only needs to be a resolvable
+		// module the generated entry can `import()` by absolute path.
+		const backendPath = join(workDir, 'backend.js');
+		writeFileSync(backendPath, 'export const __fixture = true;\n');
+
+		const outDir = join(workDir, 'asset');
+		mkdirSync(outDir, { recursive: true });
+
+		const result = bundleAgentCoreAsset(backendPath, outDir);
+		assert.strictEqual(result, outDir, 'returns the output directory');
+
+		// main.js — the CJS bundle, with the harness banner (createRequire shim + _resolveFilename patch).
+		const mainPath = join(outDir, 'main.js');
+		assert.ok(existsSync(mainPath), 'emits main.js');
+		const main = readFileSync(mainPath, 'utf-8');
+		assert.ok(main.length > 0, 'main.js is non-empty');
+		assert.ok(main.includes('_resolveFilename'), 'main.js carries the _deps resolver banner');
+		assert.ok(main.includes('importMetaUrl'), 'main.js carries the import.meta.url shim');
+
+		// package.json — forces Node to treat the .js bundle as CommonJS.
+		assert.strictEqual(readFileSync(join(outDir, 'package.json'), 'utf-8'), '{"type":"commonjs"}');
+
+		// _deps/ — the harness's dynamic-require closure copied alongside the bundle.
+		const depsDir = join(outDir, '_deps');
+		assert.ok(existsSync(depsDir), 'emits the _deps/ dynamic-require dir');
+		assert.ok(readdirSync(depsDir).length > 0, '_deps/ contains the copied packages');
+	} finally {
+		rmSync(workDir, { recursive: true, force: true });
+	}
+});