@aws-blocks/bb-agent 0.3.4 → 0.4.0

package/dist/agent.js

@@ -3,28 +3,47 @@
 import { Scope, registerSdkIdentifiers, getSdkIdentifiers } 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 { z } from 'zod';
 import { createStrandsModel, checkModelHealth } from './model-factory.js';
 import { messageSchema, conversationSchema, agentStreamChunkSchema } from './schemas.js';
 import { AgentErrors, blocksAgentError, InterruptError } from './errors.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(),
-    /** Per-call tool context, forwarded to tool invocations. JSON-serializable. */
-    context: z.any().optional(),
-});
 /** 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, value) {
+    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.
  *
@@ -44,6 +63,23 @@ function loadStrands() {
     });
     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();
+/** @internal Register a live Agent instance so the AgentCore entrypoint can find it by fullId. */
+export function registerAgentInstance(fullId, agent) {
+    agentRegistry.set(fullId, agent);
+}
+/** @internal Look up a registered Agent instance by fullId (used by the AgentCore entrypoint). */
+export function getAgentInstance(fullId) {
+    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
@@ -86,12 +122,14 @@ async function createConversationManager(config) {
 /**
  * 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 extends Scope {
     /** Developer-facing agent configuration. */
@@ -104,8 +142,6 @@ export class AgentBase extends Scope {
     messages;
     /** Realtime pub/sub — streams chunks to browser. */
     rt;
-    /** Internal async job — runs the Strands agent in a separate execution context. */
-    job;
     /** Which model provider to use. */
     modelConfig;
     /** Where to persist Strands agent state (snapshots). */
@@ -125,6 +161,8 @@ export class AgentBase 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(config.tools);
         this.modelConfig = modelConfig;
         // IDs shortened to keep S3 bucket names within the 63-char limit
@@ -145,29 +183,6 @@ export class AgentBase extends Scope {
                 chunks: Realtime.namespace(agentStreamChunkSchema),
             },
         });
-        this.job = new AsyncJob(this, 'job', {
-            schema: jobPayloadSchema,
-            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', content: '', contentType: 'text', 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 = {};
         if (this.conversations) {
             identifiers.conversationsTableName = getSdkIdentifiers(this.conversations).tableName;
@@ -178,22 +193,147 @@ export class AgentBase 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) {
+        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', content: '', contentType: 'text', 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.
+     */
+    async dispatchTurn(payload) {
+        // 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));
+        // 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: invokeTurn() → runAgent() → Strands agent.stream() → publishes chunks to Realtime BB
      *
-     * Flow: AsyncJob handler → runAgent() → Strands agent.stream() → publishes chunks to Realtime BB
-     * TODO add comments for args
+     * @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
      */
     async runAgent(message, conversationId, channelId, userId, interruptResponses, context) {
-        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;
+        const turnId = interruptResponses ? undefined : ulid();
+        const startTurnIfNew = () => {
+            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) => {
+            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) => {
+            startTurnIfNew();
+            const seen = strandsAgent.appState.get(COUNTED_TOOL_USE_IDS_KEY) ?? [];
+            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', content: message, contentType: 'text', userId, createdAt: Date.now(), metadata: '{}' });
@@ -280,6 +420,29 @@ export class AgentBase 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', content: fullText, contentType: 'text', 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;
@@ -318,6 +481,16 @@ export class AgentBase extends Scope {
                 interrupt: (params) => context.interrupt(params),
             }),
         }));
+        // 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;
+        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;
         for (const config of configs) {
@@ -330,7 +503,7 @@ export class AgentBase 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).
         const sessionManager = conversationId
@@ -388,11 +561,17 @@ export class AgentBase 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, options) {
         const conversationId = options?.conversationId;
@@ -401,7 +580,7 @@ export class AgentBase extends Scope {
             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. */
@@ -429,8 +608,12 @@ export class AgentBase 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, responses, options) {
         if (!responses.length)
@@ -467,7 +650,7 @@ export class AgentBase 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 });
     }
     /**
      * Validates the per-call tool context against `toolContextSchema` (when set) and returns it.

package/dist/agentcore-bundle.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Co-bundle the app backend + `serve()` into a self-contained AgentCore asset directory.
+ *
+ * @param backendModulePath - absolute path to the app's backend module (BlocksStack `backendCDKPath`)
+ * @param outDir - directory to write the bundle into (a stable, synth-scoped path under cdk.out)
+ * @returns `outDir` (contains `main.js`, `_deps/`, `package.json`), ready for `fromCodeAsset`.
+ *   The bundle is named `main.js` (not `agentcore-entry.js`) because AgentCore's entrypoint
+ *   validator rejects names it considers to have "multiple dots" / disallowed chars; `main.js`
+ *   matches the official @aws/agentcore CLI's convention and passes.
+ */
+export declare function bundleAgentCoreAsset(backendModulePath: string, outDir: string): string;
+//# sourceMappingURL=agentcore-bundle.d.ts.map

package/dist/agentcore-bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentcore-bundle.d.ts","sourceRoot":"","sources":["../src/agentcore-bundle.ts"],"names":[],"mappings":"AAqGA;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,iBAAiB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAkDtF"}

package/dist/agentcore-bundle.js

@@ -0,0 +1,150 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Synth-time co-bundle for the AgentCore Runtime code asset.
+ *
+ * The AgentCore process must run BOTH the developer's backend (which constructs the real
+ * Agent and its tool closures) AND bb-agent's `serve()` — from a SINGLE module graph, so
+ * the Agent instance registry (a module singleton in agent.ts) is shared. If the backend
+ * and the entrypoint were bundled separately they'd each get their own bb-agent copy, the
+ * Agent would register in one registry and the lookup would read the other, and `serve()`
+ * would fail with "No Agent registered".
+ *
+ * We esbuild-bundle a tiny generated entry that imports both from the same graph. We call
+ * `esbuild.buildSync()` DIRECTLY (not CDK's `NodejsFunction`) — that avoids the
+ * `PathNotUnderRoot` failure `NodejsFunction` hits for npm-installed packages, since direct
+ * esbuild has no projectRoot/lockfile requirement. `buildSync` because CDK synth is sync.
+ *
+ * Packaging mirrors the official `@aws/agentcore` CLI's Node CodeZip packager
+ * (lib/packaging/node.js), because the AgentCore direct-deploy base image provides ONLY the
+ * Node runtime — every dependency (including the AWS SDK) must be in the asset. Two wrinkles
+ * the CLI solves and we copy verbatim:
+ *
+ *  1. The `bedrock-agentcore` harness does `createRequire(import.meta.url); require('@fastify/sse')`
+ *     at module load. esbuild can't statically bundle those dynamic requires. So we emit CJS
+ *     (`format: 'cjs'`), shim `import.meta.url` to a real value, and prepend a banner that
+ *     patches `Module._resolveFilename` to fall back to a sibling `_deps/` dir. The dynamic
+ *     packages are copied into `_deps/` so the fallback finds them at runtime.
+ *  2. The `@aws-sdk/*` packages are pure JS and NOT in the base image, so we bundle them
+ *     (no `external`).
+ */
+import { buildSync } from 'esbuild';
+import { cpSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** bb-agent package root (dist/.. == package dir), used as esbuild's module-resolution base. */
+const PKG_ROOT = join(__dirname, '..');
+/** Sibling dir (next to the bundle) holding packages that are loaded via dynamic require(). */
+const DEPS_DIR = '_deps';
+/**
+ * Packages the `bedrock-agentcore` harness (and its Fastify plugins) load via dynamic
+ * `require()` at runtime, which esbuild leaves unbundled. Copied into `_deps/` and resolved
+ * by the `_resolveFilename` banner below. This list is taken verbatim from the official
+ * `@aws/agentcore` CLI so it stays in sync with the harness's runtime require graph.
+ */
+const DYNAMIC_REQUIRE_PACKAGES = [
+    '@fastify/sse',
+    '@fastify/websocket',
+    'duplexify',
+    'end-of-stream',
+    'fastify-plugin',
+    'inherits',
+    'once',
+    'readable-stream',
+    'safe-buffer',
+    'stream-shift',
+    'string_decoder',
+    'util-deprecate',
+    'wrappy',
+    'ws',
+];
+/**
+ * Banner prepended to the CJS bundle. First line gives ESM-style `import.meta.url` a real
+ * value (the harness calls `createRequire(import.meta.url)`); the IIFE patches Node's module
+ * resolver so a failed `require('X')` retries against `__dirname/_deps/X` (reading that
+ * package's `main` from its package.json). Byte-for-byte the CLI's banner.
+ */
+const CJS_BANNER = 'const importMetaUrl = require("url").pathToFileURL(__filename).href;' +
+    '(function(){var M=require("module"),p=require("path"),f=require("fs"),d=p.join(__dirname,"_deps"),o=M._resolveFilename;' +
+    'M._resolveFilename=function(r,P,i,O){try{return o.call(this,r,P,i,O)}catch(e){' +
+    'var dp=p.join(d,r);if(f.existsSync(dp)){var pk=p.join(dp,"package.json");' +
+    'if(f.existsSync(pk)){var m=JSON.parse(f.readFileSync(pk,"utf8")).main||"index.js";return p.resolve(dp,m)}' +
+    'return p.resolve(dp,"index.js")}throw e}};})();';
+/** Copy each dynamic-require package into `<outDir>/_deps/<pkg>`, resolving via bb-agent's
+ * module graph so hoisted (monorepo) and nested installs both work. */
+function copyDynamicDeps(outDir) {
+    const require = createRequire(join(PKG_ROOT, 'noop.js'));
+    for (const pkg of DYNAMIC_REQUIRE_PACKAGES) {
+        let pkgDir;
+        try {
+            // Resolve the package's own package.json, then take its directory.
+            pkgDir = dirname(require.resolve(`${pkg}/package.json`));
+        }
+        catch {
+            // Not installed / not resolvable from here — skip; the runtime fallback only
+            // needs the packages actually reached by the harness's require graph.
+            continue;
+        }
+        if (existsSync(pkgDir)) {
+            cpSync(pkgDir, join(outDir, DEPS_DIR, pkg), { recursive: true });
+        }
+    }
+}
+/**
+ * Co-bundle the app backend + `serve()` into a self-contained AgentCore asset directory.
+ *
+ * @param backendModulePath - absolute path to the app's backend module (BlocksStack `backendCDKPath`)
+ * @param outDir - directory to write the bundle into (a stable, synth-scoped path under cdk.out)
+ * @returns `outDir` (contains `main.js`, `_deps/`, `package.json`), ready for `fromCodeAsset`.
+ *   The bundle is named `main.js` (not `agentcore-entry.js`) because AgentCore's entrypoint
+ *   validator rejects names it considers to have "multiple dots" / disallowed chars; `main.js`
+ *   matches the official @aws/agentcore CLI's convention and passes.
+ */
+export function bundleAgentCoreAsset(backendModulePath, outDir) {
+    // Generated entry: load config, import the backend (constructs + registers the Agent),
+    // then serve. `resolveDir` = bb-agent package root so `@aws-blocks/*` and this package's
+    // own `serve` resolve via node_modules; the backend is imported by absolute PATH (esbuild
+    // resolves paths, not file:// URLs) so it's bundled into the SAME graph and its
+    // `@aws-blocks/*` deps dedupe to one instance.
+    // Wrapped in an async IIFE (not top-level await) because the bundle is emitted as CJS,
+    // which does not support top-level await.
+    const entrySource = [
+        "import { loadConfigToProcessEnv } from '@aws-blocks/core';",
+        "import { serve } from '@aws-blocks/bb-agent/agentcore';",
+        '(async () => {',
+        '  await loadConfigToProcessEnv();',
+        `  await import(${JSON.stringify(backendModulePath)});`,
+        '  serve();',
+        '})();',
+    ].join('\n');
+    mkdirSync(outDir, { recursive: true });
+    buildSync({
+        stdin: {
+            contents: entrySource,
+            resolveDir: PKG_ROOT,
+            sourcefile: '__agentcore_entry.mjs',
+            loader: 'js',
+        },
+        outfile: join(outDir, 'main.js'),
+        bundle: true,
+        platform: 'node',
+        target: 'node22',
+        // CJS (not ESM) so the harness's createRequire + our _resolveFilename patch work.
+        format: 'cjs',
+        minify: true,
+        // Resolve @aws-blocks/* (and the backend's BB constructions) to their AWS-runtime
+        // variants, exactly as core bundles the Lambda handler.
+        conditions: ['aws-runtime', 'node'],
+        banner: { js: CJS_BANNER },
+        // Give ESM `import.meta.url` (used by the harness) a real value under CJS output.
+        define: { 'import.meta.url': 'importMetaUrl' },
+    });
+    // `{"type":"commonjs"}` so Node treats the .js bundle as CJS regardless of any ambient
+    // "type":"module" in a parent package.json.
+    writeFileSync(join(outDir, 'package.json'), '{"type":"commonjs"}');
+    // Ship the harness's dynamic-require closure alongside the bundle.
+    copyDynamicDeps(outDir);
+    return outDir;
+}

package/dist/agentcore-bundle.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=agentcore-bundle.test.d.ts.map

package/dist/agentcore-bundle.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentcore-bundle.test.d.ts","sourceRoot":"","sources":["../src/agentcore-bundle.test.ts"],"names":[],"mappings":""}

package/dist/agentcore-bundle.test.js

@@ -0,0 +1,46 @@
+// 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 });
+    }
+});