@crewhaus/tool-orchestrator 0.1.0

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 ADDED
@@ -0,0 +1,43 @@
1
+ {
2
+ "name": "@crewhaus/tool-orchestrator",
3
+ "version": "0.1.0",
4
+ "type": "module",
5
+ "description": "Partition tool_use blocks into concurrent batches and serial calls based on catalog metadata",
6
+ "main": "src/index.ts",
7
+ "types": "src/index.ts",
8
+ "exports": {
9
+ ".": "./src/index.ts"
10
+ },
11
+ "scripts": {
12
+ "test": "bun test src"
13
+ },
14
+ "dependencies": {
15
+ "@crewhaus/errors": "0.0.0",
16
+ "@crewhaus/tool-catalog": "0.0.0",
17
+ "@crewhaus/turn-state-machine": "0.0.0"
18
+ },
19
+ "license": "Apache-2.0",
20
+ "author": {
21
+ "name": "Max Meier",
22
+ "email": "max@studiomax.io",
23
+ "url": "https://studiomax.io"
24
+ },
25
+ "repository": {
26
+ "type": "git",
27
+ "url": "git+https://github.com/crewhaus/factory.git",
28
+ "directory": "packages/tool-orchestrator"
29
+ },
30
+ "homepage": "https://github.com/crewhaus/factory/tree/main/packages/tool-orchestrator#readme",
31
+ "bugs": {
32
+ "url": "https://github.com/crewhaus/factory/issues"
33
+ },
34
+ "publishConfig": {
35
+ "access": "restricted"
36
+ },
37
+ "files": [
38
+ "src",
39
+ "README.md",
40
+ "LICENSE",
41
+ "NOTICE"
42
+ ]
43
+ }
@@ -0,0 +1,182 @@
1
+ import { describe, expect, test } from "bun:test";
2
+ import type { RegisteredTool } from "@crewhaus/tool-catalog";
3
+ import type { ToolUseBlock } from "@crewhaus/turn-state-machine";
4
+ import { isConcurrencySafe, partitionToolCalls } from "./index";
5
+
6
+ // Minimal RegisteredTool factory for tests. The orchestrator never invokes
7
+ // `inputSchema` or `execute`, so we don't pull zod in just to satisfy types.
8
+ function makeTool(overrides: Partial<RegisteredTool> & { name: string }): RegisteredTool {
9
+ return {
10
+ description: "test",
11
+ inputSchema: undefined as unknown as RegisteredTool["inputSchema"],
12
+ execute: async () => "ok",
13
+ concurrencySafe: false,
14
+ readOnly: false,
15
+ destructive: false,
16
+ requiresSandbox: false,
17
+ classifyOutput: true,
18
+ scope: "internal",
19
+ requireJustification: false,
20
+ ...overrides,
21
+ };
22
+ }
23
+
24
+ function call(
25
+ name: string,
26
+ id = `tu_${name}_${Math.random().toString(36).slice(2, 6)}`,
27
+ ): ToolUseBlock {
28
+ return { id, name, input: {} };
29
+ }
30
+
31
+ const READ = makeTool({ name: "Read", concurrencySafe: true, readOnly: true });
32
+ const GLOB = makeTool({ name: "Glob", concurrencySafe: true, readOnly: true });
33
+ const BASH = makeTool({ name: "Bash", destructive: true });
34
+ const WRITE = makeTool({ name: "Write", destructive: true });
35
+ const READ_BUT_DESTRUCTIVE = makeTool({
36
+ name: "Sketchy",
37
+ concurrencySafe: true,
38
+ readOnly: true,
39
+ destructive: true, // destructive overrides the others
40
+ });
41
+
42
+ const lookup = (name: string): RegisteredTool | undefined =>
43
+ ({ Read: READ, Glob: GLOB, Bash: BASH, Write: WRITE, Sketchy: READ_BUT_DESTRUCTIVE })[name];
44
+
45
+ describe("isConcurrencySafe", () => {
46
+ test("requires all three flags aligned", () => {
47
+ expect(isConcurrencySafe(READ)).toBe(true);
48
+ expect(isConcurrencySafe(BASH)).toBe(false);
49
+ expect(isConcurrencySafe(READ_BUT_DESTRUCTIVE)).toBe(false);
50
+ expect(isConcurrencySafe(makeTool({ name: "X", concurrencySafe: true }))).toBe(false);
51
+ expect(isConcurrencySafe(makeTool({ name: "X", readOnly: true }))).toBe(false);
52
+ });
53
+ });
54
+
55
+ describe("partitionToolCalls — basic shapes", () => {
56
+ test("empty input returns empty partition", () => {
57
+ const out = partitionToolCalls([], lookup);
58
+ expect(out.concurrent).toEqual([]);
59
+ expect(out.serial).toEqual([]);
60
+ });
61
+
62
+ test("all read-only → one concurrent batch", () => {
63
+ const calls = [call("Read", "1"), call("Read", "2"), call("Glob", "3")];
64
+ const out = partitionToolCalls(calls, lookup);
65
+ expect(out.concurrent.length).toBe(1);
66
+ expect(out.concurrent[0]?.map((c) => c.id)).toEqual(["1", "2", "3"]);
67
+ expect(out.serial).toEqual([]);
68
+ });
69
+
70
+ test("all destructive → all serial, zero concurrent batches", () => {
71
+ const calls = [call("Bash", "1"), call("Write", "2"), call("Bash", "3")];
72
+ const out = partitionToolCalls(calls, lookup);
73
+ expect(out.concurrent).toEqual([]);
74
+ expect(out.serial.map((c) => c.id)).toEqual(["1", "2", "3"]);
75
+ });
76
+
77
+ test("interleaved read/write splits batches", () => {
78
+ const calls = [
79
+ call("Read", "1"),
80
+ call("Read", "2"),
81
+ call("Bash", "3"),
82
+ call("Glob", "4"),
83
+ call("Write", "5"),
84
+ call("Read", "6"),
85
+ ];
86
+ const out = partitionToolCalls(calls, lookup);
87
+ // Three concurrent batches separated by serial calls: [1,2], [4], [6]
88
+ expect(out.concurrent.length).toBe(3);
89
+ expect(out.concurrent[0]?.map((c) => c.id)).toEqual(["1", "2"]);
90
+ expect(out.concurrent[1]?.map((c) => c.id)).toEqual(["4"]);
91
+ expect(out.concurrent[2]?.map((c) => c.id)).toEqual(["6"]);
92
+ expect(out.serial.map((c) => c.id)).toEqual(["3", "5"]);
93
+ });
94
+
95
+ test("destructive flag overrides concurrencySafe + readOnly", () => {
96
+ const calls = [call("Sketchy", "1"), call("Read", "2")];
97
+ const out = partitionToolCalls(calls, lookup);
98
+ expect(out.concurrent.length).toBe(1);
99
+ expect(out.concurrent[0]?.map((c) => c.id)).toEqual(["2"]);
100
+ expect(out.serial.map((c) => c.id)).toEqual(["1"]);
101
+ });
102
+
103
+ test("unknown tool name routes serial (fail-closed)", () => {
104
+ const calls = [call("Read", "1"), call("Mystery", "2"), call("Read", "3")];
105
+ const out = partitionToolCalls(calls, lookup);
106
+ expect(out.concurrent.length).toBe(2);
107
+ expect(out.concurrent[0]?.map((c) => c.id)).toEqual(["1"]);
108
+ expect(out.concurrent[1]?.map((c) => c.id)).toEqual(["3"]);
109
+ expect(out.serial.map((c) => c.id)).toEqual(["2"]);
110
+ });
111
+ });
112
+
113
+ describe("partitionToolCalls — accepts ToolCatalog", () => {
114
+ test("works with a Map-shaped lookup function", () => {
115
+ const map = new Map<string, RegisteredTool>([["Read", READ]]);
116
+ const calls = [call("Read", "1")];
117
+ const out = partitionToolCalls(calls, (name) => map.get(name));
118
+ expect(out.concurrent.length).toBe(1);
119
+ expect(out.concurrent[0]?.[0]?.id).toBe("1");
120
+ });
121
+ });
122
+
123
+ // T9 property test: invariant — no concurrent batch contains a call whose
124
+ // tool is destructive, !readOnly, or !concurrencySafe.
125
+ describe("partitionToolCalls — T9 property invariant", () => {
126
+ function randomBool(rand: () => number): boolean {
127
+ return rand() < 0.5;
128
+ }
129
+ function makeRandomTool(name: string, rand: () => number): RegisteredTool {
130
+ return makeTool({
131
+ name,
132
+ concurrencySafe: randomBool(rand),
133
+ readOnly: randomBool(rand),
134
+ destructive: randomBool(rand),
135
+ });
136
+ }
137
+ function mulberry32(seed: number): () => number {
138
+ let s = seed | 0;
139
+ return () => {
140
+ s = (s + 0x6d2b79f5) | 0;
141
+ let t = s;
142
+ t = Math.imul(t ^ (t >>> 15), t | 1);
143
+ t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
144
+ return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
145
+ };
146
+ }
147
+
148
+ test("100 random partitions never paralyze a destructive or non-safe tool", () => {
149
+ for (let seed = 0; seed < 100; seed++) {
150
+ const rand = mulberry32(seed);
151
+ const numTools = 1 + Math.floor(rand() * 8);
152
+ const toolMap = new Map<string, RegisteredTool>();
153
+ for (let i = 0; i < numTools; i++) {
154
+ const name = `T${i}`;
155
+ toolMap.set(name, makeRandomTool(name, rand));
156
+ }
157
+ const numCalls = Math.floor(rand() * 30);
158
+ const calls: ToolUseBlock[] = [];
159
+ for (let i = 0; i < numCalls; i++) {
160
+ const idx = Math.floor(rand() * numTools);
161
+ const name = `T${idx}`;
162
+ calls.push({ id: `c${i}`, name, input: {} });
163
+ }
164
+
165
+ const out = partitionToolCalls(calls, (n) => toolMap.get(n));
166
+
167
+ for (const batch of out.concurrent) {
168
+ for (const c of batch) {
169
+ const tool = toolMap.get(c.name);
170
+ expect(tool).toBeDefined();
171
+ if (!tool) continue;
172
+ expect(tool.destructive).toBe(false);
173
+ expect(tool.readOnly).toBe(true);
174
+ expect(tool.concurrencySafe).toBe(true);
175
+ }
176
+ }
177
+ // Every input call appears exactly once in either bucket.
178
+ const total = out.concurrent.flat().length + out.serial.length;
179
+ expect(total).toBe(calls.length);
180
+ }
181
+ });
182
+ });
package/src/index.ts ADDED
@@ -0,0 +1,90 @@
1
+ /**
2
+ * Catalog R3 `tool-orchestrator` — partition a flat list of `tool_use`
3
+ * blocks into concurrent batches and serial calls based on catalog
4
+ * metadata. The runtime runs the concurrent batches via `Promise.all`
5
+ * and the serial calls one-at-a-time, recovering most of the wall-clock
6
+ * latency of read-heavy turns without ever paralleling side effects.
7
+ *
8
+ * A call is **concurrent-safe** iff its registered tool has all three
9
+ * flags set the right way:
10
+ * `concurrencySafe && readOnly && !destructive`
11
+ * — i.e. the tool author explicitly opted into parallelism AND the
12
+ * call is read-only AND not destructive. Any single negation falls
13
+ * through to serial. Unknown tool names also go serial (fail-closed).
14
+ *
15
+ * The returned shape `{ concurrent: ToolUseBlock[][], serial: ToolUseBlock[] }`
16
+ * deliberately drops interleaving information between batch and serial
17
+ * groups. The runtime executes all concurrent batches first via
18
+ * `Promise.all`, then serial sequentially. This is sound for the typical
19
+ * "read N files, then mutate one" pattern. If a turn truly needs an
20
+ * `[Read, Write, Read]` order with the second Read seeing post-Write
21
+ * state, the model should split it across turns.
22
+ *
23
+ * Reference: `claude-code/services/tools/toolOrchestration.ts`
24
+ * `partitionToolCalls` (returns a `Batch[]` of consecutive groups). We
25
+ * mirror its concurrency-safety predicate but flatten to the
26
+ * spec-prescribed two-bucket return.
27
+ */
28
+ import type { RegisteredTool, ToolCatalog } from "@crewhaus/tool-catalog";
29
+ import type { ToolUseBlock } from "@crewhaus/turn-state-machine";
30
+
31
+ export type ToolPartition = {
32
+ readonly concurrent: ReadonlyArray<ReadonlyArray<ToolUseBlock>>;
33
+ readonly serial: ReadonlyArray<ToolUseBlock>;
34
+ };
35
+
36
+ /**
37
+ * Function or `ToolCatalog` that resolves a tool name to its registered
38
+ * metadata. Returning `undefined` is treated as "unknown tool" and the
39
+ * call is routed serial so the executor can produce a clear error result.
40
+ */
41
+ export type ToolLookup = ToolCatalog | ((name: string) => RegisteredTool | undefined);
42
+
43
+ /**
44
+ * Decide whether a registered tool's call is safe to run in parallel
45
+ * with sibling calls. Concurrency-safety is a triple-conjunction so a
46
+ * tool author has to opt into BOTH the concurrency contract and the
47
+ * read-only contract — destructive flag is the killswitch.
48
+ */
49
+ export function isConcurrencySafe(tool: RegisteredTool): boolean {
50
+ return tool.concurrencySafe && tool.readOnly && !tool.destructive;
51
+ }
52
+
53
+ function asLookup(lookup: ToolLookup): (name: string) => RegisteredTool | undefined {
54
+ if (typeof lookup === "function") return lookup;
55
+ return (name) => lookup.get(name);
56
+ }
57
+
58
+ /**
59
+ * Walk `calls` in order, grouping consecutive concurrency-safe calls
60
+ * into the same batch. A non-safe call breaks the run and is appended
61
+ * to `serial`. The order of returned concurrent batches mirrors the
62
+ * order in which they appeared in `calls`.
63
+ */
64
+ export function partitionToolCalls(
65
+ calls: ReadonlyArray<ToolUseBlock>,
66
+ lookup: ToolLookup,
67
+ ): ToolPartition {
68
+ const get = asLookup(lookup);
69
+ const concurrent: ToolUseBlock[][] = [];
70
+ const serial: ToolUseBlock[] = [];
71
+
72
+ let currentBatch: ToolUseBlock[] | null = null;
73
+ for (const call of calls) {
74
+ const tool = get(call.name);
75
+ const safe = tool !== undefined && isConcurrencySafe(tool);
76
+ if (safe) {
77
+ if (currentBatch === null) {
78
+ currentBatch = [call];
79
+ concurrent.push(currentBatch);
80
+ } else {
81
+ currentBatch.push(call);
82
+ }
83
+ } else {
84
+ currentBatch = null;
85
+ serial.push(call);
86
+ }
87
+ }
88
+
89
+ return { concurrent, serial };
90
+ }