@aws-blocks/bb-agent 0.1.0

package/dist/agent.js

@@ -0,0 +1,588 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { Scope, registerSdkIdentifiers, getSdkIdentifiers } 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 { Logger } from '@aws-blocks/bb-logger';
+import { Agent as StrandsAgent, tool, SessionManager, ModelStreamUpdateEvent, AfterToolCallEvent, BeforeToolCallEvent, AgentResultEvent } from '@strands-agents/sdk';
+import { InterruptResponseContent } from '@strands-agents/sdk';
+import { z } from 'zod';
+import { createStrandsModel, checkModelHealth } from './model-factory.js';
+import { messageSchema, conversationSchema, agentStreamChunkSchema } from './schemas.js';
+import { AgentErrors, blocksAgentError, InterruptError } from './errors.js';
+import { SlidingWindowConversationManager, SummarizingConversationManager } from '@strands-agents/sdk';
+import { BB_NAME, BB_VERSION } from './version.js';
+import { ulid } from 'ulid';
+/** Payload submitted to the internal AsyncJob BB. */
+const jobPayloadSchema = z.object({
+    message: z.string(),
+    conversationId: z.string().optional(),
+    channelId: z.string(),
+    userId: z.string(),
+    resume: z.boolean().optional(), // Resume fields (for HITL interrupt responses)
+    interruptResponses: z.array(z.object({ interruptId: z.string(), response: z.string() })).optional(),
+    /** Per-call tool context, forwarded to tool invocations. JSON-serializable. */
+    context: z.any().optional(),
+});
+/** Key under which the per-call tool context is threaded through Strands `invocationState`. */
+const TOOL_CONTEXT_KEY = '__bbAgentToolContext';
+/**
+ * The per-call tool factory handed to the `tools` callback. At runtime it's an identity
+ * function whose only job is to give TypeScript a single call site per tool where it can
+ * infer `TParams` (hence `input`) and apply the unforgeable brand. See `ToolFactory`.
+ */
+const makeTool = (tool) => tool;
+/**
+ * Resolve the developer's `tools` callback into a name→tool map.
+ * The Record key is the canonical tool name (overrides any `name` on the definition).
+ */
+function resolveTools(toolsConfig) {
+    const map = new Map();
+    if (!toolsConfig)
+        return map;
+    const record = toolsConfig(makeTool);
+    for (const [name, def] of Object.entries(record)) {
+        // Record key is the source of truth for the tool name.
+        map.set(name, { ...def, name });
+    }
+    return map;
+}
+/**
+ * Maps ConversationManagerConfig to Strands' ConversationManager.
+ * Controls how message history is trimmed in-memory before sending to the model. Does not handle persistence.
+ * @see https://strandsagents.com/docs/user-guide/concepts/agents/conversation-management/
+ */
+function createConversationManager(config) {
+    if (!config || !config.strategy || config.strategy === 'sliding-window') {
+        const windowSize = config && 'windowSize' in config ? config.windowSize : undefined;
+        return new SlidingWindowConversationManager({ windowSize });
+    }
+    if (config.strategy === 'summarizing') {
+        return new SummarizingConversationManager({
+            summaryRatio: config.summaryRatio,
+            preserveRecentMessages: config.preserveRecentMessages,
+        });
+    }
+}
+/**
+ * Base class for the Agent BB. Extended by agent.mock.ts (model.local) and agent.aws.ts (model.deployed).
+ *
+ * Creates up to 4 internal BBs depending on mode:
+ * - FileBucket: session snapshot storage for Strands SessionManager (always)
+ * - DistributedTable: frontend message history (when inferenceOnly = false)
+ * - Realtime: streaming chunks to browser + AsyncJob result delivery (always)
+ * - AsyncJob: runs Strands agent asynchronously (always)
+ * - TODO logging
+ */
+export class AgentBase extends Scope {
+    /** Developer-facing agent configuration. */
+    config;
+    /** Tools resolved from the `tools` callback into a name→tool map (name = Record key). */
+    toolMap;
+    /** Conversation metadata table. */
+    conversations;
+    /** Message history table. */
+    messages;
+    /** Realtime pub/sub — streams chunks to browser. */
+    rt;
+    /** Internal async job — runs the Strands agent in a separate execution context. */
+    job;
+    /** Which model provider to use. */
+    modelConfig;
+    /** Where to persist Strands agent state (snapshots). */
+    snapshotStorage;
+    /** Internal FileBucket for session storage. */
+    sessionBucket;
+    /** @internal Logger for internal operations. Defaults to error-level when not provided. */
+    log;
+    /**
+     * @param scope - Blocks scope parent (determines resource naming and CDK discovery)
+     * @param id - unique agent ID (used in resource names, keep short for AppSync namespace limits)
+     * @param config - developer-facing agent configuration
+     * @param modelConfig - which model to use, picked by subclass (model.local or model.deployed)
+     * @param createSnapshotStorage - factory that receives the internal FileBucket and returns the appropriate SnapshotStorage
+     */
+    constructor(scope, id, config, modelConfig, createSnapshotStorage) {
+        super(id, { parent: scope, bbName: BB_NAME, bbVersion: BB_VERSION });
+        this.log = config?.logger ?? new Logger(this, 'logger', { level: 'error' });
+        this.config = config;
+        this.toolMap = resolveTools(config.tools);
+        this.modelConfig = modelConfig;
+        // IDs shortened to keep S3 bucket names within the 63-char limit
+        this.sessionBucket = new FileBucket(this, 'sn');
+        this.snapshotStorage = createSnapshotStorage(this.sessionBucket);
+        if (!config.inferenceOnly) {
+            this.conversations = new DistributedTable(this, 'convos', {
+                schema: conversationSchema,
+                key: { partitionKey: 'userId', sortKey: 'conversationId' },
+            });
+            this.messages = new DistributedTable(this, 'messages', {
+                schema: messageSchema,
+                key: { partitionKey: 'conversationId', sortKey: 'messageId' },
+            });
+        }
+        this.rt = new Realtime(this, 'rt', {
+            namespaces: {
+                chunks: Realtime.namespace(agentStreamChunkSchema),
+            },
+        });
+        this.job = new AsyncJob(this, 'job', {
+            schema: jobPayloadSchema,
+            handler: async (payload) => {
+                try {
+                    await this.runAgent(payload.message, payload.conversationId, payload.channelId, payload.userId, payload.interruptResponses, payload.context);
+                }
+                catch (err) {
+                    const errorMessage = err instanceof Error ? err.message : String(err);
+                    this.log.error('runAgent error', { error: errorMessage });
+                    // Best-effort: persist error to conversation history (don't let DB failure block error chunk)
+                    try {
+                        if (payload.conversationId && this.messages) {
+                            await this.messages.put({ conversationId: payload.conversationId, messageId: ulid(), role: 'assistant', content: '', contentType: 'text', userId: payload.userId, createdAt: Date.now(), metadata: JSON.stringify({ error: errorMessage }) });
+                        }
+                    }
+                    catch (persistErr) {
+                        this.log.error('Failed to persist error to history', { error: persistErr });
+                    }
+                    // Publish error chunk so the client doesn't hang. Don't re-throw — AsyncJob would retry a non-idempotent operation.
+                    await this.rt.publish('chunks', payload.channelId, { type: 'error', error: errorMessage });
+                }
+            },
+        });
+        const identifiers = {};
+        if (this.conversations) {
+            identifiers.conversationsTableName = getSdkIdentifiers(this.conversations).tableName;
+        }
+        if (this.messages) {
+            identifiers.messagesTableName = getSdkIdentifiers(this.messages).tableName;
+        }
+        identifiers.sessionBucketName = getSdkIdentifiers(this.sessionBucket).bucketName;
+        identifiers.realtimeWsUrl = getSdkIdentifiers(this.rt).wsUrl;
+        identifiers.realtimeCallbackUrl = getSdkIdentifiers(this.rt).callbackUrl;
+        identifiers.jobQueueUrl = getSdkIdentifiers(this.job).queueUrl;
+        registerSdkIdentifiers(this.fullId, identifiers);
+    }
+    /**
+     * Executes the Strands agent, publishes chunks to Realtime, persists messages to DynamoDB.
+     *
+     * Called by: AsyncJob consumer.
+     * NOT called directly — stream() submits to AsyncJob, which invokes this.
+     *
+     * Flow: AsyncJob handler → runAgent() → Strands agent.stream() → publishes chunks to Realtime BB
+     * TODO add comments for args
+     */
+    async runAgent(message, conversationId, channelId, userId, interruptResponses, context) {
+        const strandsAgent = await this.createStrandsAgent(conversationId, context);
+        const startTime = Date.now();
+        // Only persist user message on initial path (not resume)
+        if (!interruptResponses && conversationId && this.messages) {
+            await this.messages.put({ conversationId, messageId: ulid(), role: 'user', content: message, contentType: 'text', userId, createdAt: Date.now(), metadata: '{}' });
+        }
+        let fullText = '';
+        let usage;
+        let blockBuffer = '';
+        let interrupted = false;
+        const isBlockMode = this.config.streamingMode !== 'token';
+        // Determine input: resume with responses or initial message
+        const input = interruptResponses
+            ? interruptResponses.map(r => new InterruptResponseContent({ interruptId: r.interruptId, response: r.response }))
+            : message;
+        this.log.info('runAgent started', { resume: !!interruptResponses, conversationId });
+        // Thread the per-call context through Strands invocationState so it reaches
+        // tool callbacks and the interrupt hook (see createStrandsAgent).
+        const invocationState = { [TOOL_CONTEXT_KEY]: context ?? {} };
+        try {
+            for await (const event of strandsAgent.stream(input, { invocationState })) {
+                if (event instanceof ModelStreamUpdateEvent) {
+                    if (event.event.type === 'modelContentBlockDeltaEvent' && event.event.delta.type === 'textDelta') {
+                        fullText += event.event.delta.text;
+                        if (isBlockMode) {
+                            blockBuffer += event.event.delta.text;
+                        }
+                        else {
+                            await this.rt.publish('chunks', channelId, { type: 'text-delta', text: event.event.delta.text });
+                        }
+                    }
+                    else if (isBlockMode && event.event.type === 'modelContentBlockStopEvent' && blockBuffer) {
+                        await this.rt.publish('chunks', channelId, { type: 'text-delta', text: blockBuffer });
+                        blockBuffer = '';
+                    }
+                }
+                else if (event instanceof BeforeToolCallEvent) {
+                    await this.rt.publish('chunks', channelId, { type: 'tool-call', toolName: event.toolUse.name, input: event.toolUse.input });
+                    if (conversationId && this.messages) {
+                        await this.messages.put({ conversationId, messageId: ulid(), role: 'tool-call', content: '', contentType: 'text', userId, createdAt: Date.now(), metadata: JSON.stringify({ toolName: event.toolUse.name, toolInput: event.toolUse.input }) });
+                    }
+                }
+                else if (event instanceof AfterToolCallEvent) {
+                    await this.rt.publish('chunks', channelId, { type: 'tool-result', toolName: event.toolUse.name });
+                    if (conversationId && this.messages) {
+                        await this.messages.put({ conversationId, messageId: ulid(), role: 'tool-result', content: '', contentType: 'text', userId, createdAt: Date.now(), metadata: JSON.stringify({ toolName: event.toolUse.name, toolOutput: event.result?.content }) });
+                    }
+                }
+                else if (event instanceof AgentResultEvent) {
+                    const u = event.result.metrics?.toJSON()?.accumulatedUsage;
+                    if (u)
+                        usage = { inputTokens: u.inputTokens, outputTokens: u.outputTokens, totalTokens: u.totalTokens };
+                    // Check if agent was interrupted
+                    if (event.result.stopReason === 'interrupt' && event.result.interrupts?.length) {
+                        interrupted = true;
+                        // Flush partial block buffer before publishing interrupt
+                        if (blockBuffer) {
+                            await this.rt.publish('chunks', channelId, { type: 'text-delta', text: blockBuffer });
+                            blockBuffer = '';
+                        }
+                        // Publish interrupt chunk with pending approvals
+                        const pendingInterrupts = event.result.interrupts.map(i => ({ id: i.id, name: i.name, reason: i.reason }));
+                        await this.rt.publish('chunks', channelId, {
+                            type: 'interrupt',
+                            interrupts: pendingInterrupts,
+                        });
+                        // Persist interrupt to DynamoDB for reload/audit
+                        if (conversationId && this.messages) {
+                            await this.messages.put({ conversationId, messageId: ulid(), role: 'interrupt', content: '', contentType: 'text', userId, createdAt: Date.now(), metadata: JSON.stringify({ interrupts: pendingInterrupts }) });
+                        }
+                    }
+                }
+            }
+        }
+        catch (err) {
+            // Flush partial block buffer so client gets whatever text was generated before the error
+            if (blockBuffer) {
+                await this.rt.publish('chunks', channelId, { type: 'text-delta', text: blockBuffer });
+                blockBuffer = '';
+            }
+            throw err;
+        }
+        // Normal flush (stream completed successfully)
+        if (blockBuffer) {
+            await this.rt.publish('chunks', channelId, { type: 'text-delta', text: blockBuffer });
+        }
+        const latencyMs = Date.now() - startTime;
+        this.log.info('runAgent done', { textLength: fullText.length, latencyMs, interrupted });
+        // If interrupted, don't persist final message or publish done — agent is paused
+        if (interrupted)
+            return;
+        if (conversationId && this.messages) {
+            await this.messages.put({ conversationId, messageId: ulid(), role: 'assistant', content: fullText, contentType: 'text', userId, createdAt: Date.now(), metadata: JSON.stringify({ usage, latencyMs }) });
+        }
+        // TODO: use partial update when DistributedTable supports it (DynamoDB UpdateItem)
+        if (conversationId && this.conversations) {
+            const existing = await this.conversations.get({ userId, conversationId });
+            if (existing) {
+                await this.conversations.put({ ...existing, updatedAt: Date.now() });
+            }
+        }
+        await this.rt.publish('chunks', channelId, { type: 'done', text: fullText, usage });
+    }
+    async createStrandsAgent(conversationId, fallbackContext) {
+        const toolDefs = [...this.toolMap.values()];
+        // Validate mutual exclusivity of needsApproval/trustable and interrupt
+        for (const t of toolDefs) {
+            if ((t.needsApproval !== undefined || t.trustable !== undefined) && t.interrupt) {
+                throw blocksAgentError(AgentErrors.InvalidModelConfig, `Cannot specify 'needsApproval' or 'trustable' alongside 'interrupt' on tool '${t.name}'. Use 'interrupt' for custom logic, or 'needsApproval'/'trustable' for simple approval.`);
+            }
+        }
+        // Reads the per-call context threaded through invocationState, falling back to the
+        // context captured at runAgent time (defensive — Strands always provides invocationState).
+        const readContext = (strandsCtx) => (strandsCtx?.invocationState?.[TOOL_CONTEXT_KEY] ?? fallbackContext ?? {});
+        const strandsTools = toolDefs.map(t => tool({
+            // `name` is always set by resolveTools() from the Record key.
+            name: t.name,
+            description: t.description,
+            inputSchema: t.parameters,
+            callback: (input, context) => t.handler({
+                input,
+                context: readContext(context),
+                interrupt: (params) => context.interrupt(params),
+            }),
+        }));
+        const configs = Array.isArray(this.modelConfig) ? this.modelConfig : this.modelConfig ? [this.modelConfig] : [];
+        let resolvedConfig;
+        for (const config of configs) {
+            if (await checkModelHealth(config, this.log)) {
+                resolvedConfig = config;
+                break;
+            }
+        }
+        if (!resolvedConfig && configs.length > 0) {
+            const tried = configs.map(c => `${c.provider}${c.modelId ? ` (${c.modelId})` : ''}`).join(', ');
+            throw blocksAgentError(AgentErrors.ModelUnavailable, `No model available. Tried: ${tried}. Check logs for details.`);
+        }
+        const model = await createStrandsModel(resolvedConfig, this.log);
+        // SessionManager restores/saves agent state across invocations.
+        // undefined when no conversationId (inference-only calls — no state to persist).
+        const sessionManager = conversationId
+            ? new SessionManager({ sessionId: conversationId, storage: { snapshot: this.snapshotStorage } })
+            : undefined;
+        const agent = new StrandsAgent({
+            model,
+            // Forward the optional agent identity from AgentConfig. Strands' Agent
+            // supports name/description (e.g. for multi-agent routing and tracing);
+            // previously these AgentConfig fields were accepted but never passed
+            // through, so they silently had no effect. Spread conditionally so we
+            // don't override Strands defaults with `undefined` when unset.
+            ...(this.config.name !== undefined && { name: this.config.name }),
+            ...(this.config.description !== undefined && { description: this.config.description }),
+            systemPrompt: this.config.systemPrompt,
+            tools: strandsTools,
+            conversationManager: createConversationManager(this.config.conversation),
+            sessionManager,
+            printer: false, //disable Strands automatic printing
+        });
+        // Register interrupt hook for HITL — checks needsApproval or custom interrupt function before execution
+        const toolConfigs = this.toolMap;
+        agent.addHook(BeforeToolCallEvent, (event) => {
+            const toolDef = toolConfigs.get(event.toolUse.name);
+            if (!toolDef)
+                return;
+            // Custom interrupt function — developer has full control
+            if (toolDef.interrupt) {
+                toolDef.interrupt({
+                    input: event.toolUse.input,
+                    context: readContext(event),
+                    interrupt: (params) => event.interrupt(params),
+                });
+                return;
+            }
+            // Built-in approval check
+            const needsApproval = toolDef.needsApproval ?? false;
+            if (!needsApproval)
+                return;
+            if (toolDef.trustable && event.agent.appState.get(`trusted:${event.toolUse.name}`))
+                return;
+            this.log.info('Tool approval required, interrupting', { tool: event.toolUse.name, trustable: !!toolDef.trustable });
+            const response = event.interrupt({ name: `approve:${event.toolUse.name}:${event.toolUse.toolUseId}`, reason: { tool: event.toolUse.name, input: event.toolUse.input, trustable: !!toolDef.trustable } });
+            if (response === 'trust') {
+                event.agent.appState.set(`trusted:${event.toolUse.name}`, true);
+                this.log.info('Tool trusted for session', { tool: event.toolUse.name });
+            }
+            else if (response !== 'yes') {
+                event.cancel = `User denied permission to run ${event.toolUse.name}`;
+                this.log.info('Tool denied by user', { tool: event.toolUse.name });
+            }
+        });
+        return agent;
+    }
+    /**
+     * Submit a message to the agent. Returns immediately with a channelId.
+     *
+     * Flow: stream() → AsyncJob.submit() → returns { channelId }
+     * The AsyncJob consumer calls runAgent() separately.
+     * Chunks are published to Realtime on the returned channelId.
+     *
+     * Subscribe to chunks via result.channel, or await result.complete() for the final response.
+     */
+    async stream(message, options) {
+        const conversationId = options?.conversationId;
+        const channelId = options?.channelId ?? conversationId ?? crypto.randomUUID();
+        if (!options?.userId && !this.config.inferenceOnly)
+            throw blocksAgentError(AgentErrors.PersistenceRequired, 'userId is required when persistence is enabled. Pass it via options.userId.');
+        const userId = options?.userId ?? 'anonymous';
+        const context = this.resolveContext(options?.context);
+        await this.job.submit({ message, conversationId, channelId, userId, context });
+        return {
+            channelId,
+            /** Realtime channel handle — subscribe to streaming chunks or return to client as Transferable. */
+            channel: this.rt.getChannel('chunks', channelId),
+            /** Wait for the complete response (server-side). Resolves on done, rejects on error. */
+            complete: () => new Promise((resolve, reject) => {
+                const unsub = this.rt.subscribe('chunks', channelId, (data) => {
+                    const chunk = data;
+                    if (chunk.type === 'done') {
+                        unsub();
+                        resolve(chunk);
+                    }
+                    else if (chunk.type === 'error') {
+                        unsub();
+                        reject(blocksAgentError(AgentErrors.StreamFailed, chunk.error ?? 'Agent error'));
+                    }
+                    else if (chunk.type === 'interrupt') {
+                        unsub();
+                        reject(new InterruptError('Agent requires approval to continue', chunk.interrupts ?? []));
+                    }
+                });
+            }),
+        };
+    }
+    /**
+     * Resume an interrupted agent with user's responses.
+     * Submits a new AsyncJob that loads the session and continues from the interrupt point.
+     * Chunks are published to the same channelId — use the existing subscription or call complete() again to wait for the result.
+     */
+    async resume(channelId, responses, options) {
+        if (!responses.length)
+            throw blocksAgentError(AgentErrors.InterruptRequired, 'resume() requires at least one interrupt response.');
+        this.log.info('Resuming agent', { channelId, responseCount: responses.length, conversationId: options?.conversationId });
+        const conversationId = options?.conversationId;
+        // Resuming an interrupted agent requires restoring its paused state, which
+        // only the SessionManager (keyed by conversationId) holds. Without a
+        // conversationId there is no session to restore, so the resume job would run
+        // with a fresh agent and the interrupt responses would have nothing to apply
+        // to. Fail fast with a clear error instead of silently submitting a job that
+        // can't honor the responses. For inferenceOnly agents this is a fundamental
+        // limitation (they never persist a session), not a missing parameter — call
+        // that out explicitly so developers don't go looking for a workaround.
+        if (!conversationId) {
+            const reason = this.config.inferenceOnly
+                ? 'Agents with inferenceOnly: true cannot be resumed because they have no persistent session to restore.'
+                : 'Pass options.conversationId so the interrupted session can be restored.';
+            throw blocksAgentError(AgentErrors.InterruptRequired, `resume() requires a conversationId to restore the interrupted session. ${reason}`);
+        }
+        if (!options?.userId && !this.config.inferenceOnly)
+            throw blocksAgentError(AgentErrors.PersistenceRequired, 'userId is required when persistence is enabled. Pass it via options.userId.');
+        const userId = options?.userId ?? 'anonymous';
+        // Persist each decision to conversation history
+        if (conversationId && this.messages) {
+            for (const r of responses) {
+                const content = r.response != null ? String(r.response) : r.approved ? (r.trust ? 'trust' : 'yes') : 'no';
+                await this.messages.put({ conversationId, messageId: ulid(), role: 'approval', content, contentType: 'text', userId, createdAt: Date.now(), metadata: JSON.stringify({ interruptId: r.interruptId, approved: r.approved, trust: r.trust ?? false, response: r.response, toolName: r.toolName, input: r.input }) });
+            }
+        }
+        // Translate to format for Strands — use response directly if provided, otherwise translate from approved/trust
+        const translated = responses.map(r => ({
+            interruptId: r.interruptId,
+            response: r.response != null ? String(r.response) : r.approved ? (r.trust ? 'trust' : 'yes') : 'no',
+        }));
+        const context = this.resolveContext(options?.context);
+        await this.job.submit({ message: '', conversationId, channelId, userId, resume: true, interruptResponses: translated, context });
+    }
+    /**
+     * Validates the per-call tool context against `toolContextSchema` (when set) and returns it.
+     * Throws InvalidModelConfig when the schema is declared but the context is missing or invalid.
+     */
+    resolveContext(context) {
+        const schema = this.config.toolContextSchema;
+        if (!schema)
+            return context;
+        const result = schema.safeParse(context);
+        if (!result.success) {
+            throw blocksAgentError(AgentErrors.InvalidModelConfig, `Invalid tool context: ${result.error.message}. This agent declares a 'toolContextSchema', so a matching 'context' must be passed to stream()/resume().`);
+        }
+        return result.data;
+    }
+    /** Generate a new conversation ID and create the conversation record. */
+    async createConversationId(userId) {
+        if (!this.conversations)
+            throw blocksAgentError(AgentErrors.PersistenceRequired, 'createConversationId() requires persistence. Set inferenceOnly: false (default).');
+        const conversationId = crypto.randomUUID();
+        const now = Date.now();
+        await this.conversations.put({ userId, conversationId, name: conversationId, createdAt: now, updatedAt: now });
+        return conversationId;
+    }
+    /** Get a Realtime channel for streaming chunks. Use this to subscribe before calling stream(). */
+    getChannel(channelId) {
+        return this.rt.getChannel('chunks', channelId);
+    }
+    /** Check if a conversation has pending (unanswered) interrupts by checking DynamoDB history.
+     *
+     * ⚠️ Does NOT verify ownership — it reads by conversationId alone. The caller must
+     * authorize the request (e.g. confirm the conversation belongs to the authenticated
+     * user via listConversations(userId)) before exposing the result. See the
+     * "Authorization (caller responsibility)" section in the README.
+     *
+     * TODO: optimize — query in reverse with limit instead of loading all messages.
+     */
+    async getPendingInterrupts(conversationId) {
+        if (!this.messages)
+            return [];
+        // Single pass in reverse: collect approval IDs until we hit the interrupt
+        const approvedIds = new Set();
+        let lastInterrupt = null;
+        for await (const msg of this.messages.query({ where: { conversationId: { equals: conversationId } }, order: 'desc' })) {
+            if (msg.role === 'approval') {
+                approvedIds.add(JSON.parse(msg.metadata).interruptId);
+            }
+            else if (msg.role === 'interrupt') {
+                lastInterrupt = msg;
+                break;
+            }
+            else if (msg.role === 'assistant') {
+                return [];
+            }
+        }
+        if (!lastInterrupt)
+            return [];
+        const interrupts = JSON.parse(lastInterrupt.metadata).interrupts;
+        return interrupts.filter(i => !approvedIds.has(i.id));
+    }
+    /** List all conversations for a user. */
+    async listConversations(userId) {
+        if (!this.conversations)
+            throw blocksAgentError(AgentErrors.PersistenceRequired, 'listConversations() requires persistence. Set inferenceOnly: false (default).');
+        const result = [];
+        for await (const item of this.conversations.query({ where: { userId: { equals: userId } } })) {
+            result.push({ conversationId: item.conversationId, name: item.name, createdAt: item.createdAt, updatedAt: item.updatedAt });
+        }
+        return result.sort((a, b) => b.updatedAt - a.updatedAt);
+    }
+    /** Get messages in a conversation (for frontend display).
+     * Returns the most recent messages when `limit` is specified.
+     *
+     * ⚠️ Does NOT verify ownership — it reads by conversationId alone. The caller must
+     * authorize the request (e.g. confirm the conversation belongs to the authenticated
+     * user via listConversations(userId)) before returning messages. See the
+     * "Authorization (caller responsibility)" section in the README.
+     *
+     * @param options.limit - Maximum number of (most recent) messages to return.
+     *   A `limit` of `0` returns an empty array, and any negative value is treated
+     *   the same as `0` (returns no messages). Omit `limit` to return all messages.
+     * TODO: support pagination
+     */
+    async getConversation(id, options) {
+        if (!this.messages)
+            throw blocksAgentError(AgentErrors.PersistenceRequired, 'getConversation() requires persistence. Set inferenceOnly: false (default).');
+        // A limit of 0 means "zero messages", and a negative limit is nonsensical
+        // for a message count. The previous `options?.limit && ...` guard treated 0
+        // (and never reached the negative case usefully) as falsy, so the cap was
+        // ignored and ALL messages were returned. Treat any limit <= 0 as "return no
+        // messages" so neither 0 nor a negative value is silently read as "no limit".
+        if (options?.limit !== undefined && options.limit <= 0)
+            return [];
+        const result = [];
+        for await (const item of this.messages.query({ where: { conversationId: { equals: id } }, order: 'desc' })) {
+            result.push({
+                messageId: item.messageId,
+                role: item.role,
+                content: item.content,
+                contentType: item.contentType,
+                createdAt: item.createdAt,
+                metadata: JSON.parse(item.metadata),
+            });
+            // Explicit undefined check so a valid positive limit caps results; 0 and
+            // negatives are already handled above.
+            if (options?.limit !== undefined && result.length >= options.limit)
+                break;
+        }
+        return result.reverse();
+    }
+    /** Delete a conversation and its agent state. */
+    async deleteConversation(id, userId) {
+        if (!this.messages || !this.conversations)
+            throw blocksAgentError(AgentErrors.PersistenceRequired, 'deleteConversation() requires persistence. Set inferenceOnly: false (default).');
+        // Verify ownership before any destructive work. The messages table is
+        // partitioned by conversationId (not userId) and snapshot storage is keyed
+        // by sessionId alone, so deleting them is NOT user-scoped on its own. The
+        // conversation record IS keyed by { userId, conversationId }, so its absence
+        // means the caller is not the owner (or the conversation doesn't exist).
+        // Without this guard, a non-owner could wipe another user's message history
+        // and session state while the owner's conversation record (a no-op keyed
+        // delete) survived. Bail out unless the caller owns the conversation.
+        const owned = await this.conversations.get({ userId, conversationId: id });
+        if (!owned)
+            return;
+        // Delete conversation record first — if it fails mid-way, orphaned messages are invisible (better than broken conversation with missing messages)
+        await this.conversations.delete({ userId, conversationId: id });
+        // Delete all messages in batch
+        const toDelete = [];
+        for await (const item of this.messages.query({ where: { conversationId: { equals: id } } })) {
+            toDelete.push({ conversationId: item.conversationId, messageId: item.messageId });
+        }
+        if (toDelete.length > 0)
+            await this.messages.deleteBatch(toDelete);
+        // Delete agent session data
+        await this.snapshotStorage.deleteSession({ sessionId: id });
+    }
+}

