@aws-blocks/bb-agent 0.3.4 → 0.4.0

package/dist/providers/canned.js

@@ -19,27 +19,45 @@ const CANNED_RESPONSES = {
     help: 'I can help you with weather, orders, and general questions. [canned response]',
 };
 const DEFAULT_RESPONSE = 'This is a canned mock response. No real model was called. [canned]';
+/**
+ * Pick a canned text response by keyword, matched on word boundaries for the same reason
+ * tool matching is: substring matching fired `order` inside "reorder" and `help` inside
+ * "helper", the same false-positive class the tool matcher avoids.
+ */
 function matchResponse(prompt) {
     const lower = prompt.toLowerCase();
     for (const [keyword, response] of Object.entries(CANNED_RESPONSES)) {
-        if (lower.includes(keyword))
+        if (promptMentionsWord(lower, keyword))
             return response;
     }
     return DEFAULT_RESPONSE;
 }
+const wordPatternCache = new Map();
 /**
- * Match a single word against the prompt on word boundaries (case-insensitive).
+ * Compile a word-boundary matcher for a word or phrase, cached by phrase.
  * Uses `\b...\b` rather than substring `includes()` so a tool word like "cat"
  * (from `getCat`) is NOT triggered by an unrelated word like "category", and
- * "pass" (from `getPass`) is not triggered by "password". The word is regex-
- * escaped so punctuation in tool names can't break the pattern.
+ * "pass" (from `getPass`) is not triggered by "password". Regex metacharacters are
+ * escaped so punctuation in tool names can't break the pattern, and internal
+ * whitespace becomes `\s+` so a multi-word phrase tolerates irregular spacing.
+ * Compiled patterns are cached because matching re-runs for every tool on every
+ * `stream()` call, and the key space is bounded by the agent's tool and trigger set.
  */
+function wordBoundaryPattern(phrase) {
+    let pattern = wordPatternCache.get(phrase);
+    if (!pattern) {
+        const escaped = phrase.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\s+/g, '\\s+');
+        pattern = new RegExp(`\\b${escaped}\\b`);
+        wordPatternCache.set(phrase, pattern);
+    }
+    return pattern;
+}
+/** Match a word against an already-lowercased prompt on word boundaries. */
 function promptMentionsWord(lowerPrompt, word) {
-    const escaped = word.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    return new RegExp(`\\b${escaped}\\b`).test(lowerPrompt);
+    return wordBoundaryPattern(word).test(lowerPrompt);
 }
 /** Find ALL tools mentioned in the prompt (for parallel tool calls). */
-function findAllToolMatches(prompt, toolSpecs) {
+function findAllToolMatches(prompt, toolSpecs, hints) {
     if (!toolSpecs?.length)
         return [];
     const lower = prompt.toLowerCase();
@@ -50,7 +68,16 @@ function findAllToolMatches(prompt, toolSpecs) {
         // Split camelCase into words (getWeather -> "get weather") and match each
         // on word boundaries. Skip short words (<=2 chars) to avoid noise.
         const words = t.name.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase().split(' ');
-        return words.some(w => w.length > 2 && promptMentionsWord(lower, w));
+        if (words.some(w => w.length > 2 && promptMentionsWord(lower, w)))
+            return true;
+        // Extra trigger keywords declared via `cannedTriggers`. Single and multi-word triggers
+        // both match on word boundaries (consistent with tool-name matching), so "log in" is not
+        // triggered by "backlog in" and internal whitespace is flexible (matches one-or-more spaces).
+        const triggers = hints?.get(t.name)?.triggers;
+        return triggers?.some(tr => {
+            const low = tr.trim().toLowerCase();
+            return low ? wordBoundaryPattern(low).test(lower) : false;
+        }) ?? false;
     }).map(t => t.name);
 }
 /** Check if the last message contains a tool result — means we're in the follow-up after a tool call. */
