fix(examples): reject incomplete multi-agent streams (#2666)

## Summary

Require a coordinator `response.completed` event before the multi-agent
SSE example treats stream termination as success. The production change
is six added lines in the handwritten example.

Child-agent completion/failure remains nonterminal for the coordinator.
The example still consumes the stream after coordinator completion,
preserving explicit root failures, named SSE errors, and transport
errors rather than hiding them with an early break.

## Reproduction

On current main, the actual executable example exits successfully when
the server sends `[DONE]` or closes the SSE body before the coordinator
completes—even with only partial coordinator text or a completed/failed
child agent. Ten new executable regressions fail before the source
change, while fourteen controls pass.

## Validation

- Final example suite: 25/25 tests pass on exact Node 22.0.0, Node
24.19.0, and Node 26.7.0.
- Covers empty/partial/child-only EOF and `[DONE]`,
omitted/null/explicit root ownership, child-status continuation, and a
named SSE error received after coordinator completion.
- Independent public built CommonJS/ESM checks pass on Node 22/24/26,
including later root failures, malformed SSE, transport-error identity,
output preservation, and existing sentinel behavior.
- Full canonical handwritten suite: 7,817 tests pass across 205 files.
- Canonical format, lint, TypeScript checking, build, and `git diff
--check` pass. The entire built SDK is byte-for-byte identical to the
base build.
- Adversarial review completed against the final source and test hashes
with no remaining findings.

Only the example and its existing regression-test file change. No SDK
runtime/parser changes, generated files, dependencies, new payload
limits, or WebSocket changes. All inputs and responses are synthetic; no
live API calls. This complements the existing explicit-terminal-error
handling and the separate WebSocket early-close fix.

Author: HAYDEN-OAI

examples/responses/multi-agent-streaming.ts

@@ -19,6 +19,7 @@ async function main() {
 
   const agents = new Map<string, string>();
   let currentItemID: string | undefined;
+  let coordinatorCompleted = false;
   for await (const event of stream) {
     if (event.type === 'response.output_item.added' && event.item.type === 'message') {
       agents.set(event.item.id, event.item.agent?.agent_name ?? '/root');
@@ -31,13 +32,18 @@ async function main() {
         process.stdout.write(`${separator}━━━ ${role}: ${name} ━━━\n\n`);
       }
       process.stdout.write(event.delta);
+    } else if (event.type === 'response.completed' && (!event.agent || event.agent.agent_name === '/root')) {
+      coordinatorCompleted = true;
     } else if (
       (event.type === 'response.failed' || event.type === 'response.incomplete') &&
       (!event.agent || event.agent.agent_name === '/root')
     ) {
       throw new Error(`Response ended with ${event.type}.`);
     }
   }
+  if (!coordinatorCompleted) {
+    throw new Error('Stream ended before the coordinator response completed.');
+  }
   process.stdout.write('\n');
 }
 

tests/lib/multi-agent-streaming-example.test.ts

@@ -40,7 +40,7 @@ const textEvent: BetaResponseStreamEvent = {
   sequence_number: 0,
 };
 
-async function runExample(events: BetaResponseStreamEvent[]) {
+async function runExample(events: readonly BetaResponseStreamEvent[], ending: 'done' | 'eof' = 'done') {
   const requests: { url: string | undefined; body: unknown }[] = [];
   const server = createServer((request, response) => {
     let body = '';
@@ -53,7 +53,7 @@ async function runExample(events: BetaResponseStreamEvent[]) {
       for (const [sequence_number, event] of events.entries()) {
         response.write(`event: ${event.type}\ndata: ${JSON.stringify({ ...event, sequence_number })}\n\n`);
       }
-      response.end('data: [DONE]\n\n');
+      response.end(ending === 'done' ? 'data: [DONE]\n\n' : '');
     });
   });
   server.listen(0, '127.0.0.1');
@@ -131,6 +131,46 @@ test.each([
   expect(result.stdout).toBe(partialOutput ? '━━━ Coordinator: /root ━━━\n\nSynthetic answer' : '');
 });
 
+test.each(
+  (['done', 'eof'] as const).flatMap((ending) => [
+    { name: 'no events', events: [], ending },
+    { name: 'partial coordinator text', events: [textEvent], ending },
+    ...(['completed', 'failed', 'incomplete'] as const).map((status) => ({
+      name: `only a child with ${status} status`,
+      events: [{ ...terminalEvent(status), agent: { agent_name: '/root/alpha' } }],
+      ending,
+    })),
+  ]),
+)('rejects $ending after $name without coordinator completion', async ({ name, events, ending }) => {
+  const result = await runExample(events, ending);
+
+  expect(result.exitCode).toBe(1);
+  expect(result.stderr).toContain('Stream ended before the coordinator response completed.');
+  expect(result.stderr).not.toContain('Synthetic private detail');
+  expect(result.stdout).toBe(
+    name === 'partial coordinator text' ? '━━━ Coordinator: /root ━━━\n\nSynthetic answer' : '',
+  );
+});
+
+test.each(
+  (['done', 'eof'] as const).flatMap((ending) =>
+    [
+      { ownership: 'omitted', agent: undefined },
+      { ownership: 'null', agent: null },
+      { ownership: 'explicit root', agent: { agent_name: '/root' } },
+    ].map((owner) => ({ ...owner, ending })),
+  ),
+)('accepts $ending after coordinator completion with $ownership ownership', async ({ agent, ending }) => {
+  const result = await runExample(
+    [textEvent, { ...terminalEvent('completed'), ...(agent === undefined ? {} : { agent }) }],
+    ending,
+  );
+
+  expect(result.exitCode).toBe(0);
+  expect(result.stderr).toBe('');
+  expect(result.stdout).toBe('━━━ Coordinator: /root ━━━\n\nSynthetic answer\n');
+});
+
 test.each(['completed', 'failed', 'incomplete'] as const)(
   'continues to a successful root response after a child response is %s',
   async (status) => {
@@ -162,18 +202,22 @@ test.each(['completed', 'failed', 'incomplete'] as const)(
   },
 );
 
-test('preserves SDK error handling for a named SSE error frame', async () => {
-  const result = await runExample([
-    {
-      type: 'error',
-      code: 'server_error',
-      message: 'Synthetic SSE error',
-      param: null,
-      sequence_number: 0,
-    },
-  ]);
+test.each([false, true])(
+  'preserves a named SSE error after coordinator completion: %s',
+  async (completed) => {
+    const result = await runExample([
+      ...(completed ? [terminalEvent('completed')] : []),
+      {
+        type: 'error',
+        code: 'server_error',
+        message: 'Synthetic SSE error',
+        param: null,
+        sequence_number: 0,
+      },
+    ]);
 
-  expect(result.exitCode).toBe(1);
-  expect(result.stderr).toContain('APIError: Synthetic SSE error');
-  expect(result.stdout).toBe('');
-});
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain('APIError: Synthetic SSE error');
+    expect(result.stdout).toBe('');
+  },
+);