@aws-blocks/bb-agent 0.1.0

package/src/file-bucket-snapshot-storage.ts

@@ -0,0 +1,85 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { SnapshotStorage, SnapshotLocation, Snapshot, SnapshotManifest } from '@strands-agents/sdk';
+import type { FileBucket } from '@aws-blocks/bb-file-bucket';
+
+/**
+ * SnapshotStorage backed by FileBucket BB.
+ * Used locally — on AWS, Strands' native S3Storage talks to the same bucket directly.
+ *
+ * Mirrors the Strands S3Storage implementation exactly so that local and AWS
+ * produce identical key layouts. If S3Storage changes, update this to match.
+ *
+ * Key layout (same as S3Storage):
+ *   <sessionId>/scopes/<scope>/<scopeId>/snapshots/snapshot_latest.json
+ *   <sessionId>/scopes/<scope>/<scopeId>/snapshots/immutable_history/snapshot_<uuid>.json
+ *   <sessionId>/scopes/<scope>/<scopeId>/snapshots/manifest.json
+ *
+ *   @see https://strandsagents.com/docs/user-guide/concepts/agents/session-management/#s3sessionmanager--s3storage
+ *   @see https://strandsagents.com/docs/user-guide/concepts/agents/session-management
+ */
+export class FileBucketSnapshotStorage implements SnapshotStorage {
+	constructor(private bucket: FileBucket) {}
+
+	/** Base path for a scope's snapshots folder. */
+	private basePath(location: SnapshotLocation): string {
+		return `${location.sessionId}/scopes/${location.scope}/${location.scopeId}/snapshots`;
+	}
+
+	async saveSnapshot(params: { location: SnapshotLocation; snapshotId: string; isLatest: boolean; snapshot: Snapshot }): Promise<void> {
+		const data = JSON.stringify(params.snapshot, null, 2);
+		if (params.isLatest) {
+			// Overwrite the mutable latest snapshot
+			await this.bucket.put(`${this.basePath(params.location)}/snapshot_latest.json`, data);
+		} else {
+			// Append-only immutable checkpoint
+			await this.bucket.put(`${this.basePath(params.location)}/immutable_history/snapshot_${params.snapshotId}.json`, data);
+		}
+	}
+
+	async loadSnapshot(params: { location: SnapshotLocation; snapshotId?: string }): Promise<Snapshot | null> {
+		const path = params.snapshotId
+			? `${this.basePath(params.location)}/immutable_history/snapshot_${params.snapshotId}.json`
+			: `${this.basePath(params.location)}/snapshot_latest.json`;
+		const file = await this.bucket.get(path);
+		if (!file) return null;
+		return JSON.parse(file.body.toString());
+	}
+
+	async listSnapshotIds(params: { location: SnapshotLocation; limit?: number; startAfter?: string }): Promise<string[]> {
+		const prefix = `${this.basePath(params.location)}/immutable_history/`;
+		const ids: string[] = [];
+		let pastCursor = !params.startAfter;
+		for await (const file of this.bucket.scan({ prefix })) {
+			const match = file.path.match(/snapshot_([\w-]+)\.json$/);
+			if (!match) continue;
+			const id = match[1];
+			if (!pastCursor) {
+				if (id === params.startAfter) pastCursor = true;
+				continue;
+			}
+			ids.push(id);
+			if (params.limit && ids.length >= params.limit) break;
+		}
+		return ids;
+	}
+
+	async deleteSession(params: { sessionId: string }): Promise<void> {
+		const paths: string[] = [];
+		for await (const file of this.bucket.scan({ prefix: `${params.sessionId}/` })) {
+			paths.push(file.path);
+		}
+		if (paths.length > 0) await this.bucket.deleteBatch(paths);
+	}
+
+	async loadManifest(params: { location: SnapshotLocation }): Promise<SnapshotManifest> {
+		const file = await this.bucket.get(`${this.basePath(params.location)}/manifest.json`);
+		if (!file) return { schemaVersion: '1.0', updatedAt: new Date().toISOString() };
+		return JSON.parse(file.body.toString());
+	}
+
+	async saveManifest(params: { location: SnapshotLocation; manifest: SnapshotManifest }): Promise<void> {
+		await this.bucket.put(`${this.basePath(params.location)}/manifest.json`, JSON.stringify(params.manifest, null, 2));
+	}
+}

package/src/index.aws.ts

@@ -0,0 +1,7 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export { Agent } from './agent.aws.js';
+export { AgentErrors, InterruptError } from './errors.js';
+export { BedrockModels, OllamaModels } from './models.js';
+export type { AgentConfig, AgentResult, AgentStreamChunk, AgentStreamResult, ToolDefinition, AgentTool, ToolFactory, ToolsConfig, ToolHandlerArgs, DefaultToolContext, InterruptResponse, ToolCallRecord, ModelConfig, StreamOptions, Message, Conversation, JSONValue, TokenUsage } from './types.js';

