@crewhaus/streaming-tool-executor 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,898 +0,0 @@
1
- import { afterEach, describe, expect, mock, test } from "bun:test";
2
- import type Anthropic from "@anthropic-ai/sdk";
3
- /**
4
- * Coverage-completion suite for `streaming-tool-executor`.
5
- *
6
- * The sibling `index.test.ts` / `load.test.ts` exercise the happy paths.
7
- * This file targets the remaining branches: thinking blocks, usage
8
- * merging, external-abort wiring, the concurrency scheduler's safe/unsafe
9
- * gate, malformed-JSON recovery, the `error` stream event, the wrapping
10
- * `catch`, the `runTool`/`executeTool` rejection path, and the
11
- * multi-pass in-flight drain.
12
- *
13
- * Everything is driven off in-memory `AsyncIterable<StreamEvent>`s and
14
- * hand-rolled deferred promises — no real timers, sockets, or filesystem
15
- * — so the runner exits cleanly with no leaked handles or unsettled
16
- * streams.
17
- */
18
- import type { StreamEvent, TokenUsage } from "@crewhaus/adapter-anthropic";
19
- import { buildTool } from "@crewhaus/tool-builder";
20
- import type { RegisteredTool } from "@crewhaus/tool-catalog";
21
- import { z } from "zod";
22
- import { type StreamingToolEvent, executeStreaming } from "./index";
23
-
24
- // ---------- helpers ---------- //
25
-
26
- /** Yield a fixed list of events as an async iterable (one microtask apart). */
27
- function streamOf(events: StreamEvent[]): AsyncIterable<StreamEvent> {
28
- return (async function* () {
29
- for (const e of events) {
30
- yield e;
31
- }
32
- })();
33
- }
34
-
35
- /** A deferred promise whose resolve/reject are exposed for the test. */
36
- function deferred<T>(): {
37
- promise: Promise<T>;
38
- resolve: (v: T) => void;
39
- reject: (e: unknown) => void;
40
- } {
41
- let resolve!: (v: T) => void;
42
- let reject!: (e: unknown) => void;
43
- const promise = new Promise<T>((res, rej) => {
44
- resolve = res;
45
- reject = rej;
46
- });
47
- return { promise, resolve, reject };
48
- }
49
-
50
- /**
51
- * Deterministically drain the microtask queue until `pred()` is true or a
52
- * fixed budget of turns is spent. No real timers — each turn is a single
53
- * resolved-promise await, so the `for await` stream loop and any settled
54
- * tool promises get a chance to advance. The bounded budget means a wrong
55
- * expectation fails fast instead of hanging the runner.
56
- */
57
- async function flushUntil(pred: () => boolean, maxTurns = 200): Promise<void> {
58
- for (let i = 0; i < maxTurns && !pred(); i++) {
59
- await Promise.resolve();
60
- }
61
- }
62
-
63
- function toolUseEvents(id: string, name: string, input: unknown, index: number): StreamEvent[] {
64
- return [
65
- {
66
- kind: "content_block_start",
67
- index,
68
- block: { type: "tool_use", id, name, input: {} },
69
- },
70
- {
71
- kind: "content_block_delta",
72
- index,
73
- delta: { type: "input_json_delta", partial_json: JSON.stringify(input) },
74
- },
75
- { kind: "content_block_stop", index },
76
- ];
77
- }
78
-
79
- function safeReadTool(name = "Read"): RegisteredTool {
80
- return buildTool({
81
- name,
82
- description: "safe read",
83
- inputSchema: z.object({}).passthrough(),
84
- readOnly: true,
85
- concurrencySafe: true,
86
- execute: async () => `ok:${name}`,
87
- });
88
- }
89
-
90
- afterEach(() => {
91
- // Restore any module mocks installed by individual tests so later
92
- // tests (and other files) see the real implementations.
93
- mock.restore();
94
- });
95
-
96
- // ---------- thinking blocks (296-316, 410-414) ---------- //
97
-
98
- describe("thinking blocks", () => {
99
- test("accumulates thinking + signature deltas into finalContent", async () => {
100
- const stream = streamOf([
101
- { kind: "message_start" },
102
- {
103
- kind: "content_block_start",
104
- index: 0,
105
- block: { type: "thinking", thinking: "seed " },
106
- },
107
- {
108
- kind: "content_block_delta",
109
- index: 0,
110
- delta: { type: "thinking_delta", thinking: "more" },
111
- },
112
- {
113
- kind: "content_block_delta",
114
- index: 0,
115
- delta: { type: "signature_delta", signature: "sig-123" },
116
- },
117
- { kind: "content_block_stop", index: 0 },
118
- { kind: "message_stop" },
119
- ]);
120
- const result = await executeStreaming(stream, { toolByName: new Map() });
121
- expect(result.finalContent).toEqual([
122
- { type: "thinking", thinking: "seed more", signature: "sig-123" },
123
- ]);
124
- });
125
-
126
- test("thinking block carries an initial signature from content_block_start", async () => {
127
- const stream = streamOf([
128
- { kind: "message_start" },
129
- {
130
- kind: "content_block_start",
131
- index: 0,
132
- block: { type: "thinking", thinking: "redacted", signature: "pre-sig" },
133
- },
134
- { kind: "content_block_stop", index: 0 },
135
- { kind: "message_stop" },
136
- ]);
137
- const result = await executeStreaming(stream, { toolByName: new Map() });
138
- expect(result.finalContent[0]).toEqual({
139
- type: "thinking",
140
- thinking: "redacted",
141
- signature: "pre-sig",
142
- });
143
- });
144
-
145
- test("thinking block without a signature omits the field in finalContent", async () => {
146
- const stream = streamOf([
147
- { kind: "message_start" },
148
- {
149
- kind: "content_block_start",
150
- index: 0,
151
- block: { type: "thinking", thinking: "no sig" },
152
- },
153
- { kind: "content_block_stop", index: 0 },
154
- { kind: "message_stop" },
155
- ]);
156
- const result = await executeStreaming(stream, { toolByName: new Map() });
157
- expect(result.finalContent[0]).toEqual({ type: "thinking", thinking: "no sig" });
158
- expect(result.finalContent[0]).not.toHaveProperty("signature");
159
- });
160
- });
161
-
162
- // ---------- usage merging (message_start + message_delta, 352-365) ---------- //
163
-
164
- describe("usage accounting", () => {
165
- test("message_start usage seeds, message_delta merges all four fields", async () => {
166
- const stream = streamOf([
167
- {
168
- kind: "message_start",
169
- usage: { input: 10, output: 0, cacheRead: 3, cacheCreate: 4 },
170
- },
171
- {
172
- kind: "message_delta",
173
- stopReason: "end_turn",
174
- usage: { input: 0, output: 25, cacheRead: 7, cacheCreate: 8 },
175
- },
176
- { kind: "message_stop" },
177
- ]);
178
- const result = await executeStreaming(stream, { toolByName: new Map() });
179
- // input falls back to seeded 10 (delta.input == 0), output takes delta 25,
180
- // cacheRead/cacheCreate take the delta values.
181
- expect(result.usage).toEqual({
182
- input: 10,
183
- output: 25,
184
- cacheRead: 7,
185
- cacheCreate: 8,
186
- });
187
- expect(result.stopReason).toBe("end_turn");
188
- });
189
-
190
- test("message_delta keeps prior cache fields when delta omits them", async () => {
191
- const stream = streamOf([
192
- {
193
- kind: "message_start",
194
- usage: { input: 5, output: 1, cacheRead: 99, cacheCreate: 88 },
195
- },
196
- {
197
- // delta has positive input/output but NO cache fields → carry prior.
198
- kind: "message_delta",
199
- usage: { input: 50, output: 60 },
200
- },
201
- { kind: "message_stop" },
202
- ]);
203
- const result = await executeStreaming(stream, { toolByName: new Map() });
204
- expect(result.usage).toEqual({
205
- input: 50,
206
- output: 60,
207
- cacheRead: 99,
208
- cacheCreate: 88,
209
- });
210
- });
211
-
212
- test("message_delta with neither delta nor prior cache fields stays uncached", async () => {
213
- const stream = streamOf([
214
- { kind: "message_start", usage: { input: 2, output: 2 } },
215
- { kind: "message_delta", usage: { input: 0, output: 0 } },
216
- { kind: "message_stop" },
217
- ]);
218
- const result = await executeStreaming(stream, { toolByName: new Map() });
219
- expect(result.usage).toEqual({ input: 2, output: 2 });
220
- expect(result.usage).not.toHaveProperty("cacheRead");
221
- expect(result.usage).not.toHaveProperty("cacheCreate");
222
- });
223
-
224
- test("message_delta without a usage field leaves usage untouched", async () => {
225
- const stream = streamOf([
226
- { kind: "message_start", usage: { input: 11, output: 22 } },
227
- { kind: "message_delta", stopReason: "max_tokens" },
228
- { kind: "message_stop" },
229
- ]);
230
- const result = await executeStreaming(stream, { toolByName: new Map() });
231
- expect(result.usage).toEqual({ input: 11, output: 22 });
232
- expect(result.stopReason).toBe("max_tokens");
233
- });
234
-
235
- test("message_start without usage keeps the zero default", async () => {
236
- const stream = streamOf([{ kind: "message_start" }, { kind: "message_stop" }]);
237
- const result = await executeStreaming(stream, { toolByName: new Map() });
238
- expect(result.usage).toEqual({ input: 0, output: 0 } satisfies TokenUsage);
239
- });
240
- });
241
-
242
- // ---------- malformed JSON recovery (328, 406) ---------- //
243
-
244
- describe("malformed tool_use JSON", () => {
245
- test("invalid jsonBuffer surfaces __parse_error in dispatch input and finalContent", async () => {
246
- const seen: unknown[] = [];
247
- const stream = streamOf([
248
- { kind: "message_start" },
249
- {
250
- kind: "content_block_start",
251
- index: 0,
252
- block: { type: "tool_use", id: "tu1", name: "Read", input: {} },
253
- },
254
- {
255
- kind: "content_block_delta",
256
- index: 0,
257
- delta: { type: "input_json_delta", partial_json: "{not valid json" },
258
- },
259
- { kind: "content_block_stop", index: 0 },
260
- { kind: "message_stop" },
261
- ]);
262
- const result = await executeStreaming(stream, {
263
- toolByName: new Map(),
264
- runTool: async (block) => {
265
- seen.push(block.input);
266
- return {
267
- type: "tool_result",
268
- tool_use_id: block.id,
269
- content: "handled",
270
- is_error: false,
271
- };
272
- },
273
- });
274
- expect(seen[0]).toEqual({ __parse_error: true, raw: "{not valid json" });
275
- // finalContent re-parses the persisted (now valid) JSON of the parse-error
276
- // object, so it round-trips the same shape.
277
- expect(result.finalContent[0]).toEqual({
278
- type: "tool_use",
279
- id: "tu1",
280
- name: "Read",
281
- input: { __parse_error: true, raw: "{not valid json" },
282
- });
283
- });
284
-
285
- test("empty jsonBuffer defaults the tool input to {}", async () => {
286
- const seen: unknown[] = [];
287
- const stream = streamOf([
288
- { kind: "message_start" },
289
- {
290
- kind: "content_block_start",
291
- index: 0,
292
- block: { type: "tool_use", id: "tu1", name: "Read", input: {} },
293
- },
294
- // No input_json_delta at all → jsonBuffer stays "".
295
- { kind: "content_block_stop", index: 0 },
296
- { kind: "message_stop" },
297
- ]);
298
- await executeStreaming(stream, {
299
- toolByName: new Map(),
300
- runTool: async (block) => {
301
- seen.push(block.input);
302
- return {
303
- type: "tool_result",
304
- tool_use_id: block.id,
305
- content: "ok",
306
- is_error: false,
307
- };
308
- },
309
- });
310
- expect(seen[0]).toEqual({});
311
- });
312
-
313
- test("a tool_use opened but never closed surfaces __parse_error in finalContent", async () => {
314
- // The block is opened (content_block_start) but the stream ends with NO
315
- // content_block_stop, so its jsonBuffer is never re-serialized and stays
316
- // "". The finalContent pass then does JSON.parse("") which throws and is
317
- // caught into a __parse_error marker. The block is never enqueued (no
318
- // stop event), so there is no tool result for it.
319
- const stream = streamOf([
320
- { kind: "message_start" },
321
- {
322
- kind: "content_block_start",
323
- index: 0,
324
- block: { type: "tool_use", id: "tu_open", name: "Read", input: {} },
325
- },
326
- {
327
- kind: "content_block_delta",
328
- index: 0,
329
- delta: { type: "input_json_delta", partial_json: '{"id":"partial' },
330
- },
331
- // No content_block_stop for index 0 — stream just ends.
332
- { kind: "message_stop" },
333
- ]);
334
- const result = await executeStreaming(stream, { toolByName: new Map() });
335
- expect(result.toolResults).toHaveLength(0);
336
- expect(result.finalContent).toEqual([
337
- {
338
- type: "tool_use",
339
- id: "tu_open",
340
- name: "Read",
341
- input: { __parse_error: true, raw: '{"id":"partial' },
342
- },
343
- ]);
344
- });
345
- });
346
-
347
- // ---------- concurrency scheduler (106, 262-269) ---------- //
348
-
349
- describe("concurrency gate", () => {
350
- test("two concurrency-safe tools run in parallel via isConcurrencySafe path", async () => {
351
- // Both reads are safe; when the second arrives while the first is still
352
- // in flight, processQueue's runningAllSafe + isConcurrencySafe gate lets
353
- // it dispatch concurrently rather than waiting.
354
- const d1 = deferred<Anthropic.ToolResultBlockParam>();
355
- const d2 = deferred<Anthropic.ToolResultBlockParam>();
356
- let started = 0;
357
- const events: StreamingToolEvent[] = [];
358
- const promise = executeStreaming(
359
- streamOf([
360
- { kind: "message_start" },
361
- ...toolUseEvents("tu1", "Read", { a: 1 }, 0),
362
- ...toolUseEvents("tu2", "Read", { a: 2 }, 1),
363
- { kind: "message_stop" },
364
- ]),
365
- {
366
- toolByName: new Map([["Read", safeReadTool()]]),
367
- onEvent: (e) => {
368
- events.push(e);
369
- if (e.kind === "tool-started") started++;
370
- },
371
- runTool: (block) => {
372
- return block.id === "tu1" ? d1.promise : d2.promise;
373
- },
374
- },
375
- );
376
- // Let the stream drain and both safe tools dispatch concurrently.
377
- await flushUntil(() => started >= 2);
378
- expect(started).toBe(2);
379
- d1.resolve({
380
- type: "tool_result",
381
- tool_use_id: "tu1",
382
- content: "r1",
383
- is_error: false,
384
- });
385
- d2.resolve({
386
- type: "tool_result",
387
- tool_use_id: "tu2",
388
- content: "r2",
389
- is_error: false,
390
- });
391
- const result = await promise;
392
- expect(result.toolResults.map((r) => r.tool_use_id)).toEqual(["tu1", "tu2"]);
393
- });
394
-
395
- test("an unsafe in-flight tool blocks a following safe tool until it drains", async () => {
396
- // tu1 is NOT concurrency-safe (a plain write-ish tool). While it runs,
397
- // tu2 (safe) must WAIT — exercising the `runningAllSafe === false → return`
398
- // branch — then dispatch only after tu1 settles.
399
- const unsafe = buildTool({
400
- name: "Write",
401
- description: "unsafe",
402
- inputSchema: z.object({}).passthrough(),
403
- // readOnly omitted → not concurrency-safe even if we set the flag.
404
- concurrencySafe: false,
405
- execute: async () => "wrote",
406
- });
407
- const order: string[] = [];
408
- const d1 = deferred<void>();
409
- const stream = streamOf([
410
- { kind: "message_start" },
411
- ...toolUseEvents("tu1", "Write", { a: 1 }, 0),
412
- ...toolUseEvents("tu2", "Read", { a: 2 }, 1),
413
- { kind: "message_stop" },
414
- ]);
415
- const promise = executeStreaming(stream, {
416
- toolByName: new Map<string, RegisteredTool>([
417
- ["Write", unsafe],
418
- ["Read", safeReadTool()],
419
- ]),
420
- onEvent: (e) => {
421
- if (e.kind === "tool-started") order.push(`start:${e.toolName}`);
422
- if (e.kind === "tool-finished") order.push(`finish:${e.toolName}`);
423
- },
424
- runTool: async (block) => {
425
- if (block.id === "tu1") {
426
- await d1.promise;
427
- }
428
- return {
429
- type: "tool_result",
430
- tool_use_id: block.id,
431
- content: block.id,
432
- is_error: false,
433
- };
434
- },
435
- });
436
- await flushUntil(() => order.includes("start:Write"));
437
- // Only the unsafe tool has started; the safe read is gated behind it.
438
- expect(order).toEqual(["start:Write"]);
439
- d1.resolve();
440
- const result = await promise;
441
- // Write finishes before Read even starts.
442
- expect(order).toEqual(["start:Write", "finish:Write", "start:Read", "finish:Read"]);
443
- expect(result.toolResults.map((r) => r.tool_use_id)).toEqual(["tu1", "tu2"]);
444
- });
445
-
446
- test("a safe tool already running blocks an unsafe follower (isConcurrencySafe(entry)=false)", async () => {
447
- // tu1 safe + in-flight; tu2 unsafe. runningAllSafe is true (only safe
448
- // running) but isConcurrencySafe(entry=tu2) is false → tu2 waits.
449
- const unsafe = buildTool({
450
- name: "Bash",
451
- description: "unsafe",
452
- inputSchema: z.object({}).passthrough(),
453
- destructive: true,
454
- execute: async () => "ran",
455
- });
456
- const order: string[] = [];
457
- const d1 = deferred<void>();
458
- const stream = streamOf([
459
- { kind: "message_start" },
460
- ...toolUseEvents("tu1", "Read", { a: 1 }, 0),
461
- ...toolUseEvents("tu2", "Bash", { a: 2 }, 1),
462
- { kind: "message_stop" },
463
- ]);
464
- const promise = executeStreaming(stream, {
465
- toolByName: new Map<string, RegisteredTool>([
466
- ["Read", safeReadTool()],
467
- ["Bash", unsafe],
468
- ]),
469
- // Bash here returns success so no sibling-abort fires.
470
- shouldAbortOnError: () => false,
471
- onEvent: (e) => {
472
- if (e.kind === "tool-started") order.push(`start:${e.toolName}`);
473
- },
474
- runTool: async (block) => {
475
- if (block.id === "tu1") await d1.promise;
476
- return {
477
- type: "tool_result",
478
- tool_use_id: block.id,
479
- content: block.id,
480
- is_error: false,
481
- };
482
- },
483
- });
484
- await flushUntil(() => order.includes("start:Read"));
485
- expect(order).toEqual(["start:Read"]);
486
- d1.resolve();
487
- const result = await promise;
488
- expect(order).toEqual(["start:Read", "start:Bash"]);
489
- expect(result.toolResults).toHaveLength(2);
490
- });
491
- });
492
-
493
- // ---------- external abort wiring (135-144) ---------- //
494
-
495
- describe("external abortSignal", () => {
496
- test("pre-aborted signal aborts queued tools synthetically (135-136)", async () => {
497
- const ac = new AbortController();
498
- ac.abort();
499
- const stream = streamOf([
500
- { kind: "message_start" },
501
- ...toolUseEvents("tu1", "Read", { a: 1 }, 0),
502
- { kind: "message_stop" },
503
- ]);
504
- let ran = false;
505
- const result = await executeStreaming(stream, {
506
- toolByName: new Map([["Read", safeReadTool()]]),
507
- abortSignal: ac.signal,
508
- runTool: async (block) => {
509
- ran = true;
510
- return {
511
- type: "tool_result",
512
- tool_use_id: block.id,
513
- content: "nope",
514
- is_error: false,
515
- };
516
- },
517
- });
518
- expect(ran).toBe(false);
519
- expect(result.toolResults[0]?.is_error).toBe(true);
520
- expect(result.toolResults[0]?.content).toContain("aborted: sibling tool failed");
521
- });
522
-
523
- test("signal that fires mid-stream aborts not-yet-dispatched tools (138-144)", async () => {
524
- const ac = new AbortController();
525
- const gate = deferred<void>();
526
- // tu1 runs (held by gate), abort fires while it is in flight, then the
527
- // drain re-runs processQueue and tu2 is aborted.
528
- const stream = (async function* (): AsyncIterable<StreamEvent> {
529
- yield { kind: "message_start" };
530
- yield* toolUseEvents("tu1", "Read", { a: 1 }, 0);
531
- yield* toolUseEvents("tu2", "Read", { a: 2 }, 1);
532
- yield { kind: "message_stop" };
533
- })();
534
- const started: string[] = [];
535
- const promise = executeStreaming(stream, {
536
- toolByName: new Map([["Read", safeReadTool()]]),
537
- abortSignal: ac.signal,
538
- onEvent: (e) => {
539
- if (e.kind === "tool-started") started.push(e.toolUseId);
540
- },
541
- runTool: async (block) => {
542
- if (block.id === "tu1") {
543
- // Trigger the external abort from inside the first tool, then block.
544
- ac.abort();
545
- await gate.promise;
546
- }
547
- return {
548
- type: "tool_result",
549
- tool_use_id: block.id,
550
- content: block.id,
551
- is_error: false,
552
- };
553
- },
554
- });
555
- // Wait until tu1 has started (so the in-tool ac.abort() has fired),
556
- // then release it; tu2 must be aborted during the drain.
557
- await flushUntil(() => started.includes("tu1") && ac.signal.aborted);
558
- gate.resolve();
559
- const result = await promise;
560
- expect(started).toEqual(["tu1"]);
561
- const r2 = result.toolResults.find((r) => r.tool_use_id === "tu2");
562
- expect(r2?.is_error).toBe(true);
563
- expect(r2?.content).toContain("aborted: sibling tool failed");
564
- });
565
- });
566
-
567
- // ---------- rejection path (229-236) ---------- //
568
-
569
- describe("rejection handling", () => {
570
- test("runTool rejection becomes a synthetic is_error result (Error message)", async () => {
571
- const stream = streamOf([
572
- { kind: "message_start" },
573
- ...toolUseEvents("tu1", "Read", { a: 1 }, 0),
574
- { kind: "message_stop" },
575
- ]);
576
- const result = await executeStreaming(stream, {
577
- toolByName: new Map([["Read", safeReadTool()]]),
578
- runTool: async () => {
579
- throw new Error("kaboom");
580
- },
581
- });
582
- expect(result.toolResults[0]).toMatchObject({
583
- tool_use_id: "tu1",
584
- content: "kaboom",
585
- is_error: true,
586
- });
587
- });
588
-
589
- test("non-Error rejection is stringified", async () => {
590
- const stream = streamOf([
591
- { kind: "message_start" },
592
- ...toolUseEvents("tu1", "Read", { a: 1 }, 0),
593
- { kind: "message_stop" },
594
- ]);
595
- const result = await executeStreaming(stream, {
596
- toolByName: new Map([["Read", safeReadTool()]]),
597
- // Reject with a plain string to hit the `String(err)` branch.
598
- runTool: () => Promise.reject("string failure"),
599
- });
600
- expect(result.toolResults[0]?.content).toBe("string failure");
601
- expect(result.toolResults[0]?.is_error).toBe(true);
602
- });
603
- });
604
-
605
- // ---------- executeTool fallback branch (runOne / no runTool) ---------- //
606
-
607
- describe("executeTool fallback (no runTool)", () => {
608
- test("dispatches through executeTool and maps a string result", async () => {
609
- const tool = buildTool({
610
- name: "Read",
611
- description: "read",
612
- inputSchema: z.object({ id: z.string() }),
613
- readOnly: true,
614
- concurrencySafe: true,
615
- execute: async (input) => `content:${input.id}`,
616
- });
617
- const stream = streamOf([
618
- { kind: "message_start" },
619
- ...toolUseEvents("tu1", "Read", { id: "x" }, 0),
620
- { kind: "message_stop" },
621
- ]);
622
- const result = await executeStreaming(stream, {
623
- toolByName: new Map([["Read", tool]]),
624
- });
625
- expect(result.toolResults[0]).toMatchObject({
626
- tool_use_id: "tu1",
627
- content: "content:x",
628
- is_error: false,
629
- });
630
- });
631
-
632
- test("executeTool array (image/text block) content passes through untouched", async () => {
633
- const tool = buildTool({
634
- name: "ReadImage",
635
- description: "image read",
636
- inputSchema: z.object({}).passthrough(),
637
- readOnly: true,
638
- concurrencySafe: true,
639
- execute: async () => [
640
- { type: "text" as const, text: "caption" },
641
- {
642
- type: "image" as const,
643
- source: { type: "base64" as const, media_type: "image/png", data: "AAAA" },
644
- },
645
- ],
646
- });
647
- const stream = streamOf([
648
- { kind: "message_start" },
649
- ...toolUseEvents("tu1", "ReadImage", {}, 0),
650
- { kind: "message_stop" },
651
- ]);
652
- const result = await executeStreaming(stream, {
653
- toolByName: new Map([["ReadImage", tool]]),
654
- });
655
- const content = result.toolResults[0]?.content;
656
- expect(Array.isArray(content)).toBe(true);
657
- expect(content).toEqual([
658
- { type: "text", text: "caption" },
659
- { type: "image", source: { type: "base64", media_type: "image/png", data: "AAAA" } },
660
- ]);
661
- });
662
-
663
- test("executeTool error result is mapped with is_error true and can abort siblings", async () => {
664
- // A destructive tool whose execute throws → executeTool returns isError.
665
- // Default shouldAbortOnError fires because the tool is destructive.
666
- const boom = buildTool({
667
- name: "Bash",
668
- description: "bash",
669
- inputSchema: z.object({}).passthrough(),
670
- destructive: true,
671
- execute: async () => {
672
- throw new Error("exec failed");
673
- },
674
- });
675
- const events: StreamingToolEvent[] = [];
676
- const stream = streamOf([
677
- { kind: "message_start" },
678
- ...toolUseEvents("tu1", "Bash", {}, 0),
679
- ...toolUseEvents("tu2", "Bash", {}, 1),
680
- { kind: "message_stop" },
681
- ]);
682
- const result = await executeStreaming(stream, {
683
- toolByName: new Map([["Bash", boom]]),
684
- onEvent: (e) => events.push(e),
685
- });
686
- const r1 = result.toolResults.find((r) => r.tool_use_id === "tu1");
687
- expect(r1?.is_error).toBe(true);
688
- expect(r1?.content).toBe("exec failed");
689
- expect(events.find((e) => e.kind === "sibling-aborted")).toBeDefined();
690
- const r2 = result.toolResults.find((r) => r.tool_use_id === "tu2");
691
- expect(r2?.content).toContain("aborted: sibling tool failed");
692
- });
693
- });
694
-
695
- // ---------- stream `error` event + wrapping catch (370-377) ---------- //
696
-
697
- describe("stream error handling", () => {
698
- test("an `error` stream event throws a wrapped RuntimeError", async () => {
699
- const stream = streamOf([
700
- { kind: "message_start" },
701
- { kind: "error", error: { type: "overloaded", message: "upstream 529" } },
702
- ]);
703
- await expect(executeStreaming(stream, { toolByName: new Map() })).rejects.toThrow(
704
- /stream failed:.*stream error:.*upstream 529/,
705
- );
706
- });
707
-
708
- test("an iterator that throws a non-Error value is wrapped via String(err)", async () => {
709
- const stream: AsyncIterable<StreamEvent> = {
710
- [Symbol.asyncIterator]() {
711
- let yielded = false;
712
- return {
713
- next(): Promise<IteratorResult<StreamEvent>> {
714
- if (!yielded) {
715
- yielded = true;
716
- return Promise.resolve({
717
- value: { kind: "message_start" } satisfies StreamEvent,
718
- done: false,
719
- });
720
- }
721
- // Reject with a non-Error so the catch uses String(err).
722
- return Promise.reject("raw-stream-explosion");
723
- },
724
- };
725
- },
726
- };
727
- await expect(executeStreaming(stream, { toolByName: new Map() })).rejects.toThrow(
728
- /stream failed: raw-stream-explosion/,
729
- );
730
- });
731
- });
732
-
733
- // ---------- multi-pass drain (382-388) ---------- //
734
-
735
- describe("in-flight drain", () => {
736
- test("a tool that resolves after message_stop is still awaited and ordered", async () => {
737
- // The stream finishes (message_stop) while tu1 is still pending; the
738
- // drain loop must await it before returning. tu2 is enqueued but only
739
- // dispatched after tu1 drains (kept simple/serial via an unsafe tool).
740
- const d1 = deferred<void>();
741
- let started = false;
742
- const stream = streamOf([
743
- { kind: "message_start" },
744
- ...toolUseEvents("tu1", "Read", { a: 1 }, 0),
745
- { kind: "message_stop" },
746
- ]);
747
- const promise = executeStreaming(stream, {
748
- toolByName: new Map([["Read", safeReadTool()]]),
749
- onEvent: (e) => {
750
- if (e.kind === "tool-started") started = true;
751
- },
752
- runTool: async (block) => {
753
- await d1.promise;
754
- return {
755
- type: "tool_result",
756
- tool_use_id: block.id,
757
- content: "late",
758
- is_error: false,
759
- };
760
- },
761
- });
762
- // Stream is exhausted; tu1 is still in flight when the first drain loop
763
- // runs. Resolve it only once it has actually started.
764
- await flushUntil(() => started);
765
- d1.resolve();
766
- const result = await promise;
767
- expect(result.toolResults[0]?.content).toBe("late");
768
- });
769
-
770
- test("a tool dispatched only by the post-stream processQueue still settles", async () => {
771
- // Two unsafe tools: tu1 holds the in-flight slot through message_stop;
772
- // tu2 stays queued (unsafe blocks it) until tu1's finally re-runs
773
- // processQueue, dispatching tu2 in the SECOND drain pass.
774
- const unsafe = buildTool({
775
- name: "Bash",
776
- description: "unsafe",
777
- inputSchema: z.object({}).passthrough(),
778
- destructive: true,
779
- execute: async () => "x",
780
- });
781
- const d1 = deferred<void>();
782
- const d2 = deferred<void>();
783
- const order: string[] = [];
784
- const stream = streamOf([
785
- { kind: "message_start" },
786
- ...toolUseEvents("tu1", "Bash", { a: 1 }, 0),
787
- ...toolUseEvents("tu2", "Bash", { a: 2 }, 1),
788
- { kind: "message_stop" },
789
- ]);
790
- const promise = executeStreaming(stream, {
791
- toolByName: new Map([["Bash", unsafe]]),
792
- shouldAbortOnError: () => false,
793
- onEvent: (e) => {
794
- if (e.kind === "tool-started") order.push(e.toolUseId);
795
- },
796
- runTool: async (block) => {
797
- if (block.id === "tu1") await d1.promise;
798
- else await d2.promise;
799
- return {
800
- type: "tool_result",
801
- tool_use_id: block.id,
802
- content: block.id,
803
- is_error: false,
804
- };
805
- },
806
- });
807
- await flushUntil(() => order.includes("tu1"));
808
- expect(order).toEqual(["tu1"]);
809
- d1.resolve();
810
- // After tu1 drains, processQueue dispatches tu2 in the second pass.
811
- await flushUntil(() => order.includes("tu2"));
812
- expect(order).toEqual(["tu1", "tu2"]);
813
- d2.resolve();
814
- const result = await promise;
815
- expect(result.toolResults.map((r) => r.tool_use_id)).toEqual(["tu1", "tu2"]);
816
- });
817
- });
818
-
819
- // ---------- content_block edge cases (307, 322, 399) ---------- //
820
-
821
- describe("unknown / mismatched content blocks", () => {
822
- test("deltas and stops for an unopened block index are ignored", async () => {
823
- const stream = streamOf([
824
- { kind: "message_start" },
825
- // Delta + stop for index 5 that was never opened.
826
- {
827
- kind: "content_block_delta",
828
- index: 5,
829
- delta: { type: "text_delta", text: "ghost" },
830
- },
831
- { kind: "content_block_stop", index: 5 },
832
- // A real text block at index 0.
833
- { kind: "content_block_start", index: 0, block: { type: "text", text: "real" } },
834
- { kind: "content_block_stop", index: 0 },
835
- { kind: "message_stop" },
836
- ]);
837
- const result = await executeStreaming(stream, { toolByName: new Map() });
838
- expect(result.finalContent).toEqual([{ type: "text", text: "real" }]);
839
- });
840
-
841
- test("a delta whose type mismatches the block kind is a no-op", async () => {
842
- // text block receives an input_json_delta → none of the branches match,
843
- // the text stays as opened.
844
- const stream = streamOf([
845
- { kind: "message_start" },
846
- { kind: "content_block_start", index: 0, block: { type: "text", text: "keep" } },
847
- {
848
- kind: "content_block_delta",
849
- index: 0,
850
- delta: { type: "input_json_delta", partial_json: "{}" },
851
- },
852
- { kind: "content_block_stop", index: 0 },
853
- { kind: "message_stop" },
854
- ]);
855
- const result = await executeStreaming(stream, { toolByName: new Map() });
856
- expect(result.finalContent).toEqual([{ type: "text", text: "keep" }]);
857
- });
858
-
859
- test("content_block_stop for a non-tool_use block does not enqueue work", async () => {
860
- let dispatched = false;
861
- const stream = streamOf([
862
- { kind: "message_start" },
863
- { kind: "content_block_start", index: 0, block: { type: "text", text: "t" } },
864
- { kind: "content_block_stop", index: 0 },
865
- { kind: "message_stop" },
866
- ]);
867
- const result = await executeStreaming(stream, {
868
- toolByName: new Map(),
869
- runTool: async (block) => {
870
- dispatched = true;
871
- return {
872
- type: "tool_result",
873
- tool_use_id: block.id,
874
- content: "x",
875
- is_error: false,
876
- };
877
- },
878
- });
879
- expect(dispatched).toBe(false);
880
- expect(result.toolResults).toHaveLength(0);
881
- });
882
-
883
- test("duplicate open indices are de-duplicated in finalContent (seen guard)", async () => {
884
- // Same index opened twice; openOrder records it twice but `seen` keeps
885
- // finalContent to a single entry.
886
- const stream = streamOf([
887
- { kind: "message_start" },
888
- { kind: "content_block_start", index: 0, block: { type: "text", text: "first" } },
889
- { kind: "content_block_stop", index: 0 },
890
- // Re-open the same index with a fresh block.
891
- { kind: "content_block_start", index: 0, block: { type: "text", text: "second" } },
892
- { kind: "content_block_stop", index: 0 },
893
- { kind: "message_stop" },
894
- ]);
895
- const result = await executeStreaming(stream, { toolByName: new Map() });
896
- expect(result.finalContent).toEqual([{ type: "text", text: "second" }]);
897
- });
898
- });