@crewhaus/streaming-tool-executor 0.1.0 → 0.1.2

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crewhaus/streaming-tool-executor",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "type": "module",
5
5
  "description": "Dispatch tool execution mid-stream so tools start before message_stop",
6
6
  "main": "src/index.ts",
@@ -13,19 +13,19 @@
13
13
  },
14
14
  "dependencies": {
15
15
  "@anthropic-ai/sdk": "^0.96.0",
16
- "@crewhaus/adapter-anthropic": "0.0.0",
17
- "@crewhaus/errors": "0.0.0",
18
- "@crewhaus/tool-builder": "0.0.0",
19
- "@crewhaus/tool-catalog": "0.0.0",
20
- "@crewhaus/tool-executor": "0.0.0",
21
- "@crewhaus/turn-state-machine": "0.0.0",
16
+ "@crewhaus/adapter-anthropic": "0.1.2",
17
+ "@crewhaus/errors": "0.1.2",
18
+ "@crewhaus/tool-builder": "0.1.2",
19
+ "@crewhaus/tool-catalog": "0.1.2",
20
+ "@crewhaus/tool-executor": "0.1.2",
21
+ "@crewhaus/turn-state-machine": "0.1.2",
22
22
  "zod": "^3.23.8"
23
23
  },
24
24
  "license": "Apache-2.0",
25
25
  "author": {
26
26
  "name": "Max Meier",
27
- "email": "max@studiomax.io",
28
- "url": "https://studiomax.io"
27
+ "email": "max@crewhaus.ai",
28
+ "url": "https://crewhaus.ai"
29
29
  },
30
30
  "repository": {
31
31
  "type": "git",
@@ -37,12 +37,7 @@
37
37
  "url": "https://github.com/crewhaus/factory/issues"
38
38
  },
39
39
  "publishConfig": {
40
- "access": "restricted"
40
+ "access": "public"
41
41
  },
42
- "files": [
43
- "src",
44
- "README.md",
45
- "LICENSE",
46
- "NOTICE"
47
- ]
42
+ "files": ["src", "README.md", "LICENSE", "NOTICE"]
48
43
  }
@@ -0,0 +1,898 @@
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
+ });
package/src/index.ts CHANGED
@@ -149,19 +149,26 @@ export async function executeStreaming(
149
149
  if (opts.onEvent) opts.onEvent(e);
150
150
  };
151
151
 
