@aws-blocks/bb-agent 0.1.0

package/dist/model-factory.d.ts

@@ -0,0 +1,26 @@
+import { type Model } from '@strands-agents/sdk';
+import type { BaseModelConfig } from '@strands-agents/sdk';
+import type { ChildLogger } from '@aws-blocks/bb-logger';
+import type { ModelConfig } from './types.js';
+/**
+ * Checks if a model endpoint is available and the specified model exists.
+ * Verifies endpoint/model availability only. Does not guarantee EULA acceptance or feature support (e.g. tool calling).
+ * Even calls to verified models can fail at invocation time (e.g. legacy models, quota limits) — always check error logs.
+ * For openai-api: pings GET /v1/models and checks if modelId is in the list.
+ * For bedrock: verifies model availability via @aws-sdk/client-bedrock (free, no inference cost).
+ * For canned: always returns true.
+ */
+/** @internal Injectable client interface for testing. */
+export interface BedrockHealthClient {
+    send(command: any): Promise<any>;
+}
+export declare function checkModelHealth(config: ModelConfig, log: ChildLogger, _testClient?: BedrockHealthClient): Promise<boolean>;
+/**
+ * Maps Blocks' ModelConfig to the corresponding Strands model provider.
+ * The developer configures one unified ModelConfig shape — this factory
+ * translates it to BedrockModel, OpenAIModel, or CannedProvider internally.
+ *
+ * @see https://strandsagents.com/docs/user-guide/concepts/model-providers/
+ */
+export declare function createStrandsModel(config?: ModelConfig, log?: ChildLogger): Promise<Model<BaseModelConfig>>;
+//# sourceMappingURL=model-factory.d.ts.map

package/dist/model-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-factory.d.ts","sourceRoot":"","sources":["../src/model-factory.ts"],"names":[],"mappings":"AAGA,OAAO,EAAgB,KAAK,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAK9C;;;;;;;GAOG;AACH,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IACnC,IAAI,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;CACjC;AAED,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,EAAE,WAAW,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC,CA6IjI;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,GAAG,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,CAkDjH"}

package/dist/model-factory.js

