@aws-blocks/bb-agent 0.1.0

package/src/model-factory.ts

@@ -0,0 +1,228 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { BedrockModel, type Model } from '@strands-agents/sdk';
+import type { BaseModelConfig } from '@strands-agents/sdk';
+import { OpenAIModel } from '@strands-agents/sdk/models/openai';
+import type { ChildLogger } from '@aws-blocks/bb-logger';
+import { CannedProvider } from './providers/canned.js';
+import { ThrowingProvider } from './providers/throwing.js';
+import type { ModelConfig } from './types.js';
+import { AgentErrors, blocksAgentError } from './errors.js';
+
+// TODO: validate model-specific inference config (e.g., some models don't support topP with temperature)
+
+/**
+ * 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 async function checkModelHealth(config: ModelConfig, log: ChildLogger, _testClient?: BedrockHealthClient): Promise<boolean> {
+	if (!config || config.provider === 'canned') {
+		log.info('Using canned provider (local mock, no real model)');
+		return true;
+	}
+	if ((config.provider as string) === '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 (): Promise<BedrockHealthClient> => {
+			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: unknown) {
+				const e = err as { name?: string; message?: string };
+				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: unknown) {
+			const e = err as { name?: string; message?: string };
+			// 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: { modelId?: string }) => 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: Response;
+		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 as Error).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: { data?: Array<{ id: string }> };
+		let text = '';
+		try {
+			text = await res.text();
+		} catch (err) {
+			log.warn(`Failed to read model-list response body: ${baseUrl}`, { provider: config.provider, error: (err as Error).message });
+			return false;
+		}
+		try {
+			body = JSON.parse(text) as { data?: Array<{ id: string }> };
+		} 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 as Error).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?: ModelConfig, log?: ChildLogger): Promise<Model<BaseModelConfig>> {
+	if (!config || config.provider === 'canned') return new CannedProvider();
+
+	// Test-only provider — throws mid-stream to verify error handling
+	if (config.provider === 'throwing' as string) {
+		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/src/models.ts

@@ -0,0 +1,88 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { ModelConfig } from './types.js';
+
+/**
+ * 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',
+	},
+} as const satisfies Record<string, ModelConfig>;
+
+/**
+ * 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',
+	},
+} as const satisfies Record<string, ModelConfig>;

package/src/providers/canned.ts

@@ -0,0 +1,205 @@
+// 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';
+import type { Message, ModelStreamEvent, StreamOptions } from '@strands-agents/sdk';
+import { ToolResultBlock } from '@strands-agents/sdk';
+
+interface CannedConfig {
+	modelId: string;
+}
+
+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]',
+	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: string): string {
+	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: string, word: string): boolean {
+	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: string, toolSpecs?: { name: string }[]): string[] {
+	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: Message[]): boolean {
+	const last = messages[messages.length - 1];
+	return last?.content?.some((block: any) =>
+		'toolResult' in block || block.type === 'toolResultBlock' || ('toolUseId' in block && 'status' in block)
+	) ?? false;
+}
+
+/** Extract tool result text from the last message. */
+function getToolResultText(messages: Message[]): string {
+	const last = messages[messages.length - 1];
+	const results: string[] = [];
+	for (const block of last?.content ?? []) {
+		const b = block as any;
+		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: any) => c.text ?? JSON.stringify(c)).join(' '));
+		}
+	}
+	return results.join(' | ');
+}
+
+/** 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);
+			}
+		}
+		return result;
+	}
+	return {};
+}
+
+/** Look up a tool's inputSchema from toolSpecs and generate placeholder input. */
+function getToolInput(toolName: string, toolSpecs?: { name: string; inputSchema?: any }[]): string {
+	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<CannedConfig> {
+	private config: CannedConfig;
+
+	constructor(config?: Partial<CannedConfig>) {
+		super();
+		this.config = { modelId: config?.modelId ?? 'canned-mock' };
+	}
+
+	updateConfig(config: Partial<CannedConfig>): void {
+		Object.assign(this.config, config);
+	}
+
+	getConfig(): CannedConfig {
+		return { ...this.config };
+	}
+
+	async *stream(messages: Message[], options?: StreamOptions): AsyncIterable<ModelStreamEvent> {
+		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. */
+	private async *emitText(response: string): AsyncIterable<ModelStreamEvent> {
+		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). */
+	private async *emitParallelToolCalls(toolNames: string[], toolSpecs?: { name: string; inputSchema?: any }[]): AsyncIterable<ModelStreamEvent> {
+		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. */
+	private async *emitToolCall(toolName: string, toolSpecs?: { name: string; inputSchema?: any }[]): AsyncIterable<ModelStreamEvent> {
+		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/src/providers/throwing.ts

@@ -0,0 +1,19 @@
+// 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';
+import type { Message, ModelStreamEvent, StreamOptions } from '@strands-agents/sdk';
+
+export class ThrowingProvider extends CannedProvider {
+	async *stream(_messages: Message[], _options?: StreamOptions): AsyncIterable<ModelStreamEvent> {
+		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');
+	}
+}

package/src/schemas.ts

@@ -0,0 +1,40 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { z } from 'zod';
+
+/** Schema for conversation metadata stored in DistributedTable (Table 1). */
+export const conversationSchema = z.object({
+	userId: z.string(),
+	conversationId: z.string(),
+	name: z.string(),
+	createdAt: z.number(),
+	updatedAt: z.number(),
+});
+
+/** Schema for messages stored in DistributedTable (Table 2). */
+export const messageSchema = z.object({
+	conversationId: z.string(),
+	messageId: z.string(),
+	role: z.enum(['user', 'assistant', 'tool-call', 'tool-result', 'approval', 'interrupt']),
+	content: z.string(),
+	contentType: z.enum(['text', 'image', 'audio', 'video', 'document']),
+	userId: z.string(),
+	createdAt: z.number(),
+	metadata: z.string(), // JSON: { toolName?, toolInput?, toolOutput?, usage?, latencyMs?, error?, confirmationStatus? }
+});
+
+/** Schema for AgentStreamChunk — used by Realtime namespace validation. */
+export const agentStreamChunkSchema = z.object({
+	type: z.enum(['text-delta', 'tool-call', 'tool-result', 'done', 'error', 'interrupt']),
+	text: z.string().optional(),
+	toolName: z.string().optional(),
+	input: z.any().optional(),
+	error: z.string().optional(),
+	interrupts: z.array(z.object({ id: z.string(), name: z.string(), reason: z.any().optional() })).optional(),
+	usage: z.object({
+		inputTokens: z.number(),
+		outputTokens: z.number(),
+		totalTokens: z.number(),
+	}).optional(),
+});