152
+ // Mark a queued entry as aborted with the synthetic sibling-failure
153
+ // result. Used by `processQueue` when the abort signal trips while
154
+ // entries are still waiting in the queue.
155
+ const markAborted = (entry: QueueEntry): void => {
156
+ entry.status = "aborted";
157
+ results.set(entry.block.id, {
158
+ type: "tool_result",
159
+ tool_use_id: entry.block.id,
160
+ content: "aborted: sibling tool failed",
161
+ is_error: true,
162
+ });
163
+ };
164
+
165
+ // `dispatch` is only ever reached via `processQueue`, which already
166
+ // diverts an aborted entry through `markAborted` before calling here,
167
+ // so no abort re-check is needed at this point.
152
168
  const dispatch = (entry: QueueEntry): void => {
153
169
  if (entry.status !== "queued") return;
154
- if (siblingAbort.signal.aborted) {
155
- entry.status = "aborted";
156
- results.set(entry.block.id, {
157
- type: "tool_result",
158
- tool_use_id: entry.block.id,
159
- content: "aborted: sibling tool failed",
160
- is_error: true,
161
- });
162
- return;
163
- }
164
- if (entry.tool === undefined && opts.runTool === undefined) {
170
+ const tool = entry.tool;
171
+ if (tool === undefined && opts.runTool === undefined) {
165
172
  entry.status = "done";
166
173
  results.set(entry.block.id, {
167
174
  type: "tool_result",
@@ -179,28 +186,27 @@ export async function executeStreaming(
179
186
  toolName: entry.block.name,
180
187
  startedAt,
181
188
  });
189
+ // By the guard above, when `runTool` is absent the entry's `tool`
190
+ // is guaranteed defined, so the `executeTool` branch never sees an
191
+ // undefined tool. (A bare `tool === undefined && runTool === undefined`
192
+ // entry has already short-circuited with an "unknown tool" result.)
193
+ const runOne = (resolvedTool: RegisteredTool): Promise<Anthropic.ToolResultBlockParam> =>
194
+ executeTool(resolvedTool, entry.block.input, { toolUseId: entry.block.id }).then(
195
+ (res): Anthropic.ToolResultBlockParam => ({
196
+ type: "tool_result",
197
+ tool_use_id: entry.block.id,
198
+ content:
199
+ typeof res.content === "string"
200
+ ? res.content
201
+ : (res.content as ReadonlyArray<
202
+ Anthropic.TextBlockParam | Anthropic.ImageBlockParam
203
+ > as Anthropic.ToolResultBlockParam["content"]),
204
+ is_error: res.isError,
205
+ }),
206
+ );
182
207
  const dispatchPromise: Promise<Anthropic.ToolResultBlockParam> = opts.runTool
183
208
  ? opts.runTool(entry.block)
184
- : entry.tool === undefined
185
- ? Promise.resolve<Anthropic.ToolResultBlockParam>({
186
- type: "tool_result",
187
- tool_use_id: entry.block.id,
188
- content: `unknown tool "${entry.block.name}"`,
189
- is_error: true,
190
- })
191
- : executeTool(entry.tool, entry.block.input, { toolUseId: entry.block.id }).then(
192
- (res): Anthropic.ToolResultBlockParam => ({
193
- type: "tool_result",
194
- tool_use_id: entry.block.id,
195
- content:
196
- typeof res.content === "string"
197
- ? res.content
198
- : (res.content as ReadonlyArray<
199
- Anthropic.TextBlockParam | Anthropic.ImageBlockParam
200
- > as Anthropic.ToolResultBlockParam["content"]),
201
- is_error: res.isError,
202
- }),
203
- );
209
+ : runOne(tool as RegisteredTool);
204
210
  const promise = dispatchPromise
205
211
  .then((res) => {
206
212
  entry.status = "done";
@@ -247,27 +253,22 @@ export async function executeStreaming(
247
253
  for (const entry of queue) {
248
254
  if (entry.status !== "queued") continue;
249
255
  if (siblingAbort.signal.aborted) {
250
- entry.status = "aborted";
251
- results.set(entry.block.id, {
252
- type: "tool_result",
253
- tool_use_id: entry.block.id,
254
- content: "aborted: sibling tool failed",
255
- is_error: true,
256
- });
256
+ markAborted(entry);
257
257
  continue;
258
258
  }
259
259
  if (inFlight.size === 0) {
260
260
  dispatch(entry);
261
261
  continue;
262
262
  }
263
+ // With work already in flight, only dispatch this entry when the
264
+ // running set is fully concurrency-safe AND this entry is too;
265
+ // otherwise stop scanning and wait for the running set to drain.
263
266
  const runningAllSafe = queue.every(
264
267
  (e) => e.status !== "running" || isConcurrencySafe(e.tool),
265
268
  );
266
- if (runningAllSafe && isConcurrencySafe(entry.tool)) {
267
- dispatch(entry);
268
- } else {
269
- return;
270
- }
269
+ const canRunConcurrently = runningAllSafe && isConcurrencySafe(entry.tool);
270
+ if (!canRunConcurrently) return;
271
+ dispatch(entry);
271
272
  }
272
273
  };
273
274
 
@@ -378,13 +379,16 @@ export async function executeStreaming(
378
379
  );
379
380
  }
380
381
 
381
- // Drain any tools still in flight or queued.
382
- while (inFlight.size > 0) {
383
- await Promise.race(inFlight);
384
- }
385
- processQueue();
382
+ // Drain any tools still in flight or queued. Re-run the scheduler
383
+ // after each settle so an entry unblocked by the just-finished tool
384
+ // (each tool's own `finally` also calls `processQueue`, but doing it
385
+ // here keeps the drain self-contained) is dispatched and then awaited
386
+ // on the next pass. The loop exits only once nothing is in flight,
387
+ // which — because `processQueue` has just run — means the queue is
388
+ // fully drained.
386
389
  while (inFlight.size > 0) {
387
390
  await Promise.race(inFlight);
391
+ processQueue();
388
392
  }
389
393
 
390
394
  // Build the final content array in open-order so tool_use blocks