@@ -0,0 +1,197 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { BedrockModel } from '@strands-agents/sdk';
+import { OpenAIModel } from '@strands-agents/sdk/models/openai';
+import { CannedProvider } from './providers/canned.js';
+import { ThrowingProvider } from './providers/throwing.js';
+import { AgentErrors, blocksAgentError } from './errors.js';
+export async function checkModelHealth(config, log, _testClient) {
+    if (!config || config.provider === 'canned') {
+        log.info('Using canned provider (local mock, no real model)');
+        return true;
+    }
+    if (config.provider === 'throwing') {
+        log.info('Using throwing provider (test-only)');
+        return true;
+    }
+    log.info(`Checking model health: ${config.provider}${config.modelId ? ` (${config.modelId})` : ''}`);
+    if (config.provider === 'bedrock') {
+        const isCrossRegionProfile = config.modelId && /^(us-gov|us|eu|apac)\./.test(config.modelId);
+        const getClient = async () => {
+            if (_testClient)
+                return _testClient;
+            const { BedrockClient } = await import('@aws-sdk/client-bedrock');
+            return new BedrockClient({});
+        };
+        // Cross-region inference profiles use GetInferenceProfile instead of GetFoundationModel.
+        if (isCrossRegionProfile) {
+            try {
+                const client = await getClient();
+                const command = _testClient
+                    ? { inferenceProfileIdentifier: config.modelId }
+                    : new (await import('@aws-sdk/client-bedrock')).GetInferenceProfileCommand({ inferenceProfileIdentifier: config.modelId });
+                const res = await client.send(command);
+                if (res.inferenceProfileName) {
+                    log.info(`Inference profile '${config.modelId}' available`);
+                    return true;
+                }
+                return false;
+            }
+            catch (err) {
+                const e = err;
+                log.warn(`Inference profile health check failed for '${config.modelId}': ${e.name ?? e.message}`, { provider: config.provider, modelId: config.modelId });
+                return false;
+            }
+        }
+        try {
+            const client = await getClient();
+            const command = _testClient
+                ? { modelIdentifier: config.modelId }
+                : new (await import('@aws-sdk/client-bedrock')).GetFoundationModelCommand({ modelIdentifier: config.modelId });
+            const res = await client.send(command);
+            if (res.modelDetails) {
+                log.info(`Bedrock model '${config.modelId}' exists in catalog`);
+                return true;
+            }
+            return false;
+        }
+        catch (err) {
+            const e = err;
+            // GetFoundationModel throws for unknown models (ValidationException / ResourceNotFoundException).
+            if (e.name === 'ValidationException' || e.name === 'ResourceNotFoundException') {
+                try {
+                    const client = await getClient();
+                    const listCommand = _testClient
+                        ? {}
+                        : new (await import('@aws-sdk/client-bedrock')).ListFoundationModelsCommand({});
+                    const list = await client.send(listCommand);
+                    const available = list.modelSummaries?.map((m) => m.modelId).filter(Boolean) ?? [];
+                    log.warn(`Bedrock model '${config.modelId}' not found. Available: ${available.slice(0, 10).join(', ')}${available.length > 10 ? ` (+${available.length - 10} more)` : ''}`);
+                }
+                catch {
+                    log.warn(`Bedrock model '${config.modelId}' not found. Could not list available models.`);
+                }
+                return false;
+            }
+            log.warn(`Bedrock health check failed: ${e.name ?? e.message}. Verify AWS credentials are configured.`, { provider: config.provider, modelId: config.modelId });
+            return false;
+        }
+    }
+    if (config.provider === 'openai-api') {
+        const endpoint = config.endpoint ?? 'https://api.openai.com/v1';
+        const baseUrl = endpoint.endsWith('/') ? endpoint.slice(0, -1) : endpoint;
+        const url = `${baseUrl}/models`;
+        const resolvedKey = typeof config.apiKey === 'function'
+            ? await config.apiKey()
+            : config.apiKey ?? process.env.OPENAI_API_KEY;
+        // 1. Check if endpoint is reachable
+        let res;
+        try {
+            res = await fetch(url, {
+                method: 'GET',
+                headers: resolvedKey ? { Authorization: `Bearer ${resolvedKey}` } : {},
+                signal: AbortSignal.timeout(3000),
+            });
+        }
+        catch (err) {
+            log.warn(`Endpoint unreachable: ${baseUrl}`, { provider: config.provider, error: err.message });
+            return false;
+        }
+        if (!res.ok) {
+            log.warn(`Endpoint returned HTTP ${res.status}: ${baseUrl}`, { provider: config.provider, status: res.status });
+            return false;
+        }
+        // 2. Endpoint is up — check if specified model exists
+        if (!config.modelId)
+            return true;
+        // Parse the model list defensively. A 200 response is not a guarantee of a
+        // JSON body: misconfigured proxies, captive portals, or a non-OpenAI server
+        // sharing the URL can return HTML or plain text. JSON.parse throws on such
+        // bodies — if that escaped, it would abort the model fallback loop in
+        // createStrandsAgent() and prevent the implicit canned fallback from ever
+        // running. Treat an unparseable response as "unhealthy" (return false) so the
+        // next candidate is tried, matching the fetch-failure handling above. Read the
+        // raw text first so we can log a short snippet of the offending body, which
+        // makes a misconfigured proxy / captive portal obvious during debugging.
+        let body;
+        let text = '';
+        try {
+            text = await res.text();
+        }
+        catch (err) {
+            log.warn(`Failed to read model-list response body: ${baseUrl}`, { provider: config.provider, error: err.message });
+            return false;
+        }
+        try {
+            body = JSON.parse(text);
+        }
+        catch (err) {
+            log.warn(`Endpoint returned a non-JSON body, make sure this is a valid OpenAI-compatible server: ${baseUrl}`, { provider: config.provider, error: err.message, bodySnippet: text.slice(0, 100) });
+            return false;
+        }
+        const availableModels = body.data?.map(m => m.id) ?? [];
+        if (availableModels.includes(config.modelId)) {
+            log.info(`Model '${config.modelId}' available at ${baseUrl}`);
+            return true;
+        }
+        // 3. Model not found — log what IS available
+        log.warn(`Model '${config.modelId}' not found at ${baseUrl}. Available: ${availableModels.join(', ') || 'none'}`, { provider: config.provider, modelId: config.modelId, availableModels });
+        return false;
+    }
+    return false;
+}
+/**
+ * Maps Blocks' ModelConfig to the corresponding Strands model provider.
+ * The developer configures one unified ModelConfig shape — this factory
+ * translates it to BedrockModel, OpenAIModel, or CannedProvider internally.
+ *
+ * @see https://strandsagents.com/docs/user-guide/concepts/model-providers/
+ */
+export async function createStrandsModel(config, log) {
+    if (!config || config.provider === 'canned')
+        return new CannedProvider();
+    // Test-only provider — throws mid-stream to verify error handling
+    if (config.provider === 'throwing') {
+        log?.warn('ThrowingProvider is only for internal test purposes');
+        return new ThrowingProvider();
+    }
+    if (config.provider === 'bedrock') {
+        if (!config.modelId) {
+            throw blocksAgentError(AgentErrors.InvalidModelConfig, "Model provider 'bedrock' requires modelId.");
+        }
+        return new BedrockModel({
+            modelId: config.modelId,
+            ...(config.inferenceConfig && {
+                temperature: config.inferenceConfig.temperature,
+                topP: config.inferenceConfig.topP,
+                maxTokens: config.inferenceConfig.maxTokens,
+                stopSequences: config.inferenceConfig.stopSequences,
+            }),
+        });
+    }
+    if (config.provider === 'openai-api') {
+        if (!config.modelId) {
+            throw blocksAgentError(AgentErrors.InvalidModelConfig, "Model provider 'openai-api' requires modelId.");
+        }
+        // Resolve apiKey: string, async function, or env var fallback
+        const apiKey = typeof config.apiKey === 'function' ? await config.apiKey() : config.apiKey;
+        if (!apiKey && !process.env.OPENAI_API_KEY) {
+            throw blocksAgentError(AgentErrors.InvalidModelConfig, "provider 'openai-api' requires apiKey or OPENAI_API_KEY environment variable.");
+        }
+        return new OpenAIModel({
+            api: 'chat',
+            apiKey: apiKey ?? '',
+            ...(config.endpoint && { clientConfig: { baseURL: config.endpoint } }),
+            modelId: config.modelId,
+            ...(config.inferenceConfig && {
+                temperature: config.inferenceConfig.temperature,
+                topP: config.inferenceConfig.topP,
+                maxTokens: config.inferenceConfig.maxTokens,
+                ...(config.inferenceConfig.stopSequences && {
+                    params: { stop: config.inferenceConfig.stopSequences },
+                }),
+            }),
+        });
+    }
+    throw blocksAgentError(AgentErrors.InvalidModelConfig, `Unknown provider: '${config.provider}'.`);
+}

