@crewhaus/streaming-tool-executor 0.1.3 → 0.1.5

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.
@@ -0,0 +1,92 @@
1
+ import type Anthropic from "@anthropic-ai/sdk";
2
+ /**
3
+ * Catalog R3 `streaming-tool-executor` — dispatch tool execution mid-
4
+ * stream so the first tool can start running before `message_stop`.
5
+ * Latency-sensitive turns (e.g. "read 5 files in parallel") finish
6
+ * noticeably faster than the post-stream serial path.
7
+ *
8
+ * Section 17 refactor: this module previously consumed Anthropic's
9
+ * SDK event-emitter (`AnthropicLikeStream` with `on("contentBlock")`).
10
+ * It now consumes `AsyncIterable<StreamEvent>` directly so any
11
+ * `ProviderAdapter` (Anthropic, OpenAI, Gemini, Bedrock) drives it.
12
+ *
13
+ * The dispatch logic is unchanged:
14
+ *
15
+ * - No tools currently running → run.
16
+ * - Currently-running set is all concurrency-safe AND this entry is
17
+ * concurrency-safe → run.
18
+ * - Otherwise → wait for the running set to drain.
19
+ *
20
+ * Concurrency-safety follows the same triple-conjunction as
21
+ * `tool-orchestrator`: `concurrencySafe && readOnly && !destructive`.
22
+ *
23
+ * Sibling abort: a per-call `AbortController` (`siblingAbortController`)
24
+ * is signalled when a tool result errors AND `shouldAbortOnError` says
25
+ * the failure is fatal. Pending queued tools are then short-circuited
26
+ * with a synthetic error result. In-flight tools that don't honour the
27
+ * signal complete normally — the abort affects what gets dispatched
28
+ * next, not what is already mid-flight.
29
+ */
30
+ import type { CanonicalContentBlock, StreamEvent, TokenUsage } from "@crewhaus/adapter-anthropic";
31
+ import type { RegisteredTool } from "@crewhaus/tool-catalog";
32
+ export type StreamingToolEvent = {
33
+ kind: "tool-started";
34
+ toolUseId: string;
35
+ toolName: string;
36
+ startedAt: number;
37
+ } | {
38
+ kind: "tool-finished";
39
+ toolUseId: string;
40
+ toolName: string;
41
+ durationMs: number;
42
+ isError: boolean;
43
+ } | {
44
+ kind: "sibling-aborted";
45
+ reason: string;
46
+ failedToolName: string;
47
+ };
48
+ /** A reconstructed `tool_use` block — what `runTool` callbacks receive. */
49
+ export type CompletedToolUseBlock = {
50
+ readonly id: string;
51
+ readonly name: string;
52
+ readonly input: unknown;
53
+ };
54
+ export type StreamingExecuteOptions = {
55
+ readonly toolByName: Map<string, RegisteredTool>;
56
+ readonly onEvent?: (e: StreamingToolEvent) => void;
57
+ readonly onTextDelta?: (chunk: string, blockIndex: number) => void;
58
+ readonly abortSignal?: AbortSignal;
59
+ /**
60
+ * Decide whether a sibling tool failure should abort still-running
61
+ * tools. Default: abort when the failing tool was destructive
62
+ * (mirrors claude-code's Bash-only abort, but generalised).
63
+ */
64
+ readonly shouldAbortOnError?: (failedToolName: string, tool: RegisteredTool | undefined) => boolean;
65
+ /**
66
+ * Per-tool execution function used in place of the bare `executeTool`
67
+ * call. The runtime supplies one that adds permission gating, per-tool
68
+ * abort signals, and result-store wrapping so the streaming path
69
+ * shares the same contract as the post-stream batch path.
70
+ *
71
+ * Must return a fully-formed `ToolResultBlockParam`; the streaming
72
+ * executor uses it as-is. When omitted, falls back to a minimal
73
+ * `executeTool`-only invocation (no permission gate, no result
74
+ * persistence).
75
+ */
76
+ readonly runTool?: (block: CompletedToolUseBlock) => Promise<Anthropic.ToolResultBlockParam>;
77
+ };
78
+ export type StreamingExecuteResult = {
79
+ readonly finalContent: ReadonlyArray<CanonicalContentBlock>;
80
+ readonly toolResults: ReadonlyArray<Anthropic.ToolResultBlockParam>;
81
+ readonly stopReason: string;
82
+ readonly usage: TokenUsage;
83
+ };
84
+ /**
85
+ * Drive an `AsyncIterable<StreamEvent>` and dispatch `tool_use` blocks
86
+ * as they complete. Resolves once the stream finalises AND every
87
+ * dispatched (or aborted) tool settles. The returned `toolResults`
88
+ * are sorted to match the order of `tool_use` blocks in
89
+ * `finalContent` so downstream code can pair results back to their
90
+ * original blocks by index.
91
+ */
92
+ export declare function executeStreaming(stream: AsyncIterable<StreamEvent>, opts: StreamingExecuteOptions): Promise<StreamingExecuteResult>;
package/dist/index.js ADDED
@@ -0,0 +1,322 @@
1
+ import { RuntimeError } from "@crewhaus/errors";
2
+ import { executeTool } from "@crewhaus/tool-executor";
3
+ function defaultShouldAbortOnError(_failedToolName, tool) {
4
+ return tool?.destructive === true;
5
+ }
6
+ function isConcurrencySafe(tool) {
7
+ return tool?.concurrencySafe === true && tool.readOnly && !tool.destructive;
8
+ }
9
+ /**
10
+ * Drive an `AsyncIterable<StreamEvent>` and dispatch `tool_use` blocks
11
+ * as they complete. Resolves once the stream finalises AND every
12
+ * dispatched (or aborted) tool settles. The returned `toolResults`
13
+ * are sorted to match the order of `tool_use` blocks in
14
+ * `finalContent` so downstream code can pair results back to their
15
+ * original blocks by index.
16
+ */
17
+ export async function executeStreaming(stream, opts) {
18
+ const queue = [];
19
+ const results = new Map();
20
+ const inFlight = new Set();
21
+ const siblingAbort = new AbortController();
22
+ const shouldAbortOnError = opts.shouldAbortOnError ?? defaultShouldAbortOnError;
23
+ const blocks = new Map();
24
+ // Order content blocks were OPENED in — tool_use ordering must
25
+ // follow open-order for downstream pairing to work.
26
+ const openOrder = [];
27
+ let stopReason = "end_turn";
28
+ let usage = { input: 0, output: 0 };
29
+ if (opts.abortSignal) {
30
+ if (opts.abortSignal.aborted) {
31
+ siblingAbort.abort("external_abort");
32
+ }
33
+ else {
34
+ opts.abortSignal.addEventListener("abort", () => {
35
+ siblingAbort.abort("external_abort");
36
+ }, { once: true });
37
+ }
38
+ }
39
+ const fire = (e) => {
40
+ if (opts.onEvent)
41
+ opts.onEvent(e);
42
+ };
43
+ // Mark a queued entry as aborted with the synthetic sibling-failure
44
+ // result. Used by `processQueue` when the abort signal trips while
45
+ // entries are still waiting in the queue.
46
+ const markAborted = (entry) => {
47
+ entry.status = "aborted";
48
+ results.set(entry.block.id, {
49
+ type: "tool_result",
50
+ tool_use_id: entry.block.id,
51
+ content: "aborted: sibling tool failed",
52
+ is_error: true,
53
+ });
54
+ };
55
+ // `dispatch` is only ever reached via `processQueue`, which already
56
+ // diverts an aborted entry through `markAborted` before calling here,
57
+ // so no abort re-check is needed at this point.
58
+ const dispatch = (entry) => {
59
+ if (entry.status !== "queued")
60
+ return;
61
+ const tool = entry.tool;
62
+ if (tool === undefined && opts.runTool === undefined) {
63
+ entry.status = "done";
64
+ results.set(entry.block.id, {
65
+ type: "tool_result",
66
+ tool_use_id: entry.block.id,
67
+ content: `unknown tool "${entry.block.name}"`,
68
+ is_error: true,
69
+ });
70
+ return;
71
+ }
72
+ entry.status = "running";
73
+ const startedAt = Date.now();
74
+ fire({
75
+ kind: "tool-started",
76
+ toolUseId: entry.block.id,
77
+ toolName: entry.block.name,
78
+ startedAt,
79
+ });
80
+ // By the guard above, when `runTool` is absent the entry's `tool`
81
+ // is guaranteed defined, so the `executeTool` branch never sees an
82
+ // undefined tool. (A bare `tool === undefined && runTool === undefined`
83
+ // entry has already short-circuited with an "unknown tool" result.)
84
+ const runOne = (resolvedTool) => executeTool(resolvedTool, entry.block.input, { toolUseId: entry.block.id }).then((res) => ({
85
+ type: "tool_result",
86
+ tool_use_id: entry.block.id,
87
+ content: typeof res.content === "string"
88
+ ? res.content
89
+ : res.content,
90
+ is_error: res.isError,
91
+ }));
92
+ const dispatchPromise = opts.runTool
93
+ ? opts.runTool(entry.block)
94
+ : runOne(tool);
95
+ const promise = dispatchPromise
96
+ .then((res) => {
97
+ entry.status = "done";
98
+ results.set(entry.block.id, res);
99
+ const isError = res.is_error ?? false;
100
+ fire({
101
+ kind: "tool-finished",
102
+ toolUseId: entry.block.id,
103
+ toolName: entry.block.name,
104
+ durationMs: Date.now() - startedAt,
105
+ isError,
106
+ });
107
+ if (isError &&
108
+ !siblingAbort.signal.aborted &&
109
+ shouldAbortOnError(entry.block.name, entry.tool)) {
110
+ siblingAbort.abort("sibling_error");
111
+ fire({
112
+ kind: "sibling-aborted",
113
+ reason: "sibling_error",
114
+ failedToolName: entry.block.name,
115
+ });
116
+ }
117
+ })
118
+ .catch((err) => {
119
+ entry.status = "done";
120
+ const msg = err instanceof Error ? err.message : String(err);
121
+ results.set(entry.block.id, {
122
+ type: "tool_result",
123
+ tool_use_id: entry.block.id,
124
+ content: msg,
125
+ is_error: true,
126
+ });
127
+ })
128
+ .finally(() => {
129
+ inFlight.delete(promise);
130
+ processQueue();
131
+ });
132
+ inFlight.add(promise);
133
+ };
134
+ const processQueue = () => {
135
+ for (const entry of queue) {
136
+ if (entry.status !== "queued")
137
+ continue;
138
+ if (siblingAbort.signal.aborted) {
139
+ markAborted(entry);
140
+ continue;
141
+ }
142
+ if (inFlight.size === 0) {
143
+ dispatch(entry);
144
+ continue;
145
+ }
146
+ // With work already in flight, only dispatch this entry when the
147
+ // running set is fully concurrency-safe AND this entry is too;
148
+ // otherwise stop scanning and wait for the running set to drain.
149
+ const runningAllSafe = queue.every((e) => e.status !== "running" || isConcurrencySafe(e.tool));
150
+ const canRunConcurrently = runningAllSafe && isConcurrencySafe(entry.tool);
151
+ if (!canRunConcurrently)
152
+ return;
153
+ dispatch(entry);
154
+ }
155
+ };
156
+ // Walk the stream, accumulating blocks; on content_block_stop for a
157
+ // tool_use, reconstruct it and enqueue.
158
+ try {
159
+ for await (const ev of stream) {
160
+ switch (ev.kind) {
161
+ case "message_start":
162
+ if (ev.usage)
163
+ usage = ev.usage;
164
+ break;
165
+ case "content_block_start":
166
+ openOrder.push(ev.index);
167
+ switch (ev.block.type) {
168
+ case "text":
169
+ blocks.set(ev.index, { kind: "text", text: ev.block.text });
170
+ break;
171
+ case "tool_use":
172
+ blocks.set(ev.index, {
173
+ kind: "tool_use",
174
+ id: ev.block.id,
175
+ name: ev.block.name,
176
+ jsonBuffer: "",
177
+ });
178
+ break;
179
+ case "thinking":
180
+ blocks.set(ev.index, {
181
+ kind: "thinking",
182
+ thinking: ev.block.thinking,
183
+ ...(ev.block.signature !== undefined ? { signature: ev.block.signature } : {}),
184
+ });
185
+ break;
186
+ }
187
+ break;
188
+ case "content_block_delta": {
189
+ const block = blocks.get(ev.index);
190
+ if (block === undefined)
191
+ break;
192
+ if (ev.delta.type === "text_delta" && block.kind === "text") {
193
+ block.text += ev.delta.text;
194
+ opts.onTextDelta?.(ev.delta.text, ev.index);
195
+ }
196
+ else if (ev.delta.type === "input_json_delta" && block.kind === "tool_use") {
197
+ block.jsonBuffer += ev.delta.partial_json;
198
+ }
199
+ else if (ev.delta.type === "thinking_delta" && block.kind === "thinking") {
200
+ block.thinking += ev.delta.thinking;
201
+ }
202
+ else if (ev.delta.type === "signature_delta" && block.kind === "thinking") {
203
+ block.signature = ev.delta.signature;
204
+ }
205
+ break;
206
+ }
207
+ case "content_block_stop": {
208
+ const block = blocks.get(ev.index);
209
+ if (block === undefined)
210
+ break;
211
+ if (block.kind === "tool_use") {
212
+ let input = {};
213
+ if (block.jsonBuffer.length > 0) {
214
+ try {
215
+ input = JSON.parse(block.jsonBuffer);
216
+ }
217
+ catch {
218
+ input = { __parse_error: true, raw: block.jsonBuffer };
219
+ }
220
+ }
221
+ const completed = {
222
+ id: block.id,
223
+ name: block.name,
224
+ input,
225
+ };
226
+ // Persist the parsed input on the block so finalContent
227
+ // reflects what we passed to runTool.
228
+ block.jsonBuffer = JSON.stringify(input);
229
+ queue.push({
230
+ block: completed,
231
+ tool: opts.toolByName.get(completed.name),
232
+ status: "queued",
233
+ });
234
+ processQueue();
235
+ }
236
+ break;
237
+ }
238
+ case "message_delta":
239
+ if (ev.stopReason !== undefined)
240
+ stopReason = ev.stopReason;
241
+ if (ev.usage !== undefined) {
242
+ usage = {
243
+ input: ev.usage.input > 0 ? ev.usage.input : usage.input,
244
+ output: ev.usage.output > 0 ? ev.usage.output : usage.output,
245
+ ...(ev.usage.cacheRead !== undefined
246
+ ? { cacheRead: ev.usage.cacheRead }
247
+ : usage.cacheRead !== undefined
248
+ ? { cacheRead: usage.cacheRead }
249
+ : {}),
250
+ ...(ev.usage.cacheCreate !== undefined
251
+ ? { cacheCreate: ev.usage.cacheCreate }
252
+ : usage.cacheCreate !== undefined
253
+ ? { cacheCreate: usage.cacheCreate }
254
+ : {}),
255
+ };
256
+ }
257
+ break;
258
+ case "message_stop":
259
+ break;
260
+ case "error":
261
+ throw new RuntimeError(`streaming-tool-executor: stream error: ${ev.error.message}`);
262
+ }
263
+ }
264
+ }
265
+ catch (err) {
266
+ throw new RuntimeError(`streaming-tool-executor: stream failed: ${err instanceof Error ? err.message : String(err)}`, err);
267
+ }
268
+ // Drain any tools still in flight or queued. Re-run the scheduler
269
+ // after each settle so an entry unblocked by the just-finished tool
270
+ // (each tool's own `finally` also calls `processQueue`, but doing it
271
+ // here keeps the drain self-contained) is dispatched and then awaited
272
+ // on the next pass. The loop exits only once nothing is in flight,
273
+ // which — because `processQueue` has just run — means the queue is
274
+ // fully drained.
275
+ while (inFlight.size > 0) {
276
+ await Promise.race(inFlight);
277
+ processQueue();
278
+ }
279
+ // Build the final content array in open-order so tool_use blocks
280
+ // surface in the same order they came down the wire (matching the
281
+ // Anthropic-shaped final message historically returned).
282
+ const finalContent = [];
283
+ const seen = new Set();
284
+ for (const idx of openOrder) {
285
+ if (seen.has(idx))
286
+ continue;
287
+ seen.add(idx);
288
+ const b = blocks.get(idx);
289
+ if (b === undefined)
290
+ continue;
291
+ if (b.kind === "text") {
292
+ finalContent.push({ type: "text", text: b.text });
293
+ }
294
+ else if (b.kind === "tool_use") {
295
+ let input = {};
296
+ try {
297
+ input = JSON.parse(b.jsonBuffer);
298
+ }
299
+ catch {
300
+ input = { __parse_error: true, raw: b.jsonBuffer };
301
+ }
302
+ finalContent.push({ type: "tool_use", id: b.id, name: b.name, input });
303
+ }
304
+ else {
305
+ finalContent.push({
306
+ type: "thinking",
307
+ thinking: b.thinking,
308
+ ...(b.signature !== undefined ? { signature: b.signature } : {}),
309
+ });
310
+ }
311
+ }
312
+ // Sort tool results to match tool_use block order in finalContent.
313
+ const ordered = [];
314
+ for (const block of finalContent) {
315
+ if (block.type !== "tool_use")
316
+ continue;
317
+ const r = results.get(block.id);
318
+ if (r !== undefined)
319
+ ordered.push(r);
320
+ }
321
+ return { finalContent, toolResults: ordered, stopReason, usage };
322
+ }
package/package.json CHANGED
@@ -1,24 +1,27 @@
1
1
  {
2
2
  "name": "@crewhaus/streaming-tool-executor",
3
- "version": "0.1.3",
3
+ "version": "0.1.5",
4
4
  "type": "module",
5
5
  "description": "Dispatch tool execution mid-stream so tools start before message_stop",
6
- "main": "src/index.ts",
7
- "types": "src/index.ts",
6
+ "main": "dist/index.js",
7
+ "types": "dist/index.d.ts",
8
8
  "exports": {
9
- ".": "./src/index.ts"
9
+ ".": {
10
+ "types": "./dist/index.d.ts",
11
+ "import": "./dist/index.js"
12
+ }
10
13
  },
11
14
  "scripts": {
12
15
  "test": "bun test src"
13
16
  },
14
17
  "dependencies": {
15
18
  "@anthropic-ai/sdk": "^0.96.0",
16
- "@crewhaus/adapter-anthropic": "0.1.3",
17
- "@crewhaus/errors": "0.1.3",
18
- "@crewhaus/tool-builder": "0.1.3",
19
- "@crewhaus/tool-catalog": "0.1.3",
20
- "@crewhaus/tool-executor": "0.1.3",
21
- "@crewhaus/turn-state-machine": "0.1.3",
19
+ "@crewhaus/adapter-anthropic": "0.1.5",
20
+ "@crewhaus/errors": "0.1.5",
21
+ "@crewhaus/tool-builder": "0.1.5",
22
+ "@crewhaus/tool-catalog": "0.1.5",
23
+ "@crewhaus/tool-executor": "0.1.5",
24
+ "@crewhaus/turn-state-machine": "0.1.5",
22
25
  "zod": "^3.23.8"
23
26
  },
24
27
  "license": "Apache-2.0",
@@ -39,5 +42,5 @@
39
42
  "publishConfig": {
40
43
  "access": "public"
41
44
  },
42
- "files": ["src", "README.md", "LICENSE", "NOTICE"]
45
+ "files": ["dist", "README.md", "LICENSE", "NOTICE"]
43
46
  }