@aws-blocks/bb-agent 0.4.0 → 0.4.1

package/README.md

@@ -763,7 +763,8 @@ export const api = new ApiNamespace(scope, 'api', (context) => ({
     return { conversationId: await agent.createConversationId(userId) };
   },
   async sendMessage(conversationId: string, message: string, channelId: string, userId: string) {
-    await agent.stream(message, { conversationId, channelId, userId });
+    const result = await agent.stream(message, { conversationId, channelId, userId });
+    return { channelId: result.channelId };
   },
   async getConversation(conversationId: string) {
     const messages = await agent.getConversation(conversationId);
@@ -803,7 +804,87 @@ await chat.sendMessage('Hello!');
 await chat.loadConversation('conv-123');
 ```
 
-### 2. Support Agent with Tools
+The example above is framework-agnostic on purpose — `useChat` has no React import and works with any UI layer. The two examples below show how to bridge it into a specific framework's reactivity.
+
+### 2. React: hold the instance once, drive `useState` from the callbacks
+
+`useChat` is a factory, not a React hook, so it must **not** run on every render — recreating it drops the WebSocket subscription and conversation state each time. Hold the single instance in a `useRef` (created lazily so it survives re-renders), and turn the `onMessagesChange` / `onLoadingChange` / `onInterrupt` callbacks into `setState` calls so React re-renders when the mutable instance changes. This example keeps the `api` wiring minimal — it omits the `userId` that the End-to-End example (#1) threads through `createConversation` / `sendMessage`; thread it the same way here when your API needs it (or resolve the user server-side).
+
+```tsx
+'use client'; // Next.js only — see the note below. Plain React (Vite/CRA) can omit this.
+
+import { useRef, useState, useEffect } from 'react';
+import { useChat, type ChatMessage } from '@aws-blocks/bb-agent/client';
+import { api } from './api'; // your generated aws-blocks API client
+
+export function Chat() {
+  const [messages, setMessages] = useState<ChatMessage[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [input, setInput] = useState('');
+
+  // Create the instance exactly once. The ref survives every re-render,
+  // so the subscription and conversation state are never torn down.
+  // Type the ref as `| undefined` and initialize with `undefined` — @types/react 19
+  // tightened the useRef overloads, so a bare useRef<T>() no longer compiles.
+  const chatRef = useRef<ReturnType<typeof useChat> | undefined>(undefined);
+  if (!chatRef.current) {
+    // eslint-disable-next-line react-hooks/rules-of-hooks -- useChat is a factory, not a hook; the use-prefix trips the linter's hook heuristic.
+    chatRef.current = useChat({
+      api: {
+        sendMessage: (convId, msg, chId) => api.sendMessage(convId, msg, chId),
+        createConversation: () => api.createConversation(),
+        getConversation: (id) => api.getConversation(id),
+      },
+      subscribe: async (channelId, handler) => {
+        const channel = await api.getChannel(channelId);
+        return channel.subscribe(handler);
+      },
+      // Bridge the mutable instance into React state — these fire on every change.
+      onMessagesChange: setMessages,
+      onLoadingChange: setIsLoading,
+    });
+  }
+  const chat = chatRef.current!; // guaranteed set by the block above
+
+  // Tear down the WebSocket subscription when the component unmounts.
+  useEffect(() => () => chat.destroy(), [chat]);
+
+  async function handleSend(e: React.FormEvent) {
+    e.preventDefault();
+    const text = input.trim();
+    if (!text || isLoading) return;
+    setInput('');
+    await chat.sendMessage(text);
+  }
+
+  return (
+    <div>
+      <ul>
+        {messages.map((m) => (
+          <li key={m.id} data-role={m.role}>
+            <strong>{m.role}:</strong> {m.content}
+          </li>
+        ))}
+      </ul>
+      <form onSubmit={handleSend}>
+        <input value={input} onChange={(e) => setInput(e.target.value)} disabled={isLoading} />
+        <button type="submit" disabled={isLoading}>Send</button>
+      </form>
+    </div>
+  );
+}
+```
+
+Key points:
+
+- **One instance, held in a ref.** `useRef` + the lazy `if (!chatRef.current)` guard is the React idiom for "construct once." Because the identifier is `use`-prefixed, `eslint-plugin-react-hooks` (bundled in the default Next.js and CRA configs) flags the guarded call as a conditional hook (`react-hooks/rules-of-hooks`). `useChat` is a factory, not a hook, so this is a false positive — the inline `eslint-disable-next-line` above the call silences it. What you must **not** do is call `useChat(...)` unguarded on every render: that recreates the instance each time and is the footgun the factory note warns about.
+- **Callbacks are your reactivity bridge.** `useChat` mutates its own message list in place; `onMessagesChange` / `onLoadingChange` hand you the new value so you can `setState` and trigger a render. Passing `setMessages` / `setIsLoading` directly is enough.
+- **Clean up on unmount** with `chat.destroy()` in a `useEffect` cleanup, so the Realtime subscription is closed.
+- **Approvals:** wire `resume: (chId, responses, convId) => api.resume(chId, responses, convId)` into the `api` object above (mirroring your backend's resume method — `respondToInterrupt` throws if it is absent), add `onInterrupt: setInterrupts` (with `const [interrupts, setInterrupts] = useState<Array<{ id: string; name: string; reason?: unknown }>>([])` — a bare `useState([])` infers `never[]` and rejects the payload) to render an approval UI, then call `chat.respondToInterrupt([{ interruptId, approved: true }])`.
+
+**Next.js:** this is the same component — just keep the `'use client'` directive at the top of the file. `useChat` opens a browser WebSocket and holds client state, so it must run in a Client Component, never a Server Component. No other changes are needed.
+
+### 3. Support Agent with Tools
 
 Agent with tools that can look up orders and search documentation. Uses tool context to scope queries to the authenticated user.
 

package/dist/index.cdk.d.ts

@@ -1,9 +1,9 @@
-import { Scope } from '@aws-blocks/core/cdk';
+import { BuildingBlockScope } from '@aws-blocks/core/cdk';
 import type { ScopeParent } from '@aws-blocks/core';
 import type { AgentConfig } from './types.js';
 export { AgentErrors } from './errors.js';
 export { BedrockModels, OllamaModels } from './models.js';
-export declare class Agent extends Scope {
+export declare class Agent extends BuildingBlockScope {
     /**
      * CDK layer for the Agent BB.
      *

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

@@ -1 +1 @@
-{"version":3,"file":"index.cdk.d.ts","sourceRoot":"","sources":["../src/index.cdk.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAMpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE1D,qBAAa,KAAM,SAAQ,KAAK;IAC/B;;;;;;;;;;;OAWG;gBACS,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW;CAyChE"}
+{"version":3,"file":"index.cdk.d.ts","sourceRoot":"","sources":["../src/index.cdk.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAOpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE1D,qBAAa,KAAM,SAAQ,kBAAkB;IAC5C;;;;;;;;;;;OAWG;gBACS,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW;CAyChE"}

package/dist/index.cdk.js

@@ -1,14 +1,15 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
-import { Scope } from '@aws-blocks/core/cdk';
+import { BuildingBlockScope } from '@aws-blocks/core/cdk';
 import { DistributedTable } from '@aws-blocks/bb-distributed-table';
 import { Realtime } from '@aws-blocks/bb-realtime';
 import { FileBucket } from '@aws-blocks/bb-file-bucket';
+import * as ec2 from 'aws-cdk-lib/aws-ec2';
 import { AgentCoreRuntime } from './agentcore-runtime.cdk.js';
 import { messageSchema, conversationSchema, agentStreamChunkSchema } from './schemas.js';
 export { AgentErrors } from './errors.js';
 export { BedrockModels, OllamaModels } from './models.js';
-export class Agent extends Scope {
+export class Agent extends BuildingBlockScope {
     /**
      * CDK layer for the Agent BB.
      *
@@ -22,7 +23,7 @@ export class Agent extends Scope {
      * handler no longer needs Bedrock access — the runtime's own role gets it (see AgentCoreRuntime).
      */
     constructor(scope, id, config) {
-        super(id, { parent: scope });
+        super(id, { parent: scope, vpc: { interfaceEndpoints: [ec2.InterfaceVpcEndpointAwsService.BEDROCK_RUNTIME] } });
         // Session-snapshot bucket. Provisioned here (and granted to the shared execution role that the
         // AgentCore Runtime runs as); the deployed loop re-derives its name from this bucket's `fullId`
         // in-process — the same `'sn'` id → same fullId → same physical bucket — so no name needs to be

package/dist/index.hooks.d.ts

@@ -22,7 +22,7 @@ export interface ChatMessage {
 /** Options for creating a chat instance. */
 export interface UseChatOptions {
     api: {
-        sendMessage(conversationId: string, message: string, channelId: string): Promise<void>;
+        sendMessage(conversationId: string, message: string, channelId: string): Promise<unknown>;
         createConversation(): Promise<{
             conversationId: string;
         }>;
@@ -39,7 +39,7 @@ export interface UseChatOptions {
             trust?: boolean;
             toolName?: string;
             input?: any;
-        }>, conversationId?: string): Promise<void>;
+        }>, conversationId?: string): Promise<unknown>;
         getPendingInterrupts?(conversationId: string): Promise<{
             interrupts: Array<{
                 id: string;

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

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

package/dist/index.test.js

@@ -1029,6 +1029,28 @@ describe('model-factory', () => {
 // ── useChat ──────────────────────────────────────────────────────────────────
 import { useChat } from './index.hooks.js';
 describe('useChat', () => {
+    // Type-only regression guard for the api return-type contract (PR that widened
+    // sendMessage/resume from Promise<void> to Promise<unknown>). This is compiled by
+    // `tsc --build` before the runtime tests execute, so narrowing either member back
+    // to Promise<void> fails CI here — the durable proof the manual PR check could not
+    // commit. `unknown` must accept BOTH a natural object-returning backend and a
+    // void-returning one; both assignments below must type-check.
+    test('api sendMessage/resume accept object- and void-returning backends (type-only)', () => {
+        const objectBackend = {
+            sendMessage: async () => ({ channelId: 'c' }),
+            createConversation: async () => ({ conversationId: 'c' }),
+            getConversation: async () => ({ messages: [] }),
+            resume: async () => ({ ok: true }),
+        };
+        const voidBackend = {
+            sendMessage: async () => { },
+            createConversation: async () => ({ conversationId: 'c' }),
+            getConversation: async () => ({ messages: [] }),
+            resume: async () => { },
+        };
+        assert.ok(objectBackend.sendMessage);
+        assert.ok(voidBackend.sendMessage);
+    });
     test('onError is called when error chunk arrives', async () => {
         let chunkHandler;
         let errorReceived;

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 export declare const BB_NAME = "Agent";
-export declare const BB_VERSION = "0.4.0";
+export declare const BB_VERSION = "0.4.1";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,3 @@
 // Auto-generated by scripts/generate-version.mjs — do not edit manually
 export const BB_NAME = 'Agent';
-export const BB_VERSION = '0.4.0';
+export const BB_VERSION = '0.4.1';

package/package.json

@@ -1,6 +1,14 @@
 {
   "name": "@aws-blocks/bb-agent",
-  "version": "0.4.0",
+  "version": "0.4.1",
+  "keywords": [
+    "aws-blocks",
+    "ai",
+    "agent",
+    "llm",
+    "bedrock",
+    "chatbot"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/aws-devtools-labs/aws-blocks.git",
@@ -47,11 +55,11 @@
     "test": "node --test dist/index.test.js && node --conditions=cdk --test dist/index.cdk.test.js && node --test dist/agentcore-bundle.test.js"
   },
   "dependencies": {
-    "@aws-blocks/bb-distributed-table": "^0.1.7",
-    "@aws-blocks/bb-file-bucket": "^0.2.0",
-    "@aws-blocks/bb-logger": "^0.1.6",
-    "@aws-blocks/bb-realtime": "^0.2.0",
-    "@aws-blocks/core": "^0.4.0",
+    "@aws-blocks/bb-distributed-table": "^0.2.0",
+    "@aws-blocks/bb-file-bucket": "^0.2.1",
+    "@aws-blocks/bb-logger": "^0.2.0",
+    "@aws-blocks/bb-realtime": "^0.2.1",
+    "@aws-blocks/core": "^0.5.0",
     "@aws-sdk/client-bedrock": "^3.700.0",
     "@aws-sdk/client-bedrock-agentcore": "^3.700.0",
     "@opentelemetry/api": "^1.9.0",
@@ -63,7 +71,7 @@
     "zod": "^4.1.12"
   },
   "devDependencies": {
-    "@aws-blocks/bb-lambda-compute": "^0.4.0",
+    "@aws-blocks/bb-lambda-compute": "^0.5.0",
     "@aws-sdk/client-bedrock-runtime": "^3.700.0",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "@types/node": "^20.0.0",

package/src/index.cdk.ts

@@ -1,11 +1,12 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { Scope } from '@aws-blocks/core/cdk';
+import { BuildingBlockScope } 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 { FileBucket } from '@aws-blocks/bb-file-bucket';
+import * as ec2 from 'aws-cdk-lib/aws-ec2';
 import { AgentCoreRuntime } from './agentcore-runtime.cdk.js';
 import { messageSchema, conversationSchema, agentStreamChunkSchema } from './schemas.js';
 import type { AgentConfig } from './types.js';
@@ -13,7 +14,7 @@ import type { AgentConfig } from './types.js';
 export { AgentErrors } from './errors.js';
 export { BedrockModels, OllamaModels } from './models.js';
 
-export class Agent extends Scope {
+export class Agent extends BuildingBlockScope {
 	/**
 	 * CDK layer for the Agent BB.
 	 *
@@ -27,7 +28,7 @@ export class Agent extends Scope {
 	 * handler no longer needs Bedrock access — the runtime's own role gets it (see AgentCoreRuntime).
 	 */
 	constructor(scope: ScopeParent, id: string, config?: AgentConfig) {
-		super(id, { parent: scope });
+		super(id, { parent: scope, vpc: { interfaceEndpoints: [ec2.InterfaceVpcEndpointAwsService.BEDROCK_RUNTIME] } });
 
 		// Session-snapshot bucket. Provisioned here (and granted to the shared execution role that the
 		// AgentCore Runtime runs as); the deployed loop re-derives its name from this bucket's `fullId`

package/src/index.hooks.ts

@@ -29,10 +29,10 @@ export interface ChatMessage {
 /** Options for creating a chat instance. */
 export interface UseChatOptions {
 	api: {
-		sendMessage(conversationId: string, message: string, channelId: string): Promise<void>;
+		sendMessage(conversationId: string, message: string, channelId: string): Promise<unknown>;
 		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>;
+		resume?(channelId: string, responses: Array<{ interruptId: string; approved: boolean; trust?: boolean; toolName?: string; input?: any }>, conversationId?: string): Promise<unknown>;
 		getPendingInterrupts?(conversationId: string): Promise<{ interrupts: Array<{ id: string; name: string; reason?: any }> }>;
 	};
 	/**

package/src/index.test.ts

@@ -1185,8 +1185,32 @@ describe('model-factory', () => {
 // ── useChat ──────────────────────────────────────────────────────────────────
 
 import { useChat } from './index.hooks.js';
+import type { UseChatOptions } from './index.hooks.js';
 
 describe('useChat', () => {
+	// Type-only regression guard for the api return-type contract (PR that widened
+	// sendMessage/resume from Promise<void> to Promise<unknown>). This is compiled by
+	// `tsc --build` before the runtime tests execute, so narrowing either member back
+	// to Promise<void> fails CI here — the durable proof the manual PR check could not
+	// commit. `unknown` must accept BOTH a natural object-returning backend and a
+	// void-returning one; both assignments below must type-check.
+	test('api sendMessage/resume accept object- and void-returning backends (type-only)', () => {
+		const objectBackend: UseChatOptions['api'] = {
+			sendMessage: async () => ({ channelId: 'c' }),
+			createConversation: async () => ({ conversationId: 'c' }),
+			getConversation: async () => ({ messages: [] }),
+			resume: async () => ({ ok: true }),
+		};
+		const voidBackend: UseChatOptions['api'] = {
+			sendMessage: async () => {},
+			createConversation: async () => ({ conversationId: 'c' }),
+			getConversation: async () => ({ messages: [] }),
+			resume: async () => {},
+		};
+		assert.ok(objectBackend.sendMessage);
+		assert.ok(voidBackend.sendMessage);
+	});
+
 	test('onError is called when error chunk arrives', async () => {
 		let chunkHandler: (chunk: any) => void;
 		let errorReceived: string | undefined;

package/src/version.ts

@@ -1,3 +1,3 @@
 // Auto-generated by scripts/generate-version.mjs — do not edit manually
 export const BB_NAME = 'Agent';
-export const BB_VERSION = '0.4.0';
+export const BB_VERSION = '0.4.1';