package/dist/models.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Pre-configured Bedrock model presets using cross-region inference profiles.
+ * Names are capability-based so the underlying model can be upgraded without breaking user code.
+ */
+export declare const BedrockModels: {
+    /** Highest capability and best performance. Recommended default. Currently: Claude Opus 4.8. */
+    readonly DEFAULT: {
+        readonly provider: "bedrock";
+        readonly modelId: "us.anthropic.claude-opus-4-8-20250610-v1:0";
+    };
+    /** Strong quality/cost balance. Currently: Claude Sonnet 4. */
+    readonly BALANCED: {
+        readonly provider: "bedrock";
+        readonly modelId: "us.anthropic.claude-sonnet-4-20250514-v1:0";
+    };
+    /** Fastest and lowest latency. Currently: Claude Haiku 4.5. */
+    readonly FAST: {
+        readonly provider: "bedrock";
+        readonly modelId: "us.anthropic.claude-haiku-4-5-20251001-v1:0";
+    };
+    /** Low cost per token with acceptable quality. Currently: Amazon Nova Pro. */
+    readonly BUDGET: {
+        readonly provider: "bedrock";
+        readonly modelId: "us.amazon.nova-pro-v1:0";
+    };
+    /** Ultra-cheap for simple tasks. Currently: Amazon Nova Lite. */
+    readonly MICRO: {
+        readonly provider: "bedrock";
+        readonly modelId: "us.amazon.nova-lite-v1:0";
+    };
+};
+/**
+ * Pre-configured Ollama model presets for local development.
+ * These are convenience shortcuts that use the `openai-api` provider under the hood.
+ *
+ * **Requirements:**
+ * - Ollama must be installed and running (`ollama serve`)
+ * - The model must be pulled first (`ollama pull <modelId>`)
+ * - Assumes the default Ollama endpoint: `http://localhost:11434/v1`
+ *
+ * If your Ollama runs on a different port or host, use the `openai-api` provider directly:
+ * ```ts
+ * { provider: 'openai-api', modelId: 'llama3.1:8b', endpoint: 'http://custom-host:11434/v1', apiKey: 'ollama' }
+ * ```
+ */
+export declare const OllamaModels: {
+    /** Fast and lightweight for quick iteration. Currently: Llama 3.2 3B (~2 GB, needs 4 GB VRAM). */
+    readonly XSMALL: {
+        readonly provider: "openai-api";
+        readonly modelId: "llama3.2:3b";
+        readonly endpoint: "http://localhost:11434/v1";
+        readonly apiKey: "ollama";
+    };
+    /** Good balance of speed and capability. Currently: Llama 3.1 8B (~4.7 GB, needs 8 GB VRAM). */
+    readonly SMALL: {
+        readonly provider: "openai-api";
+        readonly modelId: "llama3.1:8b";
+        readonly endpoint: "http://localhost:11434/v1";
+        readonly apiKey: "ollama";
+    };
+    /** Strong reasoning at moderate size. Currently: DeepSeek R1 14B (~9 GB, needs 16 GB VRAM). */
+    readonly MEDIUM: {
+        readonly provider: "openai-api";
+        readonly modelId: "deepseek-r1:14b";
+        readonly endpoint: "http://localhost:11434/v1";
+        readonly apiKey: "ollama";
+    };
+    /** High quality for complex tasks. Currently: Llama 3.3 70B (~43 GB, needs 48 GB+ VRAM). */
+    readonly LARGE: {
+        readonly provider: "openai-api";
+        readonly modelId: "llama3.3:70b";
+        readonly endpoint: "http://localhost:11434/v1";
+        readonly apiKey: "ollama";
+    };
+    /** Largest local model. Currently: Llama 4 Scout (~67 GB, needs 80 GB+ VRAM). */
+    readonly XLARGE: {
+        readonly provider: "openai-api";
+        readonly modelId: "llama4:16x17b";
+        readonly endpoint: "http://localhost:11434/v1";
+        readonly apiKey: "ollama";
+    };
+};
+//# sourceMappingURL=models.d.ts.map