@@ -75,49 +102,108 @@ function getToolResultText(messages) {
     }
     return results.join(' | ');
 }
+/** Sentinel for a property whose shape carries no usable signal (distinct from a legitimate `null`/`0`/`false`). */
+const NO_PLACEHOLDER = Symbol('no-placeholder');
+/**
+ * Resolve one property's placeholder value, or `NO_PLACEHOLDER` if its shape gives no signal.
+ * Order matters: an authored `default` (from Zod `.default()`) is the most realistic value, then
+ * a fixed `const`/`enum` member, then a union variant, then a per-type placeholder. `!== undefined`
+ * rather than truthiness so a `default` of `0`, `false`, or `''` is honored.
+ */
+function placeholderForProperty(prop) {
+    if (prop?.default !== undefined)
+        return prop.default;
+    if (prop?.const !== undefined)
+        return prop.const;
+    if (prop?.enum?.length)
+        return prop.enum[0];
+    // Zod unions (`z.union`, `z.discriminatedUnion`) surface as anyOf/oneOf; any one
+    // satisfying variant is enough for a mock, so take the first that resolves.
+    const variants = prop?.anyOf ?? prop?.oneOf;
+    if (Array.isArray(variants)) {
+        for (const variant of variants) {
+            const resolved = placeholderForProperty(variant);
+            if (resolved !== NO_PLACEHOLDER)
+                return resolved;
+        }
+    }
+    switch (prop?.type) {
+        case 'string': return 'sample';
+        case 'number':
+        case 'integer': return 1;
+        case 'boolean': return true;
+        case 'array': return [];
+        case 'object': return generatePlaceholderInput(prop);
+        default: return NO_PLACEHOLDER;
+    }
+}
 /** Generate placeholder input from a JSON Schema. Produces values that pass validation. */
 function generatePlaceholderInput(schema) {
     if (!schema || typeof schema !== 'object')
         return {};
-    if (schema.type === 'object' && schema.properties) {
-        const result = {};
-        for (const [key, prop] of Object.entries(schema.properties)) {
-            if (prop.type === 'string') {
-                if (prop.enum?.length)
-                    result[key] = prop.enum[0];
-                else
-                    result[key] = 'sample';
-            }
-            else if (prop.type === 'number' || prop.type === 'integer') {
-                result[key] = 1;
-            }
-            else if (prop.type === 'boolean') {
-                result[key] = true;
-            }
-            else if (prop.type === 'array') {
-                result[key] = [];
-            }
-            else if (prop.type === 'object') {
-                result[key] = generatePlaceholderInput(prop);
-            }
+    if (schema.type !== 'object' || !schema.properties)
+        return {};
+    const required = Array.isArray(schema.required) ? schema.required : [];
+    const result = {};
+    for (const [key, prop] of Object.entries(schema.properties)) {
+        const value = placeholderForProperty(prop);
+        if (value !== NO_PLACEHOLDER) {
+            result[key] = value;
+        }
+        else if (required.includes(key)) {
+            // An unrecognized shape (untyped, or a union of only unrecognized variants) yields no
+            // placeholder. Omitting a *required* field makes the emitted call fail validation before
+            // the tool ever runs, so fall back to a string. Optional fields stay omitted: absence is
+            // valid there, and inventing a wrong-typed value would break calls that used to work.
+            result[key] = 'sample';
         }
-        return result;
     }
-    return {};
+    return result;
+}
+const warnedExampleKeys = new Set();
+/**
+ * Warn (once per tool+field) when a `cannedExamples` key isn't a field of the tool's
+ * inputSchema — almost always a typo in the hint. Only ever reached through the canned
+ * provider, which is local-dev-only, so this never warns in a deployed agent. The value
+ * is still merged through and nothing throws: a bad hint must not break local dev.
+ * Skipped when the schema exposes no `properties`, where unknown keys are unknowable.
+ */
+function warnUnknownExampleKeys(toolName, examples, inputSchema) {
+    const properties = inputSchema?.properties;
+    if (!properties)
+        return;
+    for (const key of Object.keys(examples)) {
+        if (key in properties)
+            continue;
+        const seen = `${toolName}.${key}`;
+        if (warnedExampleKeys.has(seen))
+            continue;
+        warnedExampleKeys.add(seen);
+        console.warn(`[canned] cannedExamples for tool "${toolName}" sets "${key}", which is not a field of its ` +
+            `parameters schema (${Object.keys(properties).join(', ') || 'none'}). Check for a typo — the value is still sent.`);
+    }
 }
-/** Look up a tool's inputSchema from toolSpecs and generate placeholder input. */
-function getToolInput(toolName, toolSpecs) {
+/**
+ * Look up a tool's inputSchema from toolSpecs and generate placeholder input, shallow-merging
+ * any `cannedExamples` (from hints) on top so realistic values win over generated placeholders.
+ */
+function getToolInput(toolName, toolSpecs, hints) {
     const spec = toolSpecs?.find(t => t.name === toolName);
-    if (!spec?.inputSchema)
-        return '{}';
-    return JSON.stringify(generatePlaceholderInput(spec.inputSchema));
+    const base = spec?.inputSchema ? generatePlaceholderInput(spec.inputSchema) : {};
+    const examples = hints?.get(toolName)?.examples;
+    if (!examples)
+        return JSON.stringify(base);
+    warnUnknownExampleKeys(toolName, examples, spec?.inputSchema);
+    return JSON.stringify({ ...base, ...examples });
 }
 let toolCallCounter = 0;
 export class CannedProvider extends Model {
     config;
-    constructor(config) {
+    hints;
+    constructor(options) {
         super();
-        this.config = { modelId: config?.modelId ?? 'canned-mock' };
+        this.config = { modelId: options?.modelId ?? 'canned-mock' };
+        this.hints = options?.hints ?? new Map();
     }
     updateConfig(config) {
         Object.assign(this.config, config);
@@ -137,7 +223,7 @@ export class CannedProvider extends Model {
             return;
         }
         // Check if prompt mentions tool names — trigger tool call(s)
-        const toolMatches = findAllToolMatches(prompt, options?.toolSpecs);
+        const toolMatches = findAllToolMatches(prompt, options?.toolSpecs, this.hints);
         if (toolMatches.length > 1) {
             yield* this.emitParallelToolCalls(toolMatches, options?.toolSpecs);
             return;
@@ -148,7 +234,6 @@ export class CannedProvider extends Model {
             return;
         }
         // Default: keyword-based text response
-        // Default: keyword-based text response
         yield* this.emitText(matchResponse(prompt));
     }
     /** Emit a text response as ModelStreamEvents. */
@@ -168,7 +253,7 @@ export class CannedProvider extends Model {
         for (const toolName of toolNames) {
             const toolUseId = `canned-tool-${++toolCallCounter}`;
             yield { type: 'modelContentBlockStartEvent', start: { type: 'toolUseStart', name: toolName, toolUseId } };
-            yield { type: 'modelContentBlockDeltaEvent', delta: { type: 'toolUseInputDelta', input: getToolInput(toolName, toolSpecs) } };
+            yield { type: 'modelContentBlockDeltaEvent', delta: { type: 'toolUseInputDelta', input: getToolInput(toolName, toolSpecs, this.hints) } };
             yield { type: 'modelContentBlockStopEvent' };
         }
         yield { type: 'modelMessageStopEvent', stopReason: 'toolUse' };
@@ -179,7 +264,7 @@ export class CannedProvider extends Model {
         const toolUseId = `canned-tool-${++toolCallCounter}`;
         yield { type: 'modelMessageStartEvent', role: 'assistant' };
         yield { type: 'modelContentBlockStartEvent', start: { type: 'toolUseStart', name: toolName, toolUseId } };
-        yield { type: 'modelContentBlockDeltaEvent', delta: { type: 'toolUseInputDelta', input: getToolInput(toolName, toolSpecs) } };
+        yield { type: 'modelContentBlockDeltaEvent', delta: { type: 'toolUseInputDelta', input: getToolInput(toolName, toolSpecs, this.hints) } };
         yield { type: 'modelContentBlockStopEvent' };
         yield { type: 'modelMessageStopEvent', stopReason: 'toolUse' };
         yield { type: 'modelMetadataEvent', usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 }, metrics: { latencyMs: 0 } };

package/dist/types.d.ts

@@ -78,7 +78,39 @@ export interface AgentConfig<TContext = DefaultToolContext> {
      */
     toolContextSchema?: z.ZodType<TContext>;
     conversation?: ConversationManagerConfig;
-    structuredOutput?: z.ZodType;
+    /**
+     * Safety cap on the number of **model (Bedrock) invocations per turn**.
+     *
+     * The agent runs a reason→act loop where each iteration is one model call,
+     * optionally followed by tool calls; a model call that requests no tools ends
+     * the turn. Model calls are the unit Bedrock bills for, so this is the most
+     * direct guard against a runaway agent that loops indefinitely — and because
+     * every tool round needs a model call, it transitively bounds tool loops too.
+     *
+     * When the cap is hit the turn is stopped and the client receives an `error`
+     * chunk instead of `done`. Raise it for agents that legitimately reason over
+     * many steps, or set it to `false` to disable the cap entirely. This bounds
+     * call *count*, not tokens or wall-clock — pair it with a billing/CloudWatch
+     * alarm for defense in depth.
+     *
+     * Scope: the count covers the whole turn, including across a human-in-the-loop
+     * interrupt — it is kept in the agent's session state, so `resume()` continues
+     * on the same budget rather than starting a fresh one. Must be a positive
+     * integer or `false`; anything else throws `InvalidModelConfigException`.
+     */
+    maxLlmCalls?: number | false;
+    /**
+     * Safety cap on the number of **tool calls per turn**.
+     *
+     * Bounds tool-loop runaways specifically (a turn that keeps invoking tools).
+     * Parallel tool batches count each individual call. Raise it for agents that
+     * legitimately chain many tools in a single turn, or set it to `false` to
+     * disable the cap entirely. When the cap is hit the turn is stopped and the
+     * client receives an `error` chunk instead of `done`. Like `maxLlmCalls`, the
+     * count covers the whole turn (it survives `resume()` after an interrupt) and
+     * must be a positive integer or `false`.
+     */
+    maxToolIterations?: number | false;
     /** Controls how text chunks are published to the client via Realtime.
      * - `'token'`: publish every text delta immediately
      * - `'block'` (default): buffer text and publish when a full content block completes
@@ -98,6 +130,12 @@ export interface AgentConfig<TContext = DefaultToolContext> {
      * Ignored by the mock and browser runtimes.
      */
     removalPolicy?: 'destroy' | 'retain';
+    /**
+     * @internal Pre-built AgentCore code-asset directory to use instead of co-bundling the app
+     * backend at synth. Set by unit tests and apps that pre-bundle; normal apps leave this unset
+     * and the backend is co-bundled automatically. Ignored by the mock/browser runtimes.
+     */
+    agentcoreAssetPath?: string;
     /** Optional logger for internal operations. When omitted, a default Logger at error level is created. */
     logger?: ChildLogger;
 }
@@ -171,6 +209,30 @@ export interface ToolDefinition<TContext = DefaultToolContext, TParams extends z
      * - `interrupt` — pause the agent for human input
      */
     handler: (args: ToolHandlerArgs<z.infer<TParams>, TContext>) => Promise<JSONValue>;
+    /**
+     * Local-dev only. Realistic tool input for the `canned` mock provider. Shallow-merged
+     * over the generated placeholder input (your fields win; unspecified fields fall back to
+     * schema defaults / generic placeholders). The merge is one level deep — a nested-object
+     * example replaces that whole generated sub-object rather than deep-merging into it.
+     * Ignored by the bedrock/openai providers.
+     */
+    cannedExamples?: Record<string, JSONValue>;
+    /**
+     * Local-dev only. Extra keyword phrases that make the `canned` mock provider select this
+     * tool, in addition to the tool name and its camelCase words. Single and multi-word phrases
+     * match on word boundaries (so "log in" is not triggered by "backlog in"). Ignored by the
+     * bedrock/openai providers.
+     */
+    cannedTriggers?: string[];
+}
+/**
+ * Local-dev hints for the `canned` mock provider, keyed by tool name and threaded from
+ * `ToolDefinition.cannedExamples`/`cannedTriggers` into the provider (Strands strips these
+ * fields when converting tools, so they're plumbed explicitly). Ignored by real providers.
+ */
+export interface CannedToolHints {
+    examples?: Record<string, JSONValue>;
+    triggers?: string[];
 }
 /**
  * @internal Brand applied by the per-call `tool()` factory. Not forgeable by a plain

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 export declare const BB_NAME = "Agent";
-export declare const BB_VERSION = "0.3.4";
+export declare const BB_VERSION = "0.4.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,3 @@
 // Auto-generated by scripts/generate-version.mjs — do not edit manually
 export const BB_NAME = 'Agent';
-export const BB_VERSION = '0.3.4';
+export const BB_VERSION = '0.4.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws-blocks/bb-agent",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/aws-devtools-labs/aws-blocks.git",
@@ -35,28 +35,35 @@
     "./client": {
       "types": "./dist/index.hooks.d.ts",
       "default": "./dist/index.hooks.js"
+    },
+    "./agentcore": {
+      "types": "./dist/agentcore-entry.d.ts",
+      "default": "./dist/agentcore-entry.js"
     }
   },
   "scripts": {
     "prebuild": "node ../../scripts/generate-version.mjs Agent",
     "build": "tsc --build",
-    "test": "node --test dist/index.test.js"
+    "test": "node --test dist/index.test.js && node --conditions=cdk --test dist/index.cdk.test.js && node --test dist/agentcore-bundle.test.js"
   },
   "dependencies": {
-    "@aws-blocks/bb-async-job": "^0.1.4",
-    "@aws-blocks/bb-distributed-table": "^0.1.5",
-    "@aws-blocks/bb-file-bucket": "^0.1.4",
-    "@aws-blocks/bb-logger": "^0.1.4",
-    "@aws-blocks/bb-realtime": "^0.1.4",
-    "@aws-blocks/core": "^0.2.0",
+    "@aws-blocks/bb-distributed-table": "^0.1.7",
+    "@aws-blocks/bb-file-bucket": "^0.2.0",
+    "@aws-blocks/bb-logger": "^0.1.6",
+    "@aws-blocks/bb-realtime": "^0.2.0",
+    "@aws-blocks/core": "^0.4.0",
     "@aws-sdk/client-bedrock": "^3.700.0",
+    "@aws-sdk/client-bedrock-agentcore": "^3.700.0",
     "@opentelemetry/api": "^1.9.0",
-    "@strands-agents/sdk": "~1.3.0",
+    "@strands-agents/sdk": "^1.7.0",
+    "bedrock-agentcore": "^0.4.0",
+    "esbuild": "^0.27.0",
     "openai": "^6.7.0",
     "ulid": "^2.3.0",
     "zod": "^4.1.12"
   },
   "devDependencies": {
+    "@aws-blocks/bb-lambda-compute": "^0.4.0",
     "@aws-sdk/client-bedrock-runtime": "^3.700.0",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "@types/node": "^20.0.0",

package/src/agent.aws.ts

@@ -1,15 +1,29 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+import { createHash } from 'node:crypto';
+import { getConfig } from '@aws-blocks/core';
 import type { ScopeParent } from '@aws-blocks/core';
 import type { FileBucket } from '@aws-blocks/bb-file-bucket';
+import { BedrockAgentCoreClient, InvokeAgentRuntimeCommand } from '@aws-sdk/client-bedrock-agentcore';
 import type { SnapshotStorage } from '@strands-agents/sdk';
 import { S3Storage } from '@strands-agents/sdk/session/s3-storage';
 import type { S3StorageConfig } from '@strands-agents/sdk/session/s3-storage';
-import { AgentBase } from './agent.js';
+import { AgentBase, type AgentTurnPayload } from './agent.js';
+import { AgentErrors, blocksAgentError } from './errors.js';
 import type { AgentConfig, DefaultToolContext } from './types.js';
 import { BedrockModels } from './models.js';
 
+/**
+ * AgentCore requires a `runtimeSessionId` of at least 33 characters. Conversation/channel ids
+ * are UUIDs (36 chars) in the normal path and pass through unchanged; anything shorter is hashed
+ * to a stable 64-char hex id — stable per input, so a conversation keeps routing to one warm
+ * microVM across turns/resumes.
+ */
+function toRuntimeSessionId(base: string): string {
+	return base.length >= 33 ? base : createHash('sha256').update(base).digest('hex');
+}
+
 /**
  * Builds the deployed Agent's snapshot storage, pinning S3Storage to the Lambda
  * execution region (`AWS_REGION`) so non-us-east-1 deploys use the correct regional
@@ -24,7 +38,50 @@ export function createDeployedSnapshotStorage(
 }
 
 export class Agent<TContext = DefaultToolContext> extends AgentBase<TContext> {
+	private _agentCore?: BedrockAgentCoreClient;
+
 	constructor(scope: ScopeParent, id: string, config: AgentConfig<TContext>) {
 		super(scope, id, config, config.model?.deployed ?? BedrockModels.BALANCED, createDeployedSnapshotStorage);
 	}
+
+	/**
+	 * Run the turn on the AgentCore Runtime that hosts this agent's loop.
+	 *
+	 * Returns as soon as the runtime has ACCEPTED the turn: `agentcore-entry` starts `runAgent()`
+	 * as a background async task (which streams chunks to Realtime under the runtime's own role)
+	 * and responds immediately, so this `InvokeAgentRuntime` call does NOT hold the connection for
+	 * the turn's duration — the loop keeps running server-side for up to the 8h session lifetime.
+	 * `runtimeSessionId` is keyed by conversationId so a conversation's turns/resumes reuse one
+	 * warm microVM.
+	 *
+	 * @internal Internal compute seam; not customer API.
+	 */
+	protected override async dispatchTurn(payload: AgentTurnPayload<TContext>): Promise<void> {
+		const runtimeArnKey = `BB_AGENT_${this.fullId}_RUNTIME_ARN`;
+		const runtimeArn = await getConfig(runtimeArnKey);
+		if (!runtimeArn) {
+			throw blocksAgentError(
+				AgentErrors.StreamFailed,
+				`AgentCore Runtime ARN not found (config key ${runtimeArnKey}). Ensure the app build produced the AgentCore asset and the stack deployed the Runtime.`,
+			);
+		}
+		this._agentCore ??= new BedrockAgentCoreClient({});
+		const body = {
+			prompt: payload.message,
+			channelId: payload.channelId,
+			conversationId: payload.conversationId,
+			userId: payload.userId,
+			interruptResponses: payload.interruptResponses,
+			context: payload.context,
+		};
+		await this._agentCore.send(
+			new InvokeAgentRuntimeCommand({
+				agentRuntimeArn: runtimeArn,
+				runtimeSessionId: toRuntimeSessionId(payload.conversationId ?? payload.channelId),
+				contentType: 'application/json',
+				accept: 'application/json',
+				payload: new TextEncoder().encode(JSON.stringify(body)),
+			}),
+		);
+	}
 }