package/src/index.browser.ts

@@ -0,0 +1,10 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { AgentErrors, blocksAgentError } from './errors.js';
+
+export class Agent {
+  constructor(..._args: any[]) {
+    throw blocksAgentError(AgentErrors.BrowserNotSupported, 'Agent can only be instantiated on the server.');
+  }
+}

package/src/index.cdk.ts

@@ -0,0 +1,70 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { PolicyStatement } from 'aws-cdk-lib/aws-iam';
+import { Scope } from '@aws-blocks/core/cdk';
+import type { ScopeParent } from '@aws-blocks/core';
+import { DistributedTable } from '@aws-blocks/bb-distributed-table';
+import { Realtime } from '@aws-blocks/bb-realtime';
+import { AsyncJob } from '@aws-blocks/bb-async-job';
+import { FileBucket } from '@aws-blocks/bb-file-bucket';
+import { messageSchema, conversationSchema, agentStreamChunkSchema } from './schemas.js';
+import { z } from 'zod';
+
+export { AgentErrors } from './errors.js';
+export { BedrockModels, OllamaModels } from './models.js';
+
+const jobPayloadSchema = z.object({
+	message: z.string(),
+	conversationId: z.string().optional(),
+});
+
+export class Agent extends Scope {
+	/**
+	 * CDK layer for the Agent BB.
+	 * Mirrors the runtime's BB creation so CDK discovers and provisions all resources.
+	 *
+	 * TODO: scope Bedrock IAM grant to specific modelId from config
+	 * TODO: guardrails CDK provisioning
+	 */
+	constructor(scope: ScopeParent, id: string, config?: any) {
+		super(id, { parent: scope });
+
+		this.handler.addToRolePolicy(new PolicyStatement({
+			actions: ['bedrock:InvokeModel', 'bedrock:InvokeModelWithResponseStream', 'bedrock:GetFoundationModel', 'bedrock:ListFoundationModels', 'bedrock:GetInferenceProfile'],
+			resources: [
+				'arn:aws:bedrock:*::foundation-model/*',
+				'arn:aws:bedrock:*:*:inference-profile/*',
+			],
+		}));
+
+		// Propagate `removalPolicy` to the sessions bucket so customers can
+		// opt sandbox stacks into clean teardown. Without it, CDK's RETAIN
+		// default applies (production-safe) and `cdk destroy` will fail on
+		// a non-empty bucket — same pattern as FileBucket / KnowledgeBase.
+		// ID shortened to keep S3 bucket names within the 63-char limit
+		new FileBucket(this, 'sn', { removalPolicy: config?.removalPolicy });
+
+		if (!config?.inferenceOnly) {
+			new DistributedTable(this, 'convos', {
+				schema: conversationSchema,
+				key: { partitionKey: 'userId', sortKey: 'conversationId' },
+			});
+			new DistributedTable(this, 'messages', {
+				schema: messageSchema,
+				key: { partitionKey: 'conversationId', sortKey: 'messageId' },
+			});
+		}
+
+		new Realtime(this, 'rt', {
+			namespaces: {
+				chunks: { schema: agentStreamChunkSchema },
+			},
+		});
+
+		new AsyncJob(this, 'job', {
+			schema: jobPayloadSchema,
+			handler: async () => {},
+		});
+	}
+}

package/src/index.hooks.ts