package/dist/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,eAAO,MAAM,aAAa;IACzB,gGAAgG;;;;;IAKhG,+DAA+D;;;;;IAK/D,+DAA+D;;;;;IAK/D,8EAA8E;;;;;IAK9E,iEAAiE;;;;;CAKlB,CAAC;AAEjD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,YAAY;IACxB,kGAAkG;;;;;;;IAOlG,gGAAgG;;;;;;;IAOhG,+FAA+F;;;;;;;IAO/F,4FAA4F;;;;;;;IAO5F,iFAAiF;;;;;;;CAOlC,CAAC"}

package/dist/models.js

@@ -0,0 +1,84 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Pre-configured Bedrock model presets using cross-region inference profiles.
+ * Names are capability-based so the underlying model can be upgraded without breaking user code.
+ */
+export const BedrockModels = {
+    /** Highest capability and best performance. Recommended default. Currently: Claude Opus 4.8. */
+    DEFAULT: {
+        provider: 'bedrock',
+        modelId: 'us.anthropic.claude-opus-4-8-20250610-v1:0',
+    },
+    /** Strong quality/cost balance. Currently: Claude Sonnet 4. */
+    BALANCED: {
+        provider: 'bedrock',
+        modelId: 'us.anthropic.claude-sonnet-4-20250514-v1:0',
+    },
+    /** Fastest and lowest latency. Currently: Claude Haiku 4.5. */
+    FAST: {
+        provider: 'bedrock',
+        modelId: 'us.anthropic.claude-haiku-4-5-20251001-v1:0',
+    },
+    /** Low cost per token with acceptable quality. Currently: Amazon Nova Pro. */
+    BUDGET: {
+        provider: 'bedrock',
+        modelId: 'us.amazon.nova-pro-v1:0',
+    },
+    /** Ultra-cheap for simple tasks. Currently: Amazon Nova Lite. */
+    MICRO: {
+        provider: 'bedrock',
+        modelId: 'us.amazon.nova-lite-v1:0',
+    },
+};
+/**
+ * Pre-configured Ollama model presets for local development.
+ * These are convenience shortcuts that use the `openai-api` provider under the hood.
+ *
+ * **Requirements:**
+ * - Ollama must be installed and running (`ollama serve`)
+ * - The model must be pulled first (`ollama pull <modelId>`)
+ * - Assumes the default Ollama endpoint: `http://localhost:11434/v1`
+ *
+ * If your Ollama runs on a different port or host, use the `openai-api` provider directly:
+ * ```ts
+ * { provider: 'openai-api', modelId: 'llama3.1:8b', endpoint: 'http://custom-host:11434/v1', apiKey: 'ollama' }
+ * ```
+ */
+export const OllamaModels = {
+    /** Fast and lightweight for quick iteration. Currently: Llama 3.2 3B (~2 GB, needs 4 GB VRAM). */
+    XSMALL: {
+        provider: 'openai-api',
+        modelId: 'llama3.2:3b',
+        endpoint: 'http://localhost:11434/v1',
+        apiKey: 'ollama',
+    },
+    /** Good balance of speed and capability. Currently: Llama 3.1 8B (~4.7 GB, needs 8 GB VRAM). */
+    SMALL: {
+        provider: 'openai-api',
+        modelId: 'llama3.1:8b',
+        endpoint: 'http://localhost:11434/v1',
+        apiKey: 'ollama',
+    },
+    /** Strong reasoning at moderate size. Currently: DeepSeek R1 14B (~9 GB, needs 16 GB VRAM). */
+    MEDIUM: {
+        provider: 'openai-api',
+        modelId: 'deepseek-r1:14b',
+        endpoint: 'http://localhost:11434/v1',
+        apiKey: 'ollama',
+    },
+    /** High quality for complex tasks. Currently: Llama 3.3 70B (~43 GB, needs 48 GB+ VRAM). */
+    LARGE: {
+        provider: 'openai-api',
+        modelId: 'llama3.3:70b',
+        endpoint: 'http://localhost:11434/v1',
+        apiKey: 'ollama',
+    },
+    /** Largest local model. Currently: Llama 4 Scout (~67 GB, needs 80 GB+ VRAM). */
+    XLARGE: {
+        provider: 'openai-api',
+        modelId: 'llama4:16x17b',
+        endpoint: 'http://localhost:11434/v1',
+        apiKey: 'ollama',
+    },
+};

