@crewhaus/tool-orchestrator 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.
- package/{src/index.ts → dist/index.d.ts} +4 -41
- package/dist/index.js +44 -0
- package/package.json +11 -8
- package/src/index.test.ts +0 -207
|
@@ -27,64 +27,27 @@
|
|
|
27
27
|
*/
|
|
28
28
|
import type { RegisteredTool, ToolCatalog } from "@crewhaus/tool-catalog";
|
|
29
29
|
import type { ToolUseBlock } from "@crewhaus/turn-state-machine";
|
|
30
|
-
|
|
31
30
|
export type ToolPartition = {
|
|
32
|
-
|
|
33
|
-
|
|
31
|
+
readonly concurrent: ReadonlyArray<ReadonlyArray<ToolUseBlock>>;
|
|
32
|
+
readonly serial: ReadonlyArray<ToolUseBlock>;
|
|
34
33
|
};
|
|
35
|
-
|
|
36
34
|
/**
|
|
37
35
|
* Function or `ToolCatalog` that resolves a tool name to its registered
|
|
38
36
|
* metadata. Returning `undefined` is treated as "unknown tool" and the
|
|
39
37
|
* call is routed serial so the executor can produce a clear error result.
|
|
40
38
|
*/
|
|
41
39
|
export type ToolLookup = ToolCatalog | ((name: string) => RegisteredTool | undefined);
|
|
42
|
-
|
|
43
40
|
/**
|
|
44
41
|
* Decide whether a registered tool's call is safe to run in parallel
|
|
45
42
|
* with sibling calls. Concurrency-safety is a triple-conjunction so a
|
|
46
43
|
* tool author has to opt into BOTH the concurrency contract and the
|
|
47
44
|
* read-only contract — destructive flag is the killswitch.
|
|
48
45
|
*/
|
|
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
|
-
|
|
46
|
+
export declare function isConcurrencySafe(tool: RegisteredTool): boolean;
|
|
58
47
|
/**
|
|
59
48
|
* Walk `calls` in order, grouping consecutive concurrency-safe calls
|
|
60
49
|
* into the same batch. A non-safe call breaks the run and is appended
|
|
61
50
|
* to `serial`. The order of returned concurrent batches mirrors the
|
|
62
51
|
* order in which they appeared in `calls`.
|
|
63
52
|
*/
|
|
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
|
-
}
|
|
53
|
+
export declare function partitionToolCalls(calls: ReadonlyArray<ToolUseBlock>, lookup: ToolLookup): ToolPartition;
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Decide whether a registered tool's call is safe to run in parallel
|
|
3
|
+
* with sibling calls. Concurrency-safety is a triple-conjunction so a
|
|
4
|
+
* tool author has to opt into BOTH the concurrency contract and the
|
|
5
|
+
* read-only contract — destructive flag is the killswitch.
|
|
6
|
+
*/
|
|
7
|
+
export function isConcurrencySafe(tool) {
|
|
8
|
+
return tool.concurrencySafe && tool.readOnly && !tool.destructive;
|
|
9
|
+
}
|
|
10
|
+
function asLookup(lookup) {
|
|
11
|
+
if (typeof lookup === "function")
|
|
12
|
+
return lookup;
|
|
13
|
+
return (name) => lookup.get(name);
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Walk `calls` in order, grouping consecutive concurrency-safe calls
|
|
17
|
+
* into the same batch. A non-safe call breaks the run and is appended
|
|
18
|
+
* to `serial`. The order of returned concurrent batches mirrors the
|
|
19
|
+
* order in which they appeared in `calls`.
|
|
20
|
+
*/
|
|
21
|
+
export function partitionToolCalls(calls, lookup) {
|
|
22
|
+
const get = asLookup(lookup);
|
|
23
|
+
const concurrent = [];
|
|
24
|
+
const serial = [];
|
|
25
|
+
let currentBatch = null;
|
|
26
|
+
for (const call of calls) {
|
|
27
|
+
const tool = get(call.name);
|
|
28
|
+
const safe = tool !== undefined && isConcurrencySafe(tool);
|
|
29
|
+
if (safe) {
|
|
30
|
+
if (currentBatch === null) {
|
|
31
|
+
currentBatch = [call];
|
|
32
|
+
concurrent.push(currentBatch);
|
|
33
|
+
}
|
|
34
|
+
else {
|
|
35
|
+
currentBatch.push(call);
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
else {
|
|
39
|
+
currentBatch = null;
|
|
40
|
+
serial.push(call);
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
return { concurrent, serial };
|
|
44
|
+
}
|
package/package.json
CHANGED
|
@@ -1,20 +1,23 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@crewhaus/tool-orchestrator",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.5",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Partition tool_use blocks into concurrent batches and serial calls based on catalog metadata",
|
|
6
|
-
"main": "
|
|
7
|
-
"types": "
|
|
6
|
+
"main": "dist/index.js",
|
|
7
|
+
"types": "dist/index.d.ts",
|
|
8
8
|
"exports": {
|
|
9
|
-
".":
|
|
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
|
-
"@crewhaus/errors": "0.1.
|
|
16
|
-
"@crewhaus/tool-catalog": "0.1.
|
|
17
|
-
"@crewhaus/turn-state-machine": "0.1.
|
|
18
|
+
"@crewhaus/errors": "0.1.5",
|
|
19
|
+
"@crewhaus/tool-catalog": "0.1.5",
|
|
20
|
+
"@crewhaus/turn-state-machine": "0.1.5"
|
|
18
21
|
},
|
|
19
22
|
"license": "Apache-2.0",
|
|
20
23
|
"author": {
|
|
@@ -34,5 +37,5 @@
|
|
|
34
37
|
"publishConfig": {
|
|
35
38
|
"access": "public"
|
|
36
39
|
},
|
|
37
|
-
"files": ["
|
|
40
|
+
"files": ["dist", "README.md", "LICENSE", "NOTICE"]
|
|
38
41
|
}
|
package/src/index.test.ts
DELETED
|
@@ -1,207 +0,0 @@
|
|
|
1
|
-
import { describe, expect, test } from "bun:test";
|
|
2
|
-
import { type RegisteredTool, ToolCatalog } 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
|
-
test("accepts a real ToolCatalog object (exercises the .get() lookup adapter)", () => {
|
|
123
|
-
// Passing a ToolCatalog instance (not a function) routes asLookup through
|
|
124
|
-
// the `(name) => lookup.get(name)` branch.
|
|
125
|
-
const catalog = new ToolCatalog();
|
|
126
|
-
catalog.register(READ);
|
|
127
|
-
catalog.register(BASH);
|
|
128
|
-
const calls = [call("Read", "1"), call("Bash", "2"), call("Read", "3")];
|
|
129
|
-
const out = partitionToolCalls(calls, catalog);
|
|
130
|
-
// Read is concurrency-safe (own batch), Bash is destructive (serial),
|
|
131
|
-
// trailing Read opens a fresh batch.
|
|
132
|
-
expect(out.concurrent.length).toBe(2);
|
|
133
|
-
expect(out.concurrent[0]?.map((c) => c.id)).toEqual(["1"]);
|
|
134
|
-
expect(out.concurrent[1]?.map((c) => c.id)).toEqual(["3"]);
|
|
135
|
-
expect(out.serial.map((c) => c.id)).toEqual(["2"]);
|
|
136
|
-
});
|
|
137
|
-
|
|
138
|
-
test("ToolCatalog lookup treats unregistered names as unknown → serial", () => {
|
|
139
|
-
const catalog = new ToolCatalog();
|
|
140
|
-
catalog.register(READ);
|
|
141
|
-
const calls = [call("Read", "1"), call("Ghost", "2")];
|
|
142
|
-
const out = partitionToolCalls(calls, catalog);
|
|
143
|
-
expect(out.concurrent[0]?.map((c) => c.id)).toEqual(["1"]);
|
|
144
|
-
expect(out.serial.map((c) => c.id)).toEqual(["2"]);
|
|
145
|
-
});
|
|
146
|
-
});
|
|
147
|
-
|
|
148
|
-
// T9 property test: invariant — no concurrent batch contains a call whose
|
|
149
|
-
// tool is destructive, !readOnly, or !concurrencySafe.
|
|
150
|
-
describe("partitionToolCalls — T9 property invariant", () => {
|
|
151
|
-
function randomBool(rand: () => number): boolean {
|
|
152
|
-
return rand() < 0.5;
|
|
153
|
-
}
|
|
154
|
-
function makeRandomTool(name: string, rand: () => number): RegisteredTool {
|
|
155
|
-
return makeTool({
|
|
156
|
-
name,
|
|
157
|
-
concurrencySafe: randomBool(rand),
|
|
158
|
-
readOnly: randomBool(rand),
|
|
159
|
-
destructive: randomBool(rand),
|
|
160
|
-
});
|
|
161
|
-
}
|
|
162
|
-
function mulberry32(seed: number): () => number {
|
|
163
|
-
let s = seed | 0;
|
|
164
|
-
return () => {
|
|
165
|
-
s = (s + 0x6d2b79f5) | 0;
|
|
166
|
-
let t = s;
|
|
167
|
-
t = Math.imul(t ^ (t >>> 15), t | 1);
|
|
168
|
-
t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
|
|
169
|
-
return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
|
|
170
|
-
};
|
|
171
|
-
}
|
|
172
|
-
|
|
173
|
-
test("100 random partitions never paralyze a destructive or non-safe tool", () => {
|
|
174
|
-
for (let seed = 0; seed < 100; seed++) {
|
|
175
|
-
const rand = mulberry32(seed);
|
|
176
|
-
const numTools = 1 + Math.floor(rand() * 8);
|
|
177
|
-
const toolMap = new Map<string, RegisteredTool>();
|
|
178
|
-
for (let i = 0; i < numTools; i++) {
|
|
179
|
-
const name = `T${i}`;
|
|
180
|
-
toolMap.set(name, makeRandomTool(name, rand));
|
|
181
|
-
}
|
|
182
|
-
const numCalls = Math.floor(rand() * 30);
|
|
183
|
-
const calls: ToolUseBlock[] = [];
|
|
184
|
-
for (let i = 0; i < numCalls; i++) {
|
|
185
|
-
const idx = Math.floor(rand() * numTools);
|
|
186
|
-
const name = `T${idx}`;
|
|
187
|
-
calls.push({ id: `c${i}`, name, input: {} });
|
|
188
|
-
}
|
|
189
|
-
|
|
190
|
-
const out = partitionToolCalls(calls, (n) => toolMap.get(n));
|
|
191
|
-
|
|
192
|
-
for (const batch of out.concurrent) {
|
|
193
|
-
for (const c of batch) {
|
|
194
|
-
const tool = toolMap.get(c.name);
|
|
195
|
-
expect(tool).toBeDefined();
|
|
196
|
-
if (!tool) continue;
|
|
197
|
-
expect(tool.destructive).toBe(false);
|
|
198
|
-
expect(tool.readOnly).toBe(true);
|
|
199
|
-
expect(tool.concurrencySafe).toBe(true);
|
|
200
|
-
}
|
|
201
|
-
}
|
|
202
|
-
// Every input call appears exactly once in either bucket.
|
|
203
|
-
const total = out.concurrent.flat().length + out.serial.length;
|
|
204
|
-
expect(total).toBe(calls.length);
|
|
205
|
-
}
|
|
206
|
-
});
|
|
207
|
-
});
|