@aws-blocks/bb-agent 0.1.0

package/dist/agent.aws.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.aws.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent.aws.d.ts","sourceRoot":"","sources":["../src/agent.aws.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;CAGzE"}

package/dist/agent.aws.js

@@ -0,0 +1,9 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { AgentBase } from './agent.js';
+import { S3Storage } from '@strands-agents/sdk/session/s3-storage';
+export class Agent extends AgentBase {
+    constructor(scope, id, config) {
+        super(scope, id, config, config.model.deployed, (bucket) => new S3Storage({ bucket: bucket.fullId }));
+    }
+}

package/dist/agent.d.ts

@@ -0,0 +1,121 @@
+import { Scope } from '@aws-blocks/core';
+import type { ScopeParent } from '@aws-blocks/core';
+import { FileBucket } from '@aws-blocks/bb-file-bucket';
+import type { ChildLogger } from '@aws-blocks/bb-logger';
+import type { SnapshotStorage } from '@strands-agents/sdk';
+import type { AgentConfig, AgentStreamResult, StreamOptions, Message, Conversation, ModelConfig, InterruptResponse, DefaultToolContext } from './types.js';
+/**
+ * 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 declare class AgentBase<TContext = DefaultToolContext> extends Scope {
+    /** Developer-facing agent configuration. */
+    private config;
+    /** Tools resolved from the `tools` callback into a name→tool map (name = Record key). */
+    private toolMap;
+    /** Conversation metadata table. */
+    private conversations?;
+    /** Message history table. */
+    private messages?;
+    /** Realtime pub/sub — streams chunks to browser. */
+    private rt;
+    /** Internal async job — runs the Strands agent in a separate execution context. */
+    private job;
+    /** Which model provider to use. */
+    private modelConfig;
+    /** Where to persist Strands agent state (snapshots). */
+    private snapshotStorage;
+    /** Internal FileBucket for session storage. */
+    private sessionBucket;
+    /** @internal Logger for internal operations. Defaults to error-level when not provided. */
+    protected log: ChildLogger;
+    /**
+     * @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: ScopeParent, id: string, config: AgentConfig<TContext>, modelConfig: ModelConfig | ModelConfig[] | undefined, createSnapshotStorage: (bucket: FileBucket) => SnapshotStorage);
+    /**
+     * 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
+     */
+    private runAgent;
+    private createStrandsAgent;
+    /**
+     * 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.
+     */
+    stream(message: string, options?: StreamOptions<TContext>): Promise<AgentStreamResult>;
+    /**
+     * 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.
+     */
+    resume(channelId: string, responses: Array<InterruptResponse>, options?: {
+        conversationId?: string;
+        userId?: string;
+        context?: TContext;
+    }): Promise<void>;
+    /**
+     * 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.
+     */
+    private resolveContext;
+    /** Generate a new conversation ID and create the conversation record. */
+    createConversationId(userId: string): Promise<string>;
+    /** Get a Realtime channel for streaming chunks. Use this to subscribe before calling stream(). */
+    getChannel(channelId: string): Promise<import("@aws-blocks/bb-realtime").RealtimeChannel<any>>;
+    /** 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.
+     */
+    getPendingInterrupts(conversationId: string): Promise<Array<{
+        id: string;
+        name: string;
+        reason?: any;
+    }>>;
+    /** List all conversations for a user. */
+    listConversations(userId: string): Promise<Conversation[]>;
+    /** 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
+     */
+    getConversation(id: string, options?: {
+        limit?: number;
+    }): Promise<Message[]>;
+    /** Delete a conversation and its agent state. */
+    deleteConversation(id: string, userId: string): Promise<void>;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

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