package/dist/providers/canned.d.ts

@@ -0,0 +1,32 @@
+/**
+ * CannedProvider — a fake Strands model provider for local dev.
+ * Returns keyword-based responses without calling any real model.
+ * Speaks the same ModelStreamEvent protocol as Bedrock/OpenAI,
+ * so Strands processes it identically to a real provider.
+ *
+ * Tool call support: if the prompt mentions a tool name from the available toolSpecs,
+ * emits toolUse events so Strands executes the tool. On the follow-up call (with tool
+ * result in messages), emits a simple text summary.
+ *
+ * @see https://strandsagents.com/docs/user-guide/concepts/model-providers/custom_model_provider/
+ */
+import { Model } from '@strands-agents/sdk';
+import type { Message, ModelStreamEvent, StreamOptions } from '@strands-agents/sdk';
+interface CannedConfig {
+    modelId: string;
+}
+export declare class CannedProvider extends Model<CannedConfig> {
+    private config;
+    constructor(config?: Partial<CannedConfig>);
+    updateConfig(config: Partial<CannedConfig>): void;
+    getConfig(): CannedConfig;
+    stream(messages: Message[], options?: StreamOptions): AsyncIterable<ModelStreamEvent>;
+    /** Emit a text response as ModelStreamEvents. */
+    private emitText;
+    /** Emit multiple tool calls in one message (parallel execution). */
+    private emitParallelToolCalls;
+    /** Emit a tool call as ModelStreamEvents. Strands executes the tool and calls stream() again with the result. */
+    private emitToolCall;
+}
+export {};
+//# sourceMappingURL=canned.d.ts.map