@@ -0,0 +1,256 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Client hooks for Agent BB.
+ *
+ * useChat() provides state management for agent conversations.
+ * Works with any framework — not React-specific (no JSX, no React imports).
+ *
+ * Flow:
+ * 1. Subscribe to Realtime channel + await established
+ * 2. Load existing history from DB
+ * 3. Show history — any in-flight chunks are caught by the subscription
+ * 4. User sends message — chunks arrive via the already-open subscription
+ */
+
+import type { AgentStreamChunk } from './types.js';
+
+export type { AgentStreamChunk } from './types.js';
+
+/** A message in the conversation (for UI rendering). */
+export interface ChatMessage {
+	id: string;
+	role: 'user' | 'assistant' | 'approval';
+	content: string;
+	metadata?: Record<string, any>;
+}
+
+/** Options for creating a chat instance. */
+export interface UseChatOptions {
+	api: {
+		sendMessage(conversationId: string, message: string, channelId: string): Promise<void>;
+		createConversation(): Promise<{ conversationId: string }>;
+		getConversation(id: string): Promise<{ messages: { role: string; content: string; metadata?: Record<string, any> }[] }>;
+		resume?(channelId: string, responses: Array<{ interruptId: string; approved: boolean; trust?: boolean; toolName?: string; input?: any }>, conversationId?: string): Promise<void>;
+		getPendingInterrupts?(conversationId: string): Promise<{ interrupts: Array<{ id: string; name: string; reason?: any }> }>;
+	};
+	/**
+	 * Subscribe to a Realtime channel. Must return an object with:
+	 * - unsubscribe(): stop receiving messages
+	 * - established: Promise that resolves when the WS subscription is confirmed
+	 */
+	subscribe: (channelId: string, handler: (chunk: AgentStreamChunk) => void) => Promise<{ unsubscribe(): void; established: Promise<void> }>;
+	/** Called whenever the message list changes. */
+	onMessagesChange?: (messages: ChatMessage[]) => void;
+	/** Called whenever loading state changes. */
+	onLoadingChange?: (isLoading: boolean) => void;
+	/** Called on each streaming chunk. */
+	onChunk?: (chunk: AgentStreamChunk) => void;
+	/** Called when the agent encounters an error. */
+	onError?: (error: string) => void;
+	/** Called when the agent needs human approval before continuing. */
+	onInterrupt?: (interrupts: Array<{ id: string; name: string; reason?: any }>) => void;
+}
+
+/** Returned by useChat(). */
+export interface ChatInstance {
+	/** Send a message. Creates a conversation and subscribes if needed. */
+	sendMessage(text: string): Promise<void>;
+	/** Respond to an interrupt (tool approval). Resumes the agent. */
+	respondToInterrupt(responses: Array<{ interruptId: string; approved: boolean; trust?: boolean; toolName?: string; input?: any }>): Promise<void>;
+	/** Current messages. */
+	getMessages(): ChatMessage[];
+	/** Whether the agent is currently responding. */
+	isLoading(): boolean;
+	/** Current conversation ID (null until first message). */
+	getConversationId(): string | null;
+	/** Open a conversation: subscribe to Realtime, then load history. */
+	loadConversation(conversationId: string): Promise<void>;
+	/** Clean up the active subscription. */
+	destroy(): void;
+}
+
+let messageCounter = 0;
+function nextId(): string {
+	return `msg-${++messageCounter}-${Date.now()}`;
+}
+
+/**
+ * Create a chat instance for managing agent conversations.
+ *
+ * @example
+ * ```typescript
+ * const chat = useChat({
+ *   api: {
+ *     sendMessage: (convId, msg, chId) => api.agentStream(msg, convId, chId),
+ *     createConversation: () => api.agentCreateConversationId(),
+ *     getConversation: (id) => api.agentGetConversation(id),
+ *   },
+ *   subscribe: async (channelId, handler) => {
+ *     const result = await api.agentGetChannel(channelId);
+ *     return result.channel.subscribe(handler);
+ *   },
+ *   onMessagesChange: (msgs) => renderMessages(msgs),
+ *   onLoadingChange: (loading) => updateSpinner(loading),
+ * });
+ *
+ * await chat.loadConversation('conv-123');
+ * await chat.sendMessage('Hello!');
+ * ```
+ */
+export function useChat(options: UseChatOptions): ChatInstance {
+	let messages: ChatMessage[] = [];
+	let loading = false;
+	let conversationId: string | null = null;
+	let activeSub: { unsubscribe(): void } | null = null;
+	let assistantId: string | null = null;
+	let assistantText = '';
+
+	/** Handle a chunk from the Realtime subscription. */
+	function handleChunk(chunk: AgentStreamChunk) {
+		options.onChunk?.(chunk);
+
+		if (chunk.type === 'text-delta' && chunk.text && assistantId) {
+			assistantText += chunk.text;
+			messages = messages.map(m => m.id === assistantId ? { ...m, content: assistantText } : m);
+			options.onMessagesChange?.(messages);
+		}
+
+		if (chunk.type === 'done') {
+			if (chunk.text && assistantId) {
+				messages = messages.map(m => m.id === assistantId ? { ...m, content: chunk.text! } : m);
+				options.onMessagesChange?.(messages);
+			}
+			loading = false;
+			options.onLoadingChange?.(loading);
+		}
+
+		if (chunk.type === 'error') {
+			loading = false;
+			options.onLoadingChange?.(loading);
+			options.onError?.(chunk.error ?? 'Unknown error');
+		}
+
+		if (chunk.type === 'interrupt' && chunk.interrupts) {
+			// Remove empty assistant placeholder (no text was generated before interrupt)
+			if (assistantId) {
+				const assistant = messages.find(m => m.id === assistantId);
+				if (assistant && !assistant.content) {
+					messages = messages.filter(m => m.id !== assistantId);
+					options.onMessagesChange?.(messages);
+				}
+			}
+			assistantId = null;
+			loading = false;
+			options.onLoadingChange?.(loading);
+			options.onInterrupt?.(chunk.interrupts);
+		}
+	}
+
+	/** Subscribe to a conversation's Realtime channel and wait for WS confirmation. Retries with fresh token on auth failure. */
+	async function ensureSubscribed(channelId: string) {
+		if (activeSub) { activeSub.unsubscribe(); activeSub = null; }
+
+		const sub = await options.subscribe(channelId, handleChunk);
+		try {
+			await sub.established;
+		} catch (err) {
+			console.warn('Subscription failed, retrying with fresh token:', err);
+			sub.unsubscribe();
+			const retrySub = await options.subscribe(channelId, handleChunk);
+			await retrySub.established;
+			activeSub = retrySub;
+			return;
+		}
+		activeSub = sub;
+	}
+
+	return {
+		async sendMessage(text: string) {
+			if (loading) return;
+			// Create conversation + subscribe on first message
+			if (!conversationId) {
+				const result = await options.api.createConversation();
+				conversationId = result.conversationId;
+				await ensureSubscribed(conversationId);
+			}
+
+			// Subscribe if not already (e.g., sendMessage without loadConversation)
+			if (!activeSub) {
+				await ensureSubscribed(conversationId);
+			}
+
+			// Add user message + assistant placeholder
+			const userMsg: ChatMessage = { id: nextId(), role: 'user', content: text };
+			const aMsg: ChatMessage = { id: nextId(), role: 'assistant', content: '' };
+			assistantId = aMsg.id;
+			assistantText = '';
+			messages = [...messages, userMsg, aMsg];
+			options.onMessagesChange?.(messages);
+			loading = true;
+			options.onLoadingChange?.(loading);
+
+			// Submit — chunks arrive via the already-open subscription
+			await options.api.sendMessage(conversationId, text, conversationId);
+		},
+
+		async respondToInterrupt(responses: Array<{ interruptId: string; approved: boolean; trust?: boolean; toolName?: string; input?: any }>) {
+			if (loading) return;
+			if (!conversationId) throw new Error('No active conversation');
+			// Add approval messages to chat immediately
+			for (const r of responses) {
+				messages = [...messages, { id: nextId(), role: 'approval' as const, content: r.approved ? 'Approved' : 'Denied', metadata: { approved: r.approved, trust: r.trust, toolName: r.toolName, input: r.input } }];
+			}
+			// Reuse existing empty assistant placeholder or create one
+			const existingEmpty = messages.find(m => m.role === 'assistant' && !m.content);
+			if (existingEmpty) {
+				assistantId = existingEmpty.id;
+			} else {
+				const aMsg: ChatMessage = { id: nextId(), role: 'assistant', content: '' };
+				assistantId = aMsg.id;
+				messages = [...messages, aMsg];
+			}
+			assistantText = '';
+			options.onMessagesChange?.(messages);
+			loading = true;
+			options.onLoadingChange?.(loading);
+			if (!options.api.resume) throw new Error('respondToInterrupt requires api.resume to be configured');
+			await options.api.resume(conversationId, responses, conversationId);
+		},
+
+		getMessages() { return messages; },
+		isLoading() { return loading; },
+		getConversationId() { return conversationId; },
+
+		async loadConversation(id: string) {
+			conversationId = id;
+
+			// 1. Subscribe FIRST — catch any in-flight chunks
+			await ensureSubscribed(id);
+
+			// 2. THEN load history from DB
+			// TODO: buffer chunks received between subscribe and history load, then deduplicate/merge
+			const { messages: history } = await options.api.getConversation(id);
+			messages = history
+				.filter(m => m.role === 'user' || m.role === 'assistant' || m.role === 'approval')
+				.map(m => ({
+					id: nextId(),
+					role: m.role as 'user' | 'assistant' | 'approval',
+					content: m.content,
+					metadata: m.metadata,
+				}));
+			options.onMessagesChange?.(messages);
+
+			// Check for pending interrupts (e.g., user left mid-approval)
+			if (options.api.getPendingInterrupts) {
+				const { interrupts } = await options.api.getPendingInterrupts(id);
+				if (interrupts.length) options.onInterrupt?.(interrupts);
+			}
+		},
+
+		destroy() {
+			if (activeSub) { activeSub.unsubscribe(); activeSub = null; }
+		},
+	};
+}

package/src/index.mock.ts

@@ -0,0 +1,7 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export { Agent } from './agent.mock.js';
+export { AgentErrors, InterruptError } from './errors.js';
+export { BedrockModels, OllamaModels } from './models.js';
+export type { AgentConfig, AgentResult, AgentStreamChunk, AgentStreamResult, ToolDefinition, AgentTool, ToolFactory, ToolsConfig, ToolHandlerArgs, DefaultToolContext, InterruptResponse, ToolCallRecord, ModelConfig, StreamOptions, Message, Conversation, JSONValue, TokenUsage } from './types.js';