@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/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 {};