package/dist/agent.mock.d.ts

@@ -0,0 +1,7 @@
+import type { ScopeParent } from '@aws-blocks/core';
+import { AgentBase } from './agent.js';
+import type { AgentConfig, DefaultToolContext } from './types.js';
+export declare class Agent<TContext = DefaultToolContext> extends AgentBase<TContext> {
+    constructor(scope: ScopeParent, id: string, config: AgentConfig<TContext>);
+}
+//# sourceMappingURL=agent.mock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent.mock.d.ts","sourceRoot":"","sources":["../src/agent.mock.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAElE,qBAAa,KAAK,CAAC,QAAQ,GAAG,kBAAkB,CAAE,SAAQ,SAAS,CAAC,QAAQ,CAAC;gBAChE,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC;CAMzE"}

package/dist/agent.mock.js

@@ -0,0 +1,12 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { AgentBase } from './agent.js';
+import { FileBucketSnapshotStorage } from './file-bucket-snapshot-storage.js';
+export class Agent extends AgentBase {
+    constructor(scope, id, config) {
+        // Canned provider is appended as implicit last fallback for local dev
+        const local = config.model.local;
+        const candidates = local ? (Array.isArray(local) ? [...local, { provider: 'canned' }] : [local, { provider: 'canned' }]) : [{ provider: 'canned' }];
+        super(scope, id, config, candidates, (bucket) => new FileBucketSnapshotStorage(bucket));
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 declare const AgentErrors: {
+    readonly PersistenceRequired: "PersistenceRequiredException";
+    readonly InvalidModelConfig: "InvalidModelConfigException";
+    readonly ModelUnavailable: "ModelUnavailableException";
+    readonly BrowserNotSupported: "BrowserNotSupportedException";
+    readonly StreamFailed: "StreamFailedException";
+    readonly InterruptRequired: "InterruptRequiredException";
+};
+export declare function blocksAgentError(name: string, message: string): Error;
+export declare class InterruptError extends Error {
+    readonly interrupts: Array<{
+        id: string;
+        name: string;
+        reason?: any;
+    }>;
+    constructor(message: string, interrupts: Array<{
+        id: string;
+        name: string;
+        reason?: any;
+    }>);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,WAAW;;;;;;;CAOd,CAAC;AAEX,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,CAIrE;AAED,qBAAa,cAAe,SAAQ,KAAK;IACxC,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,GAAG,CAAA;KAAE,CAAC,CAAC;gBAE3D,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,GAAG,CAAA;KAAE,CAAC;CAK1F"}