@aws-blocks/bb-agent 0.1.0

package/dist/errors.js

@@ -0,0 +1,40 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Typed error constants for Agent BB. Use with `isBlocksError()` in catch blocks.
+ *
+ * @example
+ * ```typescript
+ * import { isBlocksError } from '@aws-blocks/core';
+ * import { AgentErrors } from '@aws-blocks/bb-agent';
+ *
+ * try {
+ *   await agent.getConversation(id);
+ * } catch (e) {
+ *   if (isBlocksError(e, AgentErrors.PersistenceRequired)) {
+ *     // agent is in inferenceOnly mode
+ *   }
+ * }
+ * ```
+ */
+export const AgentErrors = {
+    PersistenceRequired: 'PersistenceRequiredException',
+    InvalidModelConfig: 'InvalidModelConfigException',
+    ModelUnavailable: 'ModelUnavailableException',
+    BrowserNotSupported: 'BrowserNotSupportedException',
+    StreamFailed: 'StreamFailedException',
+    InterruptRequired: 'InterruptRequiredException',
+};
+export function blocksAgentError(name, message) {
+    const err = new Error(`${name}: ${message}`);
+    err.name = name;
+    return err;
+}
+export class InterruptError extends Error {
+    interrupts;
+    constructor(message, interrupts) {
+        super(`${AgentErrors.InterruptRequired}: ${message}`);
+        this.name = AgentErrors.InterruptRequired;
+        this.interrupts = interrupts;
+    }
+}

package/dist/file-bucket-snapshot-storage.d.ts

@@ -0,0 +1,49 @@
+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 declare class FileBucketSnapshotStorage implements SnapshotStorage {
+    private bucket;
+    constructor(bucket: FileBucket);
+    /** Base path for a scope's snapshots folder. */
+    private basePath;
+    saveSnapshot(params: {
+        location: SnapshotLocation;
+        snapshotId: string;
+        isLatest: boolean;
+        snapshot: Snapshot;
+    }): Promise<void>;
+    loadSnapshot(params: {
+        location: SnapshotLocation;
+        snapshotId?: string;
+    }): Promise<Snapshot | null>;
+    listSnapshotIds(params: {
+        location: SnapshotLocation;
+        limit?: number;
+        startAfter?: string;
+    }): Promise<string[]>;
+    deleteSession(params: {
+        sessionId: string;
+    }): Promise<void>;
+    loadManifest(params: {
+        location: SnapshotLocation;
+    }): Promise<SnapshotManifest>;
+    saveManifest(params: {
+        location: SnapshotLocation;
+        manifest: SnapshotManifest;
+    }): Promise<void>;
+}
+//# sourceMappingURL=file-bucket-snapshot-storage.d.ts.map

package/dist/file-bucket-snapshot-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-bucket-snapshot-storage.d.ts","sourceRoot":"","sources":["../src/file-bucket-snapshot-storage.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACzG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAE7D;;;;;;;;;;;;;;GAcG;AACH,qBAAa,yBAA0B,YAAW,eAAe;IACpD,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,UAAU;IAEtC,gDAAgD;IAChD,OAAO,CAAC,QAAQ;IAIV,YAAY,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,QAAQ,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAW9H,YAAY,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IASnG,eAAe,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAkB/G,aAAa,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ3D,YAAY,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAM/E,YAAY,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAC;QAAC,QAAQ,EAAE,gBAAgB,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAGrG"}

package/dist/file-bucket-snapshot-storage.js

@@ -0,0 +1,84 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * 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 {
+    bucket;
+    constructor(bucket) {
+        this.bucket = bucket;
+    }
+    /** Base path for a scope's snapshots folder. */
+    basePath(location) {
+        return `${location.sessionId}/scopes/${location.scope}/${location.scopeId}/snapshots`;
+    }
+    async saveSnapshot(params) {
+        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) {
+        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) {
+        const prefix = `${this.basePath(params.location)}/immutable_history/`;
+        const ids = [];
+        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) {
+        const paths = [];
+        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) {
+        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) {
+        await this.bucket.put(`${this.basePath(params.location)}/manifest.json`, JSON.stringify(params.manifest, null, 2));
+    }
+}

package/dist/index.aws.d.ts

@@ -0,0 +1,5 @@
+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';
+//# sourceMappingURL=index.aws.d.ts.map

package/dist/index.aws.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.aws.d.ts","sourceRoot":"","sources":["../src/index.aws.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC1D,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.aws.js

@@ -0,0 +1,5 @@
+// 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';

package/dist/index.browser.d.ts

@@ -0,0 +1,4 @@
+export declare class Agent {
+    constructor(..._args: any[]);
+}
+//# sourceMappingURL=index.browser.d.ts.map

package/dist/index.browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.browser.d.ts","sourceRoot":"","sources":["../src/index.browser.ts"],"names":[],"mappings":"AAKA,qBAAa,KAAK;gBACJ,GAAG,KAAK,EAAE,GAAG,EAAE;CAG5B"}

package/dist/index.browser.js

@@ -0,0 +1,8 @@
+// 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) {
+        throw blocksAgentError(AgentErrors.BrowserNotSupported, 'Agent can only be instantiated on the server.');
+    }
+}

package/dist/index.cdk.d.ts

@@ -0,0 +1,15 @@
+import { Scope } from '@aws-blocks/core/cdk';
+import type { ScopeParent } from '@aws-blocks/core';
+export { AgentErrors } from './errors.js';
+export { BedrockModels, OllamaModels } from './models.js';
+export declare 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);
+}
+//# sourceMappingURL=index.cdk.d.ts.map

package/dist/index.cdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cdk.d.ts","sourceRoot":"","sources":["../src/index.cdk.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAQpD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAO1D,qBAAa,KAAM,SAAQ,KAAK;IAC/B;;;;;;OAMG;gBACS,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG;CAwCxD"}

package/dist/index.cdk.js

@@ -0,0 +1,60 @@
+// 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 { 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, id, config) {
+        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/dist/index.hooks.d.ts

@@ -0,0 +1,122 @@
+/**
+ * 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;
+}
+/**
+ * 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 declare function useChat(options: UseChatOptions): ChatInstance;
+//# sourceMappingURL=index.hooks.d.ts.map

package/dist/index.hooks.d.ts.map

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

package/dist/index.hooks.js

@@ -0,0 +1,179 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+let messageCounter = 0;
+function nextId() {
+    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) {
+    let messages = [];
+    let loading = false;
+    let conversationId = null;
+    let activeSub = null;
+    let assistantId = null;
+    let assistantText = '';
+    /** Handle a chunk from the Realtime subscription. */
+    function handleChunk(chunk) {
+        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) {
+        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) {
+            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 = { id: nextId(), role: 'user', content: text };
+            const aMsg = { 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) {
+            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', 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 = { 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) {
+            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,
+                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/dist/index.mock.d.ts

@@ -0,0 +1,5 @@
+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';
+//# sourceMappingURL=index.mock.d.ts.map

package/dist/index.mock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mock.d.ts","sourceRoot":"","sources":["../src/index.mock.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC1D,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.mock.js

@@ -0,0 +1,5 @@
+// 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';

package/dist/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/dist/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":""}