@crewhaus/model-service 0.6.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/LICENSE +201 -0
- package/NOTICE +29 -0
- package/README.md +246 -0
- package/dist/index.d.ts +545 -0
- package/dist/index.js +522 -0
- package/dist/side-calls.d.ts +103 -0
- package/dist/side-calls.js +592 -0
- package/package.json +48 -0
package/dist/index.js
ADDED
|
@@ -0,0 +1,522 @@
|
|
|
1
|
+
import { classifyRouteLabel } from "@crewhaus/eval-judge";
|
|
2
|
+
import { escapeJsonString } from "@crewhaus/infra-utils";
|
|
3
|
+
import { createConsultTool, createEscalateTool, createEscalationLatch, resolveRosterTarget, rosterFromPool, strongestOf, } from "@crewhaus/tool-consult";
|
|
4
|
+
import { hasSideCallStrategy, runNestedSingleTurn, wireSideCalls, } from "./side-calls";
|
|
5
|
+
export { DEFAULT_GUIDE_MAX_TOKENS, DEFAULT_SHADOW_SAMPLE_RATE, GUIDE_INSTRUCTIONS, buildCommitteeSideCall, buildGuideSideCall, buildShadowSideCall, hasSideCallStrategy, latestUserText, runNestedSingleTurn, textOnlyTranscript, wireSideCalls, } from "./side-calls";
|
|
6
|
+
const _MODEL_WIRING_RUN_OPTIONS_PIN = true;
|
|
7
|
+
void _MODEL_WIRING_RUN_OPTIONS_PIN;
|
|
8
|
+
/** The routing keys, in the order every emitter and the interpreter have
|
|
9
|
+
* always written them. `wireModels` returns them in this order and
|
|
10
|
+
* {@link renderModelWiringFields} renders them in this order. */
|
|
11
|
+
export const MODEL_WIRING_KEYS = [
|
|
12
|
+
"modelFallbacks",
|
|
13
|
+
"circuitBreaker",
|
|
14
|
+
"modelTiers",
|
|
15
|
+
"modelPool",
|
|
16
|
+
];
|
|
17
|
+
/** The hybrid-tool keys `wireModels` appends after {@link MODEL_WIRING_KEYS}
|
|
18
|
+
* when the pool declares `strategy.model_directed: true`. Never rendered by
|
|
19
|
+
* {@link renderModelWiringFields}: they are runtime constructions, carried
|
|
20
|
+
* into a bundle by {@link renderHybridWiringFields}. */
|
|
21
|
+
export const HYBRID_WIRING_KEYS = ["hybridTools", "escalation"];
|
|
22
|
+
/** 0.6.0 §7.2.3 — the key `wireModels` appends after the hybrid keys when
|
|
23
|
+
* the pool declares `policy: classifier` with a `classifier:` block. A
|
|
24
|
+
* runtime construction, never rendered by {@link renderModelWiringFields}. */
|
|
25
|
+
export const CLASSIFIER_WIRING_KEYS = ["routeClassifier"];
|
|
26
|
+
/** The side-call key `wireModels` appends LAST when the pool's strategy
|
|
27
|
+
* declares a guide, a shadow or a committee (PR 9d). A runtime
|
|
28
|
+
* construction: rendered into a bundle by
|
|
29
|
+
* {@link renderHybridWiringFields}, never by
|
|
30
|
+
* {@link renderModelWiringFields}. */
|
|
31
|
+
export const SIDE_CALL_WIRING_KEYS = ["sideCalls"];
|
|
32
|
+
/** Every key {@link wireHybrid} can add, in the order it adds them — the
|
|
33
|
+
* runtime constructions {@link renderModelWiringFields} never renders and
|
|
34
|
+
* {@link renderHybridWiringFields} carries into a bundle instead. */
|
|
35
|
+
export const HYBRID_CONSTRUCTION_KEYS = [
|
|
36
|
+
...HYBRID_WIRING_KEYS,
|
|
37
|
+
...CLASSIFIER_WIRING_KEYS,
|
|
38
|
+
...SIDE_CALL_WIRING_KEYS,
|
|
39
|
+
];
|
|
40
|
+
/**
|
|
41
|
+
* Pick the routing slice out of a lowered block EXACTLY as the retired
|
|
42
|
+
* per-emitter renderers read it — only declared keys are carried, and an
|
|
43
|
+
* EMPTY `modelFallbacks` array is treated as absent (the emitters' and the
|
|
44
|
+
* interpreter's `length > 0` guard), so a spec that declares no chain wires
|
|
45
|
+
* no chain. Values are carried by reference, never copied or re-shaped:
|
|
46
|
+
* the pool blob's key order is a byte contract (`model` then `tags` first,
|
|
47
|
+
* every 0.6.0 key after — the compiler's key-order guard).
|
|
48
|
+
*/
|
|
49
|
+
export function modelWiringFragmentFromIr(block) {
|
|
50
|
+
const fallbacks = block.modelFallbacks;
|
|
51
|
+
return {
|
|
52
|
+
...(fallbacks !== undefined && fallbacks.length > 0 ? { modelFallbacks: fallbacks } : {}),
|
|
53
|
+
...(block.circuitBreaker !== undefined ? { circuitBreaker: block.circuitBreaker } : {}),
|
|
54
|
+
...(block.modelTiers !== undefined ? { modelTiers: block.modelTiers } : {}),
|
|
55
|
+
...(block.modelPool !== undefined ? { modelPool: block.modelPool } : {}),
|
|
56
|
+
};
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* 0.6.0 §7.9 (PR 9a) — the emit-side twin of `@crewhaus/crew-orchestrator`'s
|
|
60
|
+
* `scopeRolePool`: a block's fragment with its pool's `scope` defaulted to
|
|
61
|
+
* the host's name (a workflow step, a graph node) when the spec pinned none.
|
|
62
|
+
* The compiler deliberately leaves `scope` unstamped at lower time (the IR
|
|
63
|
+
* blob is what README / loop projections read), so the emitter that knows
|
|
64
|
+
* which step or node a `runChatLoop` call belongs to stamps it where the
|
|
65
|
+
* loop options are assembled — runtime-core stamps the result on
|
|
66
|
+
* `model_route.scope`, and the routing store keys arms by it from PR 10 on.
|
|
67
|
+
* A declared `scope` always wins; a fragment without a pool is returned
|
|
68
|
+
* untouched (object identity kept), so un-pooled steps and nodes stay
|
|
69
|
+
* byte-identical.
|
|
70
|
+
*/
|
|
71
|
+
export function scopedModelWiringFragment(block, scope) {
|
|
72
|
+
const pool = block.modelPool;
|
|
73
|
+
if (pool === undefined || pool.scope !== undefined)
|
|
74
|
+
return block;
|
|
75
|
+
return { ...modelWiringFragmentFromIr(block), modelPool: { ...pool, scope } };
|
|
76
|
+
}
|
|
77
|
+
// ---------------------------------------------------------------------------
|
|
78
|
+
// wireModels — the composition root
|
|
79
|
+
// ---------------------------------------------------------------------------
|
|
80
|
+
/**
|
|
81
|
+
* THE one stable call. Returns the spread-ready `RunChatLoopOptions` slice
|
|
82
|
+
* for a fragment: every key present only when the fragment declares it
|
|
83
|
+
* (spread-return-`{}` discipline — an empty fragment yields `{}` and the
|
|
84
|
+
* runtime defaults stay authoritative), values by reference, keys in
|
|
85
|
+
* {@link MODEL_WIRING_KEYS} order, then {@link HYBRID_WIRING_KEYS} when the
|
|
86
|
+
* pool declares `strategy.model_directed: true`.
|
|
87
|
+
*
|
|
88
|
+
* Still synchronous. The runtime resolves candidate adapters, opens the
|
|
89
|
+
* scoreboard and builds the PolicyRouter inside `runChatLoop` from the four
|
|
90
|
+
* routing options exactly as it did when each emitter rendered them by hand
|
|
91
|
+
* (moving that construction here is PR 9a/10's job). What this root DOES
|
|
92
|
+
* construct today is the model-directed pair: the `Consult` tool over a
|
|
93
|
+
* nested-`runChatLoop` runner on the roster, and the `Escalate` tool with the
|
|
94
|
+
* latch the loop consumes — see {@link wireModelDirected}.
|
|
95
|
+
*/
|
|
96
|
+
export function wireModels(fragment, deps) {
|
|
97
|
+
const overridden = typeof deps.modelOverride === "string";
|
|
98
|
+
const fallbacks = fragment.modelFallbacks;
|
|
99
|
+
const pool = !overridden ? fragment.modelPool : undefined;
|
|
100
|
+
return {
|
|
101
|
+
...(!overridden && fallbacks !== undefined && fallbacks.length > 0
|
|
102
|
+
? { modelFallbacks: fallbacks }
|
|
103
|
+
: {}),
|
|
104
|
+
...(fragment.circuitBreaker !== undefined ? { circuitBreaker: fragment.circuitBreaker } : {}),
|
|
105
|
+
...(!overridden && fragment.modelTiers !== undefined
|
|
106
|
+
? { modelTiers: fragment.modelTiers }
|
|
107
|
+
: {}),
|
|
108
|
+
...(pool !== undefined ? { modelPool: pool } : {}),
|
|
109
|
+
...(pool !== undefined ? wireHybrid(pool, deps) : {}),
|
|
110
|
+
};
|
|
111
|
+
}
|
|
112
|
+
/** Every family, in the order {@link wireHybrid} constructs them. The default
|
|
113
|
+
* when a caller passes no `hybridFamilies` — the interpreter's posture. */
|
|
114
|
+
export const ALL_HYBRID_WIRING_FAMILIES = [
|
|
115
|
+
"modelDirected",
|
|
116
|
+
"classifier",
|
|
117
|
+
"sideCalls",
|
|
118
|
+
];
|
|
119
|
+
/**
|
|
120
|
+
* **Plan §11.3, in code.** Shape → the closure families that shape's COMPILED
|
|
121
|
+
* bundle constructs, which since PR 9f is also exactly what its emitter
|
|
122
|
+
* renders and what the compiler declines to warn about. The table is
|
|
123
|
+
* published verbatim in crewhaus/docs `COMPILER-ARCHITECTURE.md` and the
|
|
124
|
+
* book's appendix D and printed per-shape by `models explain`, so it lives
|
|
125
|
+
* HERE — one table three consumers read — rather than being restated at each
|
|
126
|
+
* seam and drifting from the emitters (which is precisely what PR 9e's known
|
|
127
|
+
* shortfall was).
|
|
128
|
+
*
|
|
129
|
+
* Reading the matrix rows:
|
|
130
|
+
*
|
|
131
|
+
* - The ten pool-bearing shapes take `classifier` and `sideCalls`. `committee`
|
|
132
|
+
* is a `sideCalls` member but the strict schema already refuses it anywhere
|
|
133
|
+
* §11.3 marks it `—` (`SpecRoutedHost.committee`), so no shape needs to
|
|
134
|
+
* decline the family for it.
|
|
135
|
+
* - `pipeline` declines `modelDirected`: §11.3 marks `Consult / Escalate` `—`
|
|
136
|
+
* on that row, and the table is the only ground for it. Mechanically the
|
|
137
|
+
* shape could host the pair: {@link wireModelDirected} builds Consult /
|
|
138
|
+
* Escalate from the POOL roster and returns them as ADDITIVE `hybridTools`
|
|
139
|
+
* — it narrows no shape toolset (the consulted model gets none at all), and
|
|
140
|
+
* the emitted pipeline bundle registers a tool catalog of its own.
|
|
141
|
+
* `toolLess` in `@crewhaus/spec` says only that the pipeline SPEC has no
|
|
142
|
+
* `tools:` key, which is why a per-model `tools` list is refused there — a
|
|
143
|
+
* different fact. So this row is a plan decision open to revision, not a
|
|
144
|
+
* shape fact, and the compiler's warning says so.
|
|
145
|
+
* - The four shapes with no `model_pool` block at all (`voice`, `eval`,
|
|
146
|
+
* `onchain`, `onchain-game` — `—` in the pool column) take no family; the
|
|
147
|
+
* strict schema refuses the block before any of this is reached.
|
|
148
|
+
*/
|
|
149
|
+
export const HYBRID_FAMILIES_BY_SHAPE = {
|
|
150
|
+
cli: ALL_HYBRID_WIRING_FAMILIES,
|
|
151
|
+
workflow: ALL_HYBRID_WIRING_FAMILIES,
|
|
152
|
+
channel: ALL_HYBRID_WIRING_FAMILIES,
|
|
153
|
+
graph: ALL_HYBRID_WIRING_FAMILIES,
|
|
154
|
+
managed: ALL_HYBRID_WIRING_FAMILIES,
|
|
155
|
+
pipeline: ["classifier", "sideCalls"],
|
|
156
|
+
crew: ALL_HYBRID_WIRING_FAMILIES,
|
|
157
|
+
research: ALL_HYBRID_WIRING_FAMILIES,
|
|
158
|
+
batch: ALL_HYBRID_WIRING_FAMILIES,
|
|
159
|
+
voice: [],
|
|
160
|
+
browser: ALL_HYBRID_WIRING_FAMILIES,
|
|
161
|
+
eval: [],
|
|
162
|
+
onchain: [],
|
|
163
|
+
"onchain-game": [],
|
|
164
|
+
};
|
|
165
|
+
/** The §11.3 row for a shape — {@link HYBRID_FAMILIES_BY_SHAPE} with a total
|
|
166
|
+
* signature, so a caller holding a widened `string` gets `[]` (wires
|
|
167
|
+
* nothing) rather than `undefined`. */
|
|
168
|
+
export function hybridWiringFamiliesForShape(shape) {
|
|
169
|
+
return (HYBRID_FAMILIES_BY_SHAPE[shape] ?? []);
|
|
170
|
+
}
|
|
171
|
+
/** Does a pool declare the given closure family? The per-family half of
|
|
172
|
+
* {@link poolNeedsHybridWiring}, so the gate, the builder and the renderer
|
|
173
|
+
* all ask one question. */
|
|
174
|
+
export function poolDeclaresHybridFamily(pool, family) {
|
|
175
|
+
switch (family) {
|
|
176
|
+
case "modelDirected":
|
|
177
|
+
return pool.strategy?.modelDirected === true;
|
|
178
|
+
case "classifier":
|
|
179
|
+
return pool.policy === "classifier" && pool.classifier !== undefined;
|
|
180
|
+
case "sideCalls":
|
|
181
|
+
return hasSideCallStrategy(pool);
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
/**
|
|
185
|
+
* True when a pool declares at least one closure-shaped feature the HOST can
|
|
186
|
+
* construct: `strategy.model_directed` (Consult + Escalate), `policy:
|
|
187
|
+
* classifier` with a `classifier:` block, or `strategy.{guide,shadow,
|
|
188
|
+
* committee}`. The gate every emitter's codegen and import both key on, so
|
|
189
|
+
* "wires nothing" and "renders nothing" can never disagree.
|
|
190
|
+
*
|
|
191
|
+
* `families` narrows the question to the shape's §11.3 row (PR 9f): a
|
|
192
|
+
* `pipeline` pool that declares ONLY `strategy.model_directed` needs no
|
|
193
|
+
* wiring, because that shape constructs no model-directed pair — so it also
|
|
194
|
+
* renders no call and imports nothing, and the compiler warns on the key
|
|
195
|
+
* instead. Omitted, every family counts (the interpreter's posture).
|
|
196
|
+
*/
|
|
197
|
+
export function poolNeedsHybridWiring(pool, families = ALL_HYBRID_WIRING_FAMILIES) {
|
|
198
|
+
if (pool === undefined)
|
|
199
|
+
return false;
|
|
200
|
+
return families.some((f) => poolDeclaresHybridFamily(pool, f));
|
|
201
|
+
}
|
|
202
|
+
/**
|
|
203
|
+
* 0.6.0 §7.2.3 / §7.2.4 / §7.4 / §7.6 / §7.8 (PR 9e) — build every runtime
|
|
204
|
+
* closure a pool declares, in ONE call: the model-directed pair, the route
|
|
205
|
+
* classifier, and the guide / shadow / committee side calls. Spread-return-
|
|
206
|
+
* `{}` — a pool declaring none of them yields no keys at all.
|
|
207
|
+
*
|
|
208
|
+
* This is the whole of what `wireModels` appends beyond the four literal
|
|
209
|
+
* routing fields, factored out precisely so a compiled bundle can call it
|
|
210
|
+
* directly: {@link renderHybridWiringFields} renders
|
|
211
|
+
* `...wireHybrid(<pool blob>, { sessionName })` into the generated
|
|
212
|
+
* `runChatLoop({...})`, and the interpreter reaches the same code through
|
|
213
|
+
* `wireModels`. One code path, not a mirror — pinned by test.
|
|
214
|
+
*/
|
|
215
|
+
export function wireHybrid(pool, deps) {
|
|
216
|
+
const families = deps.hybridFamilies ?? ALL_HYBRID_WIRING_FAMILIES;
|
|
217
|
+
const wires = (family) => families.includes(family) && poolDeclaresHybridFamily(pool, family);
|
|
218
|
+
return {
|
|
219
|
+
...(wires("modelDirected") ? wireModelDirected(pool, deps) : {}),
|
|
220
|
+
...(wires("classifier") && pool.classifier !== undefined
|
|
221
|
+
? { routeClassifier: buildRouteClassifier(pool.classifier, deps) }
|
|
222
|
+
: {}),
|
|
223
|
+
...(wires("sideCalls") ? wireSideCalls(pool, deps) : {}),
|
|
224
|
+
};
|
|
225
|
+
}
|
|
226
|
+
/**
|
|
227
|
+
* The codegen twin of {@link wireHybrid}: the spread field an emitter renders
|
|
228
|
+
* onto a pooled block's `runChatLoop({...})` (or a channel `createAgent`
|
|
229
|
+
* body) when the pool declares a closure-shaped feature —
|
|
230
|
+
* `\n<indent>...wireHybrid(<pool blob>, { sessionName: "…" }),` — so the
|
|
231
|
+
* bundle constructs the closures at boot through THIS package. `""` for every
|
|
232
|
+
* other pool, which is what keeps pre-0.6.0 bundles byte-identical: no field,
|
|
233
|
+
* and (because the emitter gates its import on the same
|
|
234
|
+
* {@link poolNeedsHybridWiring} predicate) no `@crewhaus/model-service`
|
|
235
|
+
* import either.
|
|
236
|
+
*
|
|
237
|
+
* The pool blob is the same `JSON.stringify` {@link renderModelWiringFields}
|
|
238
|
+
* already writes for `modelPool`, so the closures and the literal option are
|
|
239
|
+
* built from byte-identical config. `sessionName` is the harness name the
|
|
240
|
+
* nested side calls label their spend with.
|
|
241
|
+
*
|
|
242
|
+
* `families` (PR 9f) is the emitter's §11.3 row —
|
|
243
|
+
* {@link hybridWiringFamiliesForShape} for its own target. A shape that
|
|
244
|
+
* declines a family renders `hybridFamilies: [...]` into the call, so the
|
|
245
|
+
* BUNDLE applies the same restriction the interpreter would; a shape that
|
|
246
|
+
* hosts every family renders exactly the 9e text, which is what keeps the six
|
|
247
|
+
* emitters wired then byte-identical now.
|
|
248
|
+
*/
|
|
249
|
+
export function renderHybridWiringFields(fragment, indent, sessionName, families = ALL_HYBRID_WIRING_FAMILIES) {
|
|
250
|
+
const pool = fragment.modelPool;
|
|
251
|
+
if (!poolNeedsHybridWiring(pool, families))
|
|
252
|
+
return "";
|
|
253
|
+
const restricted = ALL_HYBRID_WIRING_FAMILIES.every((f) => families.includes(f))
|
|
254
|
+
? ""
|
|
255
|
+
: `, hybridFamilies: ${JSON.stringify(ALL_HYBRID_WIRING_FAMILIES.filter((f) => families.includes(f)))}`;
|
|
256
|
+
return `\n${indent}...wireHybrid(${JSON.stringify(pool)}, { sessionName: ${escapeJsonString(sessionName)}${restricted} }),`;
|
|
257
|
+
}
|
|
258
|
+
/** The import line a bundle carries when {@link renderHybridWiringFields}
|
|
259
|
+
* rendered a field. One constant so the ten emitters cannot drift. */
|
|
260
|
+
export const HYBRID_WIRING_IMPORT = 'import { wireHybrid } from "@crewhaus/model-service";';
|
|
261
|
+
// ---------------------------------------------------------------------------
|
|
262
|
+
// Classifier-directed: the `policy: classifier` label call (plan §7.2.3)
|
|
263
|
+
// ---------------------------------------------------------------------------
|
|
264
|
+
/**
|
|
265
|
+
* Build the {@link RouteClassifierFn} for a pool's `classifier:` block: one
|
|
266
|
+
* enum-constrained forced-tool call on the classifier model per turn
|
|
267
|
+
* (`@crewhaus/eval-judge`'s `classifyRouteLabel`), published on the RUN bus
|
|
268
|
+
* the loop hands in with `role: "classifier"` — so cost-tracker prices it,
|
|
269
|
+
* the budget meter counts it under `judge_share`, and the session mirror
|
|
270
|
+
* persists it. The labels are the block's own (`tag → description`); the
|
|
271
|
+
* loop re-validates the verdict against the pool's tags. Any throw
|
|
272
|
+
* propagates: runtime-core's `preRoute` turns it into the heuristic fallback
|
|
273
|
+
* with `reason: "classifier failed"`. The model resolves through the
|
|
274
|
+
* model-router on first call unless a test injects `_classifierAdapter`.
|
|
275
|
+
*/
|
|
276
|
+
export function buildRouteClassifier(classifier, deps) {
|
|
277
|
+
return async ({ userText, bus }) => {
|
|
278
|
+
const verdict = await classifyRouteLabel({
|
|
279
|
+
labels: classifier.labels,
|
|
280
|
+
userText,
|
|
281
|
+
model: classifier.model,
|
|
282
|
+
...(classifier.maxTokens !== undefined ? { maxTokens: classifier.maxTokens } : {}),
|
|
283
|
+
...(deps._classifierAdapter !== undefined ? { adapter: deps._classifierAdapter } : {}),
|
|
284
|
+
bus,
|
|
285
|
+
role: "classifier",
|
|
286
|
+
});
|
|
287
|
+
return {
|
|
288
|
+
label: verdict.label,
|
|
289
|
+
model: verdict.usage.model,
|
|
290
|
+
...(verdict.usage.costUsdMicros !== undefined
|
|
291
|
+
? { costUsdMicros: verdict.usage.costUsdMicros }
|
|
292
|
+
: {}),
|
|
293
|
+
};
|
|
294
|
+
};
|
|
295
|
+
}
|
|
296
|
+
// ---------------------------------------------------------------------------
|
|
297
|
+
// Model-directed: Consult + Escalate (plan §7.2.4, §7.5)
|
|
298
|
+
// ---------------------------------------------------------------------------
|
|
299
|
+
/**
|
|
300
|
+
* Build the `Consult` / `Escalate` pair for a pool that declares
|
|
301
|
+
* `strategy.model_directed: true`. The roster is the pool's ENABLED
|
|
302
|
+
* candidates; the escalation target is `strategy.cascade.escalateTo`
|
|
303
|
+
* resolved against the roster (a tag, profile or model string), else the
|
|
304
|
+
* strongest candidate (first `routing.strongTag`-tagged, else the last
|
|
305
|
+
* declared — the router's `escalation()` convention); `strategy.
|
|
306
|
+
* max_escalations` bounds the latch (default 1). A pool the compiler let
|
|
307
|
+
* through with no enabled candidate wires nothing rather than throwing.
|
|
308
|
+
*/
|
|
309
|
+
export function wireModelDirected(pool, deps) {
|
|
310
|
+
const roster = rosterFromPool(pool);
|
|
311
|
+
if (roster.length === 0)
|
|
312
|
+
return {};
|
|
313
|
+
const strongTag = pool.routing?.strongTag;
|
|
314
|
+
const escalateTo = pool.strategy?.cascade?.escalateTo;
|
|
315
|
+
const target = (escalateTo !== undefined ? resolveRosterTarget(roster, escalateTo, strongTag) : undefined) ??
|
|
316
|
+
strongestOf(roster, strongTag);
|
|
317
|
+
const latch = createEscalationLatch({
|
|
318
|
+
target,
|
|
319
|
+
...(pool.strategy?.maxEscalations !== undefined
|
|
320
|
+
? { maxEscalations: pool.strategy.maxEscalations }
|
|
321
|
+
: {}),
|
|
322
|
+
});
|
|
323
|
+
const run = deps._consultRunner ?? buildConsultRunner(deps);
|
|
324
|
+
const consult = createConsultTool({
|
|
325
|
+
roster,
|
|
326
|
+
run,
|
|
327
|
+
...(strongTag !== undefined ? { strongTag } : {}),
|
|
328
|
+
});
|
|
329
|
+
const escalate = createEscalateTool({ latch });
|
|
330
|
+
return { hybridTools: [consult, escalate], escalation: latch };
|
|
331
|
+
}
|
|
332
|
+
/** The consulted model's system prompt — it sees the question, nothing else. */
|
|
333
|
+
export const CONSULT_INSTRUCTIONS = "You are being consulted by another model of the same harness on one question. Answer it directly and concisely, using only the question and the context you are given. You have no tools and cannot see the rest of the conversation; if the question cannot be answered from what you were given, say exactly what is missing.";
|
|
334
|
+
/**
|
|
335
|
+
* The Consult side call (plan §7.5 / §7.6) — one nested single-turn
|
|
336
|
+
* `runChatLoop` on the roster target through {@link runNestedSingleTurn}:
|
|
337
|
+
* own child `RunContext` and child bus (the singleTurn path mutates
|
|
338
|
+
* `runContext.turnNumber`, so a shared context would inject phantom turns),
|
|
339
|
+
* model events re-published on the PARENT bus under `role: "consult"` so the
|
|
340
|
+
* parent's cost-tracker prices them and its `budgetMeter` counts them under
|
|
341
|
+
* `judge_share`, and — since PR 9d, plan §16 Q6 — `persistSession: false`,
|
|
342
|
+
* so a consult no longer writes a child session file like a Task child.
|
|
343
|
+
*
|
|
344
|
+
* Returns the raw reply text — classification at TrustOrigin "consult"
|
|
345
|
+
* (`classifyBoundary` + `tagContent`) is the tool's job in
|
|
346
|
+
* `@crewhaus/tool-consult`, exactly once.
|
|
347
|
+
*/
|
|
348
|
+
export function buildConsultRunner(deps) {
|
|
349
|
+
return async ({ target, question, context, runContext: parent, signal }) => {
|
|
350
|
+
const content = context !== undefined && context.trim().length > 0
|
|
351
|
+
? `${context.trim()}
|
|
352
|
+
|
|
353
|
+
---
|
|
354
|
+
|
|
355
|
+
Question: ${question}`
|
|
356
|
+
: question;
|
|
357
|
+
const result = await runNestedSingleTurn({
|
|
358
|
+
target: {
|
|
359
|
+
modelString: target.modelString,
|
|
360
|
+
...(target.profile !== undefined ? { profile: target.profile } : {}),
|
|
361
|
+
},
|
|
362
|
+
instructions: CONSULT_INSTRUCTIONS,
|
|
363
|
+
seedMessages: [{ role: "user", content }],
|
|
364
|
+
role: "consult",
|
|
365
|
+
...(parent !== undefined ? { parent } : {}),
|
|
366
|
+
...(signal !== undefined ? { signal } : {}),
|
|
367
|
+
sessionTarget: "consult",
|
|
368
|
+
deps,
|
|
369
|
+
});
|
|
370
|
+
return { text: result.text, model: result.model };
|
|
371
|
+
};
|
|
372
|
+
}
|
|
373
|
+
// ---------------------------------------------------------------------------
|
|
374
|
+
// The codegen twin — what an emitter writes into a bundle
|
|
375
|
+
// ---------------------------------------------------------------------------
|
|
376
|
+
/**
|
|
377
|
+
* Render the routing fields of a fragment as object-literal source for a
|
|
378
|
+
* generated `runChatLoop({...})` (or crew `RoleDefinition`) call — the
|
|
379
|
+
* codegen twin of {@link wireModels}, byte-for-byte the string the ten
|
|
380
|
+
* emitters used to build by hand:
|
|
381
|
+
*
|
|
382
|
+
* `\n<indent>modelFallbacks: ["a", "b"],`
|
|
383
|
+
* `\n<indent>circuitBreaker: {"failureThreshold":2},`
|
|
384
|
+
* `\n<indent>modelTiers: {"fast":"…","default":"…"},`
|
|
385
|
+
* `\n<indent>modelPool: {"candidates":[…],"policy":"heuristic"},`
|
|
386
|
+
*
|
|
387
|
+
* Model strings pass through `escapeJsonString` (user-controlled spec values
|
|
388
|
+
* landing in generated source); the breaker / tiers / pool blocks are
|
|
389
|
+
* validated numbers, strings and closed-literal unions, safe to
|
|
390
|
+
* `JSON.stringify` as plain object literals. Returns `""` when the fragment
|
|
391
|
+
* declares nothing, so pre-existing bundles stay byte-identical. `indent`
|
|
392
|
+
* is the caller's field indentation (two spaces for target-cli's top-level
|
|
393
|
+
* call, eight inside a channel `createAgent` body, …).
|
|
394
|
+
*
|
|
395
|
+
* Evaluating the rendered fields yields exactly `wireModels(fragment, {})`
|
|
396
|
+
* — pinned in `index.test.ts` — which is what makes a compiled bundle and
|
|
397
|
+
* the `crewhaus run` interpreter one code path rather than a mirror.
|
|
398
|
+
*/
|
|
399
|
+
export function renderModelWiringFields(fragment, indent) {
|
|
400
|
+
const pieces = [];
|
|
401
|
+
const fallbacks = fragment.modelFallbacks;
|
|
402
|
+
if (fallbacks !== undefined && fallbacks.length > 0) {
|
|
403
|
+
pieces.push(`\n${indent}modelFallbacks: [${fallbacks.map((m) => escapeJsonString(m)).join(", ")}],`);
|
|
404
|
+
}
|
|
405
|
+
if (fragment.circuitBreaker !== undefined) {
|
|
406
|
+
pieces.push(`\n${indent}circuitBreaker: ${JSON.stringify(fragment.circuitBreaker)},`);
|
|
407
|
+
}
|
|
408
|
+
if (fragment.modelTiers !== undefined) {
|
|
409
|
+
pieces.push(`\n${indent}modelTiers: ${JSON.stringify(fragment.modelTiers)},`);
|
|
410
|
+
}
|
|
411
|
+
if (fragment.modelPool !== undefined) {
|
|
412
|
+
pieces.push(`\n${indent}modelPool: ${JSON.stringify(fragment.modelPool)},`);
|
|
413
|
+
}
|
|
414
|
+
return pieces.join("");
|
|
415
|
+
}
|
|
416
|
+
/**
|
|
417
|
+
* 0.6.0 §7.7 — render one `IrSubAgentDefinition` as the single-line TS object
|
|
418
|
+
* literal the emitted `__subAgents` Map holds (a runtime
|
|
419
|
+
* `SubAgentDefinition`). ONE renderer for the three emitters that register
|
|
420
|
+
* the Task tool (cli, channel-bot, crew) — until PR 11 each carried a
|
|
421
|
+
* hand-mirrored copy with a "keep the three in sync" comment.
|
|
422
|
+
*
|
|
423
|
+
* Byte contract: the seven fields a 0.5.x definition has (`name`,
|
|
424
|
+
* `description`, `instructions`, `tools`, `model`, `permissions`,
|
|
425
|
+
* `inherit_bypass`) render exactly as the copies did, in that order; every
|
|
426
|
+
* 0.6.0 key (`modelProfile`, `overlay`, the params, the routing quartet,
|
|
427
|
+
* `budgetShare`, `inheritRouting`, `allowedProfiles`) is appended AFTER them and ONLY when
|
|
428
|
+
* present, so a spec whose sub-agents carry only today's fields emits a
|
|
429
|
+
* byte-identical bundle. The 0.6.0 keys use the runtime `SubAgentDefinition`
|
|
430
|
+
* names (camelCase, identical to the IR's) — `inherit_bypass` keeps its
|
|
431
|
+
* legacy spelling.
|
|
432
|
+
*/
|
|
433
|
+
export function renderSubAgentDef(d) {
|
|
434
|
+
const lines = [];
|
|
435
|
+
lines.push(`name: ${escapeJsonString(d.name)}`);
|
|
436
|
+
lines.push(`description: ${escapeJsonString(d.description)}`);
|
|
437
|
+
lines.push(`instructions: ${escapeJsonString(d.instructions)}`);
|
|
438
|
+
lines.push(`tools: ${JSON.stringify(d.tools)}`);
|
|
439
|
+
if (d.model !== undefined)
|
|
440
|
+
lines.push(`model: ${escapeJsonString(d.model)}`);
|
|
441
|
+
if (typeof d.permissions === "string") {
|
|
442
|
+
lines.push(`permissions: ${escapeJsonString(d.permissions)}`);
|
|
443
|
+
}
|
|
444
|
+
else {
|
|
445
|
+
lines.push(`permissions: { allow: ${JSON.stringify(d.permissions.allow)}, deny: ${JSON.stringify(d.permissions.deny)} }`);
|
|
446
|
+
}
|
|
447
|
+
lines.push(`inherit_bypass: ${d.inheritBypass}`);
|
|
448
|
+
if (d.modelProfile !== undefined)
|
|
449
|
+
lines.push(`modelProfile: ${escapeJsonString(d.modelProfile)}`);
|
|
450
|
+
if (d.overlay !== undefined)
|
|
451
|
+
lines.push(`overlay: ${escapeJsonString(d.overlay)}`);
|
|
452
|
+
if (d.thinking !== undefined)
|
|
453
|
+
lines.push(`thinking: ${JSON.stringify(d.thinking)}`);
|
|
454
|
+
if (d.maxTokens !== undefined)
|
|
455
|
+
lines.push(`maxTokens: ${d.maxTokens}`);
|
|
456
|
+
if (d.temperature !== undefined)
|
|
457
|
+
lines.push(`temperature: ${d.temperature}`);
|
|
458
|
+
if (d.modelFallbacks !== undefined && d.modelFallbacks.length > 0) {
|
|
459
|
+
lines.push(`modelFallbacks: ${JSON.stringify(d.modelFallbacks)}`);
|
|
460
|
+
}
|
|
461
|
+
if (d.circuitBreaker !== undefined) {
|
|
462
|
+
lines.push(`circuitBreaker: ${JSON.stringify(d.circuitBreaker)}`);
|
|
463
|
+
}
|
|
464
|
+
if (d.modelTiers !== undefined)
|
|
465
|
+
lines.push(`modelTiers: ${JSON.stringify(d.modelTiers)}`);
|
|
466
|
+
if (d.modelPool !== undefined)
|
|
467
|
+
lines.push(`modelPool: ${JSON.stringify(d.modelPool)}`);
|
|
468
|
+
if (d.budgetShare !== undefined)
|
|
469
|
+
lines.push(`budgetShare: ${d.budgetShare}`);
|
|
470
|
+
if (d.inheritRouting !== undefined)
|
|
471
|
+
lines.push(`inheritRouting: ${d.inheritRouting}`);
|
|
472
|
+
if (d.allowedProfiles !== undefined) {
|
|
473
|
+
lines.push(`allowedProfiles: ${JSON.stringify(d.allowedProfiles)}`);
|
|
474
|
+
}
|
|
475
|
+
return `{ ${lines.join(", ")} }`;
|
|
476
|
+
}
|
|
477
|
+
/** The import a judge site's bundle needs for {@link renderJudgePanelFields}. */
|
|
478
|
+
export const JUDGE_PANEL_IMPORT = 'import { gradeWithJudgePanel, inLoopRunResult } from "@crewhaus/eval-judge";';
|
|
479
|
+
/**
|
|
480
|
+
* Render the panel fields of a `gradeWithJudgePanel({ … })` call, in a fixed
|
|
481
|
+
* order (`model`, `judges`, `repeats`, `temperature`, `target`, `params`)
|
|
482
|
+
* and ONLY when present — a spec that declares none of the §6.2 knobs emits
|
|
483
|
+
* exactly `model: "…"`, so its judge behaves as the single-model `judge()`
|
|
484
|
+
* call did before this seam existed.
|
|
485
|
+
*
|
|
486
|
+
* Model strings and the `target` literal pass through `escapeJsonString`
|
|
487
|
+
* (they are user-controlled spec values); `params` is a plain lowered object
|
|
488
|
+
* and renders through `JSON.stringify`.
|
|
489
|
+
*/
|
|
490
|
+
export function renderJudgePanelFields(panel, indent) {
|
|
491
|
+
const pieces = [];
|
|
492
|
+
if (panel.model !== undefined) {
|
|
493
|
+
pieces.push(`\n${indent}model: ${escapeJsonString(panel.model)},`);
|
|
494
|
+
}
|
|
495
|
+
if (panel.judges !== undefined && panel.judges.length > 0) {
|
|
496
|
+
pieces.push(`\n${indent}judges: [${panel.judges.map((m) => escapeJsonString(m)).join(", ")}],`);
|
|
497
|
+
}
|
|
498
|
+
if (panel.repeats !== undefined)
|
|
499
|
+
pieces.push(`\n${indent}repeats: ${panel.repeats},`);
|
|
500
|
+
if (panel.temperature !== undefined) {
|
|
501
|
+
pieces.push(`\n${indent}temperature: ${panel.temperature},`);
|
|
502
|
+
}
|
|
503
|
+
if (panel.target !== undefined) {
|
|
504
|
+
pieces.push(`\n${indent}target: ${escapeJsonString(panel.target)},`);
|
|
505
|
+
}
|
|
506
|
+
if (panel.params !== undefined) {
|
|
507
|
+
pieces.push(`\n${indent}params: ${JSON.stringify(panel.params)},`);
|
|
508
|
+
}
|
|
509
|
+
return pieces.join("");
|
|
510
|
+
}
|
|
511
|
+
/**
|
|
512
|
+
* The INSTRUMENT identity a judge site declares up front (`RunEvaluation.
|
|
513
|
+
* judgeModel`, and the `judge_verdict` fallback): the single judge model, or
|
|
514
|
+
* every panelist joined with `+` in declaration order. Two different panels
|
|
515
|
+
* are two different instruments, so a per-arm quality lineage keyed on this
|
|
516
|
+
* string re-baselines instead of averaging them (§6.3 item 4).
|
|
517
|
+
*/
|
|
518
|
+
export function judgeInstrumentId(panel, fallbackModel) {
|
|
519
|
+
if (panel.judges !== undefined && panel.judges.length > 0)
|
|
520
|
+
return panel.judges.join("+");
|
|
521
|
+
return panel.model ?? fallbackModel;
|
|
522
|
+
}
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
import type { ProviderAdapter, ProviderId } from "@crewhaus/adapter-anthropic";
|
|
2
|
+
import type { IrModelPoolStrategy } from "@crewhaus/ir";
|
|
3
|
+
import { type RunContext } from "@crewhaus/run-context";
|
|
4
|
+
import { type CommitteeSideCall, type GuideSideCall, type HybridSideCalls, type RunChatLoopOptions, type ShadowSideCall } from "@crewhaus/runtime-core";
|
|
5
|
+
import { type ModelRole, type ModelUsage } from "@crewhaus/trace-event-bus";
|
|
6
|
+
/** The SDK message shape, taken from runtime-core's option so this package
|
|
7
|
+
* needs no direct SDK dependency. */
|
|
8
|
+
type MessageParam = NonNullable<RunChatLoopOptions["seedMessages"]>[number];
|
|
9
|
+
/**
|
|
10
|
+
* The slice of a pool the side calls read — structural over `IrModelPool`
|
|
11
|
+
* so the crew orchestrator's `RoleModelPool` (the runtime's widened pool
|
|
12
|
+
* type) and the IR pool both fit without a cast.
|
|
13
|
+
*/
|
|
14
|
+
export type SideCallPool = {
|
|
15
|
+
readonly candidates: ReadonlyArray<{
|
|
16
|
+
readonly model: string;
|
|
17
|
+
readonly tags: readonly string[];
|
|
18
|
+
readonly profile?: string;
|
|
19
|
+
readonly enabled?: false;
|
|
20
|
+
}>;
|
|
21
|
+
readonly routing?: {
|
|
22
|
+
readonly strongTag?: string;
|
|
23
|
+
};
|
|
24
|
+
readonly strategy?: IrModelPoolStrategy;
|
|
25
|
+
};
|
|
26
|
+
/** The slice of `WireModelsDeps` the side calls read (kept structural so
|
|
27
|
+
* index.ts stays the one place the deps type is declared). */
|
|
28
|
+
export type SideCallDeps = {
|
|
29
|
+
readonly sessionName?: string;
|
|
30
|
+
/**
|
|
31
|
+
* Test injection — pre-built adapters for every nested side-call target
|
|
32
|
+
* (consult, guide, shadow, committee members and tie-breaker), keyed by
|
|
33
|
+
* SPEC model string. Production callers leave it undefined: the nested
|
|
34
|
+
* loop resolves the target through the model-router.
|
|
35
|
+
*/
|
|
36
|
+
readonly _consultAdapters?: ReadonlyMap<string, ProviderAdapter>;
|
|
37
|
+
/** Test injection — the shadow's and committee's judge adapter. */
|
|
38
|
+
readonly _judgeAdapter?: ProviderAdapter;
|
|
39
|
+
};
|
|
40
|
+
export type NestedTarget = {
|
|
41
|
+
readonly modelString: string;
|
|
42
|
+
readonly profile?: string;
|
|
43
|
+
};
|
|
44
|
+
export type NestedSingleTurnArgs = {
|
|
45
|
+
readonly target: NestedTarget;
|
|
46
|
+
readonly instructions: string;
|
|
47
|
+
readonly seedMessages: ReadonlyArray<MessageParam>;
|
|
48
|
+
readonly role: ModelRole;
|
|
49
|
+
readonly stage?: string;
|
|
50
|
+
/** The parent run's context; a fresh child is minted when absent. */
|
|
51
|
+
readonly parent?: RunContext;
|
|
52
|
+
readonly signal?: AbortSignal;
|
|
53
|
+
readonly maxTokens?: number;
|
|
54
|
+
readonly sessionTarget: string;
|
|
55
|
+
readonly deps: SideCallDeps;
|
|
56
|
+
};
|
|
57
|
+
export type NestedSingleTurnResult = {
|
|
58
|
+
readonly text: string;
|
|
59
|
+
/** Wire model id that served (the spec string until the first response). */
|
|
60
|
+
readonly model: string;
|
|
61
|
+
readonly provider: ProviderId;
|
|
62
|
+
readonly usage: ModelUsage;
|
|
63
|
+
readonly latencyMs: number;
|
|
64
|
+
/** Priced from the static table; undefined off-table. */
|
|
65
|
+
readonly costUsd?: number;
|
|
66
|
+
};
|
|
67
|
+
/**
|
|
68
|
+
* THE nested single-turn side call (plan §7.5 / §7.6). One tool-less turn on
|
|
69
|
+
* the target through `runChatLoop` — never `adapter.stream` — on a child run
|
|
70
|
+
* context whose bus inherits the parent's trace and whose model events are
|
|
71
|
+
* re-published on the parent bus under the parent's envelope with `role` /
|
|
72
|
+
* `stage`. Persists nothing of its own (`persistSession: false`, §16 Q6).
|
|
73
|
+
*/
|
|
74
|
+
export declare function runNestedSingleTurn(args: NestedSingleTurnArgs): Promise<NestedSingleTurnResult>;
|
|
75
|
+
/**
|
|
76
|
+
* The transcript a tool-less side call can be handed: text blocks only
|
|
77
|
+
* (a `tool_use` / `tool_result` pair means nothing to a model that has no
|
|
78
|
+
* tools and would orphan under a different toolset), consecutive same-role
|
|
79
|
+
* messages merged, a leading assistant message dropped, ending on a user
|
|
80
|
+
* message. Returns `[]` when no user text survives.
|
|
81
|
+
*/
|
|
82
|
+
export declare function textOnlyTranscript(messages: ReadonlyArray<MessageParam>): MessageParam[];
|
|
83
|
+
/** The latest user text in a transcript (the turn's input), if any. */
|
|
84
|
+
export declare function latestUserText(messages: ReadonlyArray<MessageParam>): string | undefined;
|
|
85
|
+
/** The guide model's system prompt — it plans; it never answers the user. */
|
|
86
|
+
export declare const GUIDE_INSTRUCTIONS = "You are the guide for another model that will actually answer the user. Read the executor's instructions and the conversation so far, then write concise guidance for the executor's next answer: the key steps or plan, the pitfalls to avoid, and what a good answer must contain. Write in the second person to the executor. Do not answer the user yourself, do not address the user, and do not include anything that is not guidance.";
|
|
87
|
+
export declare const DEFAULT_GUIDE_MAX_TOKENS = 400;
|
|
88
|
+
export declare function buildGuideSideCall(pool: SideCallPool, deps: SideCallDeps): GuideSideCall | undefined;
|
|
89
|
+
export declare const DEFAULT_SHADOW_SAMPLE_RATE = 0.1;
|
|
90
|
+
export declare function buildShadowSideCall(pool: SideCallPool, deps: SideCallDeps): ShadowSideCall | undefined;
|
|
91
|
+
export declare function buildCommitteeSideCall(pool: SideCallPool, deps: SideCallDeps): CommitteeSideCall | undefined;
|
|
92
|
+
/** True when the pool's strategy declares a guide, a shadow or a committee. */
|
|
93
|
+
export declare function hasSideCallStrategy(pool: SideCallPool | undefined): boolean;
|
|
94
|
+
/**
|
|
95
|
+
* Build the `sideCalls` option for a pool. Spread-return-`{}`: a pool whose
|
|
96
|
+
* strategy declares none of the three yields `{}`, so every pre-0.6.0 loop
|
|
97
|
+
* call stays byte-identical. Called once per RUN (the guide's budget cap is
|
|
98
|
+
* per run), never cached across runs.
|
|
99
|
+
*/
|
|
100
|
+
export declare function wireSideCalls(pool: SideCallPool, deps?: SideCallDeps): {
|
|
101
|
+
readonly sideCalls?: HybridSideCalls;
|
|
102
|
+
};
|
|
103
|
+
export {};
|