fix(bb-agent): add toJSON() to AgentStreamResult

.changeset/fix-bb-agent-stream-result-tojson.md

@@ -0,0 +1,7 @@
+---
+"@aws-blocks/bb-agent": patch
+---
+
+fix(bb-agent): add toJSON() to AgentStreamResult
+
+`AgentStreamResult` now serializes to `{ channelId, channel: null }` when returned from API methods. Previously `channel` serialized to an empty object `{}`; it is now explicitly `null` to signal it is server-side only.

packages/bb-agent/API.md

@@ -93,6 +93,10 @@ export interface AgentStreamResult {
     channel: Promise<RealtimeChannel<AgentStreamChunk>>;
     channelId: string;
     complete: () => Promise<AgentStreamChunk>;
+    toJSON(): {
+        channelId: string;
+        channel: null;
+    };
 }
 
 // @public

packages/bb-agent/src/agent.ts

@@ -9,14 +9,14 @@
 import { FileBucket } from '@aws-blocks/bb-file-bucket';
 import { Logger } from '@aws-blocks/bb-logger';
 import type { ChildLogger } from '@aws-blocks/bb-logger';
 import { Agent as StrandsAgent, tool, SessionManager, ModelStreamUpdateEvent, AfterToolCallEvent, BeforeToolCallEvent, AgentResultEvent, InterruptEvent } from '@strands-agents/sdk';
 import type { AgentResult } from '@strands-agents/sdk';
 import { InterruptResponseContent } from '@strands-agents/sdk';
 import { z } from 'zod';
 import { createStrandsModel, checkModelHealth } from './model-factory.js';
 import type { SnapshotStorage } from '@strands-agents/sdk';
 import { messageSchema, conversationSchema, agentStreamChunkSchema } from './schemas.js';
 import type { AgentConfig, AgentStreamChunk, AgentStreamResult, StreamOptions, Message, Conversation, TokenUsage, ConversationManagerConfig, ModelConfig, JSONValue, InterruptResponse, DefaultToolContext, AgentTool, ToolDefinition } from './types.js';
 import { AgentErrors, blocksAgentError, InterruptError } from './errors.js';
 import { SlidingWindowConversationManager, SummarizingConversationManager } from '@strands-agents/sdk';
 import { BB_NAME, BB_VERSION } from './version.js';
@@ -67,7 +67,7 @@
  * @see https://strandsagents.com/docs/user-guide/concepts/agents/conversation-management/
  */
 function createConversationManager(config?: ConversationManagerConfig) {
 	if (!config || !config.strategy || config.strategy === 'sliding-window') {
 		const windowSize = config && 'windowSize' in config ? config.windowSize : undefined;
 		return new SlidingWindowConversationManager({ windowSize });
 	}
@@ -313,13 +313,13 @@
 
 		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),
 			}),
 		}));
 
@@ -428,6 +428,7 @@
 					}
 				});
 			}),
+			toJSON() { return { channelId, channel: null }; },
 		};
 	}
 

packages/bb-agent/src/index.test.ts

@@ -115,6 +115,19 @@
 	});
 });
 
+// ── AgentStreamResult.toJSON() ───────────────────────────────────────────────
+
+describe('AgentStreamResult.toJSON()', () => {
+	test('serializes to { channelId, channel: null }', async () => {
+		const scope = new Scope('test-tojson');
+		const agent = new Agent(scope, 'tj', { systemPrompt: 'test', model: { deployed: { provider: 'canned' }, local: { provider: 'canned' } } });
+		const result = await agent.stream('hello', { userId: 'test-user' });
+		const serialized = JSON.parse(JSON.stringify(result));
+		assert.deepStrictEqual(serialized, { channelId: result.channelId, channel: null });
+		assert.strictEqual('complete' in serialized, false);
+	});
+});
+
 // ── tool factory enforcement (compile-time) ──────────────────────────────────
 
 describe('tool factory enforcement', () => {
@@ -727,7 +740,7 @@
 
 		await chat.sendMessage('hello');
 		// Simulate error chunk from server
 		chunkHandler!({ type: 'error', error: 'model throttled' });
 
 		assert.strictEqual(errorReceived, 'model throttled');
 		assert.strictEqual(loadingStates.at(-1), false, 'loading should be false after error');
@@ -753,11 +766,11 @@
 		});
 
 		await chat.sendMessage('hello');
 		chunkHandler!({ type: 'interrupt', interrupts: [{ id: 'int-1', name: 'approve:deleteRecords', reason: { tool: 'deleteRecords' } }] });
 
 		assert.ok(interruptsReceived, 'onInterrupt should be called');
 		assert.strictEqual(interruptsReceived!.length, 1);
 		assert.strictEqual(interruptsReceived![0].name, 'approve:deleteRecords');
 		assert.strictEqual(loadingStates.at(-1), false, 'loading should be false after interrupt');
 	});
 

packages/bb-agent/src/types.ts

@@ -264,14 +264,30 @@ export interface StreamOptions<TContext = DefaultToolContext> {
 	context?: TContext;
 }
 
-/** Returned by stream(). Provides the channelId and server-side convenience methods. */
+/**
+ * Returned by stream(). Provides the channelId and server-side convenience methods.
+ *
+ * Safe to return directly from API methods — `toJSON()` serializes to
+ * `{ channelId, channel: null }`. Only `channelId` is meaningful client-side;
+ * `channel` is explicitly `null` to signal the live handle is server-side only,
+ * and the `complete()` helper is dropped (functions don't serialize).
+ */
 export interface AgentStreamResult {
 	/** Realtime channel ID where chunks are published. */
 	channelId: string;
-	/** Realtime channel handle — subscribe to streaming chunks or return to client as Transferable. */
+	/**
+	 * Realtime channel handle (server-side only). Nulled by `toJSON()` — clients subscribe from `channelId` instead.
+	 *
+	 * @remarks
+	 * Unlike `RealtimeChannel.toJSON()` which produces a hydratable descriptor, this is nulled
+	 * because it's a `Promise` that can't round-trip. Clients reconstruct a subscribe-only
+	 * channel from `channelId` via the `useChat` `subscribe` callback.
+	 */
 	channel: Promise<RealtimeChannel<AgentStreamChunk>>;
 	/** Wait for the complete response (server-side). Resolves when the done chunk arrives. */
 	complete: () => Promise<AgentStreamChunk>;
+	/** Only `{ channelId, channel: null }` is serialized when this object crosses the RPC boundary. */
+	toJSON(): { channelId: string; channel: null };
 }
 
 export interface AgentStreamChunk {