package/dist/providers/canned.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canned.d.ts","sourceRoot":"","sources":["../../src/providers/canned.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC5C,OAAO,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpF,UAAU,YAAY;IACrB,OAAO,EAAE,MAAM,CAAC;CAChB;AAoGD,qBAAa,cAAe,SAAQ,KAAK,CAAC,YAAY,CAAC;IACtD,OAAO,CAAC,MAAM,CAAe;gBAEjB,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC;IAK1C,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI;IAIjD,SAAS,IAAI,YAAY;IAIlB,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,aAAa,CAAC,gBAAgB,CAAC;IA+B5F,iDAAiD;YAClC,QAAQ;IAWvB,oEAAoE;YACrD,qBAAqB;IAYpC,iHAAiH;YAClG,YAAY;CAS3B"}

package/dist/providers/canned.js

@@ -0,0 +1,187 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CannedProvider — a fake Strands model provider for local dev.
+ * Returns keyword-based responses without calling any real model.
+ * Speaks the same ModelStreamEvent protocol as Bedrock/OpenAI,
+ * so Strands processes it identically to a real provider.
+ *
+ * Tool call support: if the prompt mentions a tool name from the available toolSpecs,
+ * emits toolUse events so Strands executes the tool. On the follow-up call (with tool
+ * result in messages), emits a simple text summary.
+ *
+ * @see https://strandsagents.com/docs/user-guide/concepts/model-providers/custom_model_provider/
+ */
+import { Model } from '@strands-agents/sdk';
+const CANNED_RESPONSES = {
+    weather: 'The weather is 22°C and sunny. [canned response]',
+    order: 'Order #12345 has been shipped and is on its way. [canned response]',
+    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]';
+function matchResponse(prompt) {
+    const lower = prompt.toLowerCase();
+    for (const [keyword, response] of Object.entries(CANNED_RESPONSES)) {
+        if (lower.includes(keyword))
+            return response;
+    }
+    return DEFAULT_RESPONSE;
+}
+/**
+ * Match a single word against the prompt on word boundaries (case-insensitive).
+ * 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.
+ */
+function promptMentionsWord(lowerPrompt, word) {
+    const escaped = word.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`\\b${escaped}\\b`).test(lowerPrompt);
+}
+/** Find ALL tools mentioned in the prompt (for parallel tool calls). */
+function findAllToolMatches(prompt, toolSpecs) {
+    if (!toolSpecs?.length)
+        return [];
+    const lower = prompt.toLowerCase();
+    return toolSpecs.filter(t => {
+        const name = t.name.toLowerCase();
+        if (promptMentionsWord(lower, name))
+            return true;
+        // 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));
+    }).map(t => t.name);
+}
+/** Check if the last message contains a tool result — means we're in the follow-up after a tool call. */
+function hasToolResult(messages) {
+    const last = messages[messages.length - 1];
+    return last?.content?.some((block) => 'toolResult' in block || block.type === 'toolResultBlock' || ('toolUseId' in block && 'status' in block)) ?? false;
+}
+/** Extract tool result text from the last message. */
+function getToolResultText(messages) {
+    const last = messages[messages.length - 1];
+    const results = [];
+    for (const block of last?.content ?? []) {
+        const b = block;
+        if ('toolResult' in b || b.type === 'toolResultBlock' || ('toolUseId' in b && 'status' in b)) {
+            const content = b.toolResult?.content ?? b.content ?? [];
+            if (!Array.isArray(content)) {
+                results.push(String(content));
+                continue;
+            }
+            results.push(content.map((c) => c.text ?? JSON.stringify(c)).join(' '));
+        }
+    }
+    return results.join(' | ');
+}
+/** 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);
+            }
+        }
+        return result;
+    }
+    return {};
+}
+/** Look up a tool's inputSchema from toolSpecs and generate placeholder input. */
+function getToolInput(toolName, toolSpecs) {
+    const spec = toolSpecs?.find(t => t.name === toolName);
+    if (!spec?.inputSchema)
+        return '{}';
+    return JSON.stringify(generatePlaceholderInput(spec.inputSchema));
+}
+let toolCallCounter = 0;
+export class CannedProvider extends Model {
+    config;
+    constructor(config) {
+        super();
+        this.config = { modelId: config?.modelId ?? 'canned-mock' };
+    }
+    updateConfig(config) {
+        Object.assign(this.config, config);
+    }
+    getConfig() {
+        return { ...this.config };
+    }
+    async *stream(messages, options) {
+        const lastMessage = messages[messages.length - 1];
+        const prompt = lastMessage?.content
+            ?.map((block) => ('text' in block ? block.text : ''))
+            .join('') ?? '';
+        // Follow-up after tool execution — Strands sends the tool result back to the model
+        if (hasToolResult(messages)) {
+            const resultText = getToolResultText(messages);
+            yield* this.emitText(`I called the tool. Output: ${resultText} [canned tool response]`);
+            return;
+        }
+        // Check if prompt mentions tool names — trigger tool call(s)
+        const toolMatches = findAllToolMatches(prompt, options?.toolSpecs);
+        if (toolMatches.length > 1) {
+            yield* this.emitParallelToolCalls(toolMatches, options?.toolSpecs);
+            return;
+        }
+        const toolName = toolMatches[0];
+        if (toolName) {
+            yield* this.emitToolCall(toolName, options?.toolSpecs);
+            return;
+        }
+        // Default: keyword-based text response
+        // Default: keyword-based text response
+        yield* this.emitText(matchResponse(prompt));
+    }
+    /** Emit a text response as ModelStreamEvents. */
+    async *emitText(response) {
+        yield { type: 'modelMessageStartEvent', role: 'assistant' };
+        yield { type: 'modelContentBlockStartEvent' };
+        for (const word of response.split(' ')) {
+            yield { type: 'modelContentBlockDeltaEvent', delta: { type: 'textDelta', text: word + ' ' } };
+        }
+        yield { type: 'modelContentBlockStopEvent' };
+        yield { type: 'modelMessageStopEvent', stopReason: 'endTurn' };
+        yield { type: 'modelMetadataEvent', usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 }, metrics: { latencyMs: 0 } };
+    }
+    /** Emit multiple tool calls in one message (parallel execution). */
+    async *emitParallelToolCalls(toolNames, toolSpecs) {
+        yield { type: 'modelMessageStartEvent', role: 'assistant' };
+        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: 'modelContentBlockStopEvent' };
+        }
+        yield { type: 'modelMessageStopEvent', stopReason: 'toolUse' };
+        yield { type: 'modelMetadataEvent', usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 }, metrics: { latencyMs: 0 } };
+    }
+    /** Emit a tool call as ModelStreamEvents. Strands executes the tool and calls stream() again with the result. */
+    async *emitToolCall(toolName, toolSpecs) {
+        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: 'modelContentBlockStopEvent' };
+        yield { type: 'modelMessageStopEvent', stopReason: 'toolUse' };
+        yield { type: 'modelMetadataEvent', usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 }, metrics: { latencyMs: 0 } };
+    }
+}

