@aws-blocks/bb-agent 0.3.4 → 0.4.0

package/src/providers/canned.ts

@@ -17,11 +17,18 @@
 import { Model } from '@strands-agents/sdk';
 import type { Message, ModelStreamEvent, StreamOptions } from '@strands-agents/sdk';
 import { ToolResultBlock } from '@strands-agents/sdk';
+import type { CannedToolHints } from '../types.js';
 
 interface CannedConfig {
 	modelId: string;
 }
 
+interface CannedProviderOptions {
+	modelId?: string;
+	/** Per-tool hints (examples, triggers) keyed by tool name. */
+	hints?: Map<string, CannedToolHints>;
+}
+
 const CANNED_RESPONSES: Record<string, string> = {
 	weather: 'The weather is 22°C and sunny. [canned response]',
 	order: 'Order #12345 has been shipped and is on its way. [canned response]',
@@ -30,28 +37,48 @@ const CANNED_RESPONSES: Record<string, string> = {
 
 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: string): string {
 	const lower = prompt.toLowerCase();
 	for (const [keyword, response] of Object.entries(CANNED_RESPONSES)) {
-		if (lower.includes(keyword)) return response;
+		if (promptMentionsWord(lower, keyword)) return response;
 	}
 	return DEFAULT_RESPONSE;
 }
 
+const wordPatternCache = new Map<string, RegExp>();
+
 /**
- * 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: string): RegExp {
+	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: string, word: string): boolean {
-	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: string, toolSpecs?: { name: string }[]): string[] {
+function findAllToolMatches(prompt: string, toolSpecs?: { name: string }[], hints?: Map<string, CannedToolHints>): string[] {
 	if (!toolSpecs?.length) return [];
 	const lower = prompt.toLowerCase();
 	return toolSpecs.filter(t => {
@@ -60,7 +87,15 @@ function findAllToolMatches(prompt: string, toolSpecs?: { name: string }[]): str
 		// 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);
 }
 
@@ -87,45 +122,107 @@ function getToolResultText(messages: Message[]): string {
 	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: any): any {
+	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: any): any {
 	if (!schema || typeof schema !== 'object') return {};
-	if (schema.type === 'object' && schema.properties) {
-		const result: Record<string, any> = {};
-		for (const [key, prop] of Object.entries(schema.properties) as [string, any][]) {
-			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: unknown[] = Array.isArray(schema.required) ? schema.required : [];
+	const result: Record<string, any> = {};
+	for (const [key, prop] of Object.entries(schema.properties) as [string, any][]) {
+		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;
 }
 
-/** Look up a tool's inputSchema from toolSpecs and generate placeholder input. */
-function getToolInput(toolName: string, toolSpecs?: { name: string; inputSchema?: any }[]): string {
+const warnedExampleKeys = new Set<string>();
+
+/**
+ * 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: string, examples: Record<string, unknown>, inputSchema?: any): void {
+	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, shallow-merging
+ * any `cannedExamples` (from hints) on top so realistic values win over generated placeholders.
+ */
+function getToolInput(toolName: string, toolSpecs?: { name: string; inputSchema?: any }[], hints?: Map<string, CannedToolHints>): string {
 	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<CannedConfig> {
 	private config: CannedConfig;
+	private hints: Map<string, CannedToolHints>;
 
-	constructor(config?: Partial<CannedConfig>) {
+	constructor(options?: CannedProviderOptions) {
 		super();
-		this.config = { modelId: config?.modelId ?? 'canned-mock' };
+		this.config = { modelId: options?.modelId ?? 'canned-mock' };
+		this.hints = options?.hints ?? new Map();
 	}
 
 	updateConfig(config: Partial<CannedConfig>): void {
@@ -150,7 +247,7 @@ export class CannedProvider extends Model<CannedConfig> {
 		}
 
 		// 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;
@@ -161,8 +258,6 @@ export class CannedProvider extends Model<CannedConfig> {
 			return;
 		}
 
-		// Default: keyword-based text response
-
 		// Default: keyword-based text response
 		yield* this.emitText(matchResponse(prompt));
 	}
@@ -185,7 +280,7 @@ export class CannedProvider extends Model<CannedConfig> {
 		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' };
@@ -197,7 +292,7 @@ export class CannedProvider extends Model<CannedConfig> {
 		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/src/types.ts

@@ -85,7 +85,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
@@ -106,6 +138,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;
 }
@@ -175,6 +213,31 @@ 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[];
 }
 
 /**

package/src/version.ts

@@ -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';