package/dist/providers/throwing.d.ts

@@ -0,0 +1,10 @@
+/**
+ * ThrowingProvider — extends CannedProvider but throws mid-stream.
+ * Used in unit tests to verify block buffer flush on error.
+ */
+import { CannedProvider } from './canned.js';
+import type { Message, ModelStreamEvent, StreamOptions } from '@strands-agents/sdk';
+export declare class ThrowingProvider extends CannedProvider {
+    stream(_messages: Message[], _options?: StreamOptions): AsyncIterable<ModelStreamEvent>;
+}
+//# sourceMappingURL=throwing.d.ts.map

package/dist/providers/throwing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"throwing.d.ts","sourceRoot":"","sources":["../../src/providers/throwing.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpF,qBAAa,gBAAiB,SAAQ,cAAc;IAC5C,MAAM,CAAC,SAAS,EAAE,OAAO,EAAE,EAAE,QAAQ,CAAC,EAAE,aAAa,GAAG,aAAa,CAAC,gBAAgB,CAAC;CAO9F"}

package/dist/providers/throwing.js

@@ -0,0 +1,16 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * ThrowingProvider — extends CannedProvider but throws mid-stream.
+ * Used in unit tests to verify block buffer flush on error.
+ */
+import { CannedProvider } from './canned.js';
+export class ThrowingProvider extends CannedProvider {
+    async *stream(_messages, _options) {
+        yield { type: 'modelMessageStartEvent', role: 'assistant' };
+        yield { type: 'modelContentBlockStartEvent' };
+        yield { type: 'modelContentBlockDeltaEvent', delta: { type: 'textDelta', text: 'partial ' } };
+        yield { type: 'modelContentBlockDeltaEvent', delta: { type: 'textDelta', text: 'text' } };
+        throw new Error('simulated mid-stream failure');
+    }
+}