@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.
@@ -0,0 +1,545 @@
1
+ /**
2
+ * @crewhaus/model-service — the composition root for model routing
3
+ * (0.6.0 plan §2 stance 4, module brief 308; the `wireMemory` precedent in
4
+ * `@crewhaus/memory-service`).
5
+ *
6
+ * const routing = wireModels(modelWiringFragmentFromIr(ir.agent), {});
7
+ * await runChatLoop({ model, instructions, tools, ...routing });
8
+ *
9
+ * ONE call turns the lowered model-routing IR into the `RunChatLoopOptions`
10
+ * fragment runtime-core consumes. Before this package, ten emitters and two
11
+ * interpreter sites each hand-mirrored the same four-field rendering
12
+ * (`modelFallbacks` / `circuitBreaker` / `modelTiers` / `modelPool`) with a
13
+ * "keep the N copies in sync" comment; the copies had already drifted (the
14
+ * single-turn interpreter path dropped `circuitBreaker` under `--model`, the
15
+ * REPL path kept it). Every later routing feature — per-candidate adapters,
16
+ * chains and breakers, the scoreboard and priors, the PolicyRouter with rules
17
+ * / classifier / eligibility, the per-candidate plan table, judge metering,
18
+ * the guide / shadow / committee closures, the Consult / Escalate tools —
19
+ * lands HERE (PRs 8b, 9a–9d, 10), never in codegen. runtime-core keeps
20
+ * receiving injected closures and stays store-free.
21
+ *
22
+ * PR 8a (this file's first cut) WRAPPED what the emitters already rendered,
23
+ * byte-identically: {@link renderModelWiringFields} reproduces the legacy
24
+ * emitter strings exactly so every existing bundle is unchanged, and
25
+ * `wireModels` and the renderer are pinned equal by test (`index.test.ts`):
26
+ * evaluating the rendered fields yields the same object `wireModels` returns.
27
+ *
28
+ * PR 8b adds the first runtime CONSTRUCTION: under
29
+ * `model_pool.strategy.model_directed: true` the root builds the `Consult`
30
+ * and `Escalate` tools from `@crewhaus/tool-consult` and returns them as the
31
+ * `hybridTools` / `escalation` options (plan §7.2.4, §7.5). The Consult
32
+ * runner is a nested single-turn `runChatLoop` on the allowlisted roster
33
+ * sibling — through `runChatLoop`, never `adapter.stream`, so
34
+ * `model_request` / `model_response`, `cost_accrual` and budget metering all
35
+ * hold — minted with its OWN child `RunContext` and child `TraceEventBus`
36
+ * (the side-call isolation contract, §7.6) whose model events are re-published
37
+ * on the parent bus so the parent's meter counts them. The reply is classified
38
+ * at TrustOrigin "consult" (`classifyBoundary` + `tagContent`) INSIDE the tool
39
+ * package, exactly once; this root only builds the call. A pool without the
40
+ * strategy key, or any `--model` override, wires no hybrid tool — the
41
+ * pre-0.6.0 fragment stays byte-identical.
42
+ *
43
+ * PR 9e closes the REACH gap. Everything above is a runtime CLOSURE, so it
44
+ * cannot ride the `JSON.stringify(modelPool)` blob every emitter writes —
45
+ * which is why, until 9e, a compiled bundle had the pool but none of the
46
+ * hybrid behaviour: no Consult / Escalate, a `policy: classifier` pool
47
+ * routing heuristically with `reason: "classifier failed: no classifier
48
+ * wired"`, and no guide / shadow / committee outside the workflow / graph /
49
+ * crew hosts. The fix is {@link wireHybrid} and its codegen twin
50
+ * {@link renderHybridWiringFields}: an emitter whose lowered pool declares
51
+ * `strategy.model_directed`, `policy: classifier` or
52
+ * `strategy.{guide,shadow,committee}` renders
53
+ * `...wireHybrid(<pool blob>, { sessionName })` beside the literal routing
54
+ * fields and imports THIS package at boot, so the bundle constructs exactly
55
+ * the closures the interpreter constructs. A bundle importing this package
56
+ * is not a cycle: the emitted bundle is a CONSUMER of the workspace, not a
57
+ * member of it (the workflow and graph emitters have imported it for the
58
+ * side calls since 9d, and the emitted `dist/package.json` lists it because
59
+ * the manifest is collected from the bundle's own import strings).
60
+ *
61
+ * Absent = byte-identical: a pool that declares none of the three renders
62
+ * nothing and imports nothing, so every pre-0.6.0 bundle is unchanged.
63
+ *
64
+ * PR 9f finishes the reach on the remaining four pool-bearing shapes
65
+ * (pipeline, research, batch, browser) and moves the plan's per-shape
66
+ * acceptance table INTO this package as {@link HYBRID_FAMILIES_BY_SHAPE} —
67
+ * §11.3 in code, so the published matrix and the emitters cannot drift. Each
68
+ * of the three closure FAMILIES ({@link HybridWiringFamily}) is wired per
69
+ * shape: every pool-bearing shape gets `classifier` and `sideCalls`, and
70
+ * every one but `pipeline` also gets `modelDirected`, because §11.3 marks
71
+ * `Consult / Escalate` `—` there. That cell is the PLAN's decision, not a
72
+ * property of the shape — see {@link HYBRID_FAMILIES_BY_SHAPE}.
73
+ * {@link wireHybrid} and {@link renderHybridWiringFields} both
74
+ * take that family set, so the interpreter, the bundle and the compiler's
75
+ * warning all read one table.
76
+ *
77
+ * PR 9a (the per-candidate plan table) therefore builds the plans INSIDE
78
+ * runtime-core, at boot, from the widened `modelPool` option this root hands
79
+ * it — `@crewhaus/model-plan`'s pure `buildRequestParams` /
80
+ * `buildAdvertisement` do the derivation, runtime-core owns the selection —
81
+ * rather than constructing them here: the same blob a bundle renders and the
82
+ * interpreter spreads yields the same plans on both paths, which keeps the
83
+ * one-code-path contract without a boot-time import. What this root DOES add
84
+ * in 9a is the emit-side scope twin {@link scopedModelWiringFragment}.
85
+ *
86
+ * PR 9b adds the second runtime construction: under `policy: classifier`
87
+ * with a `classifier:` block the root builds the {@link RouteClassifierFn}
88
+ * (`routeClassifier`) runtime-core's `preRoute` phase calls each turn — see
89
+ * {@link buildRouteClassifier}. Like the hybrid tools it reaches the
90
+ * interpreter through `loop-contract.ts` and — since PR 9e — a compiled
91
+ * bundle through {@link renderHybridWiringFields}.
92
+ *
93
+ * `wireModels` is per RUN, not per process: the escalation latch it returns
94
+ * is bounded "per run", so a host that serves many runs from one process
95
+ * (`crewhaus serve`) calls it once per run — never caches the fragment.
96
+ */
97
+ import type { ProviderAdapter } from "@crewhaus/adapter-anthropic";
98
+ import type { IrCircuitBreaker, IrModelParams, IrModelPool, IrModelPoolClassifier, IrModelTiers, IrSubAgentDefinition } from "@crewhaus/ir";
99
+ import type { HybridSideCalls, RouteClassifierFn } from "@crewhaus/runtime-core";
100
+ import type { RegisteredTool } from "@crewhaus/tool-catalog";
101
+ import { type ConsultRunner, type EscalationLatch } from "@crewhaus/tool-consult";
102
+ import { type SideCallPool } from "./side-calls";
103
+ export { DEFAULT_GUIDE_MAX_TOKENS, DEFAULT_SHADOW_SAMPLE_RATE, GUIDE_INSTRUCTIONS, type NestedSingleTurnArgs, type NestedSingleTurnResult, type NestedTarget, type SideCallDeps, type SideCallPool, buildCommitteeSideCall, buildGuideSideCall, buildShadowSideCall, hasSideCallStrategy, latestUserText, runNestedSingleTurn, textOnlyTranscript, wireSideCalls, } from "./side-calls";
104
+ /**
105
+ * The model-routing slice of ONE lowered model-bearing block (an `IrV0`
106
+ * agent, a workflow step, a crew role, a graph node, a pooled single-agent
107
+ * block). Every IR block that carries routing already satisfies this shape
108
+ * structurally, so emitters and the interpreter pass the block itself —
109
+ * typed IR in (Pillar 1), one call out. Every key is optional and
110
+ * absent-when-omitted: an empty fragment wires NOTHING.
111
+ *
112
+ * `modelPool` is the whole `IrModelPool`, not an allow-list of its keys: the
113
+ * pool travels to runtime as ONE blob (`JSON.stringify(modelPool)` in a
114
+ * bundle, the object itself in the interpreter), so every per-candidate
115
+ * setting, rule, strategy and reward key the compiler lowers reaches
116
+ * `runChatLoop` verbatim. The `index.test.ts` "one new key per level"
117
+ * fixture pins that nothing between the IR and the option object drops a
118
+ * key (plan §17).
119
+ */
120
+ export type ModelWiringFragment = {
121
+ /** Ordered fallback model strings (spec `model_fallbacks`). */
122
+ readonly modelFallbacks?: readonly string[];
123
+ /** Breaker tuning (spec `circuit_breaker`) — with or without fallbacks. */
124
+ readonly circuitBreaker?: IrCircuitBreaker;
125
+ /** The two-tier turn-difficulty router (spec `model_tiers`). */
126
+ readonly modelTiers?: IrModelTiers;
127
+ /** The N-candidate pool (spec `model_pool`), carried whole. */
128
+ readonly modelPool?: IrModelPool;
129
+ };
130
+ /**
131
+ * The `runChatLoop(...)` options fragment `wireModels` returns — the four
132
+ * routing options under runtime-core's own option names, mirrored
133
+ * STRUCTURALLY from the IR types, plus (PR 8b) the two hybrid-tool options
134
+ * the root constructs under `strategy.model_directed`. Since PR 8b this
135
+ * package DOES depend on `@crewhaus/runtime-core` (the Consult runner is a
136
+ * nested `runChatLoop`), so the whole type is pinned assignable to
137
+ * `Pick<RunChatLoopOptions, keyof ModelWiringRunOptions>` right here
138
+ * ({@link _ModelWiringRunOptionsPin}) — a rename or reshaping in runtime-core
139
+ * fails `tsc -b` in this package, and `apps/cli/src/loop-contract.ts`'s
140
+ * `modelRoutingRunOptions` carries the same pin at the interpreter seam (the
141
+ * `LoopContractRunOptions` discipline). Later PRs widen this type
142
+ * (`_poolAdapters`, `_scoreboard`, …) as the root constructs more.
143
+ */
144
+ export type ModelWiringRunOptions = {
145
+ readonly modelFallbacks?: readonly string[];
146
+ readonly circuitBreaker?: IrCircuitBreaker;
147
+ readonly modelTiers?: IrModelTiers;
148
+ readonly modelPool?: IrModelPool;
149
+ /**
150
+ * 0.6.0 §7.2.4 — `Consult` + `Escalate`, present only when the (non-
151
+ * overridden) pool declares `strategy.model_directed: true`. runtime-core
152
+ * appends them to the effective tool list (first-party wins a collision).
153
+ */
154
+ readonly hybridTools?: ReadonlyArray<RegisteredTool>;
155
+ /** The `Escalate` tool's latch — the loop consumes it at its next model call. */
156
+ readonly escalation?: EscalationLatch;
157
+ /**
158
+ * 0.6.0 §7.2.3 (PR 9b) — the `policy: classifier` label call, present only
159
+ * when the (non-overridden) pool declares `policy: classifier` AND a
160
+ * `classifier:` block. runtime-core's `preRoute` phase calls it with the
161
+ * latest human user text and falls back to the heuristic policy when it
162
+ * throws. Built over `@crewhaus/eval-judge`'s `classifyRouteLabel`.
163
+ */
164
+ readonly routeClassifier?: RouteClassifierFn;
165
+ /**
166
+ * 0.6.0 §7.4 / §7.6 / §7.8 (PR 9d) — the guide / shadow / committee
167
+ * closures, present only when the (non-overridden) pool's `strategy`
168
+ * declares one of the three. Built by {@link wireSideCalls}; runtime-core
169
+ * owns their lifecycle.
170
+ */
171
+ readonly sideCalls?: HybridSideCalls;
172
+ };
173
+ /**
174
+ * The runtime dependencies `wireModels` composes over: the interpreter's
175
+ * `--model` override, the session facts the nested consult loops persist
176
+ * under, and the test injection seams for the consult side call. The
177
+ * adapters, scoreboard root, bus and tool catalog join as the root grows.
178
+ */
179
+ export type WireModelsDeps = {
180
+ /**
181
+ * A caller-forced primary model (the interpreter's `--model` flag). A
182
+ * flag-forced model is an explicit routing decision, and the spec's
183
+ * fallback chain, tiers and pool were authored against the SPEC's primary
184
+ * — so they are dropped (and with the pool, its hybrid tools).
185
+ * `circuitBreaker` is kept: declared alone it breaker-wraps whichever
186
+ * single primary serves, override or not.
187
+ */
188
+ readonly modelOverride?: string;
189
+ /**
190
+ * The harness / spec name the nested consult loops label their sessions
191
+ * with (`<name>:consult`). Defaults to `"consult"`.
192
+ */
193
+ readonly sessionName?: string;
194
+ /**
195
+ * Retained for callers that passed it in 8b; since PR 9d the nested side
196
+ * calls run with `persistSession: false` (plan §16 Q6) and write NO
197
+ * session or event-log file of their own — their spend and stages are
198
+ * re-published on the parent bus and land in the parent's log — so this
199
+ * root is no longer read.
200
+ */
201
+ readonly sessionRootDir?: string;
202
+ /**
203
+ * Test injection — pre-built adapters for every nested side-call target
204
+ * (consult, guide, shadow, committee members and tie-breaker), keyed by
205
+ * SPEC model string (the `_poolAdapters` contract), so a side call runs
206
+ * offline through `runChatLoop({ _adapter })`. Production callers leave it
207
+ * undefined: the nested loop resolves the target through the model-router.
208
+ */
209
+ readonly _consultAdapters?: ReadonlyMap<string, ProviderAdapter>;
210
+ /** Test injection — the shadow's and committee's judge adapter. */
211
+ readonly _judgeAdapter?: ProviderAdapter;
212
+ /**
213
+ * Test injection — replace the nested-`runChatLoop` runner entirely with a
214
+ * scripted one. Production callers leave it undefined.
215
+ */
216
+ readonly _consultRunner?: ConsultRunner;
217
+ /**
218
+ * Test injection — a pre-built adapter for the `policy: classifier` label
219
+ * call, so it runs offline. Production callers leave it undefined: the
220
+ * classifier model resolves through the model-router on first call.
221
+ */
222
+ readonly _classifierAdapter?: ProviderAdapter;
223
+ /**
224
+ * 0.6.0 §11.3 (PR 9f) — the closure families the HOST may construct. Omit
225
+ * (every interpreter caller) and {@link wireHybrid} builds every family the
226
+ * pool declares. An emitter passes its shape's row from
227
+ * {@link HYBRID_FAMILIES_BY_SHAPE} so a shape the matrix marks `—` for a
228
+ * family constructs nothing for it — today that is `pipeline` and
229
+ * `modelDirected`. The list is rendered verbatim into the bundle, so the
230
+ * bundle and the interpreter apply the SAME restriction.
231
+ */
232
+ readonly hybridFamilies?: readonly HybridWiringFamily[];
233
+ };
234
+ /** The routing keys, in the order every emitter and the interpreter have
235
+ * always written them. `wireModels` returns them in this order and
236
+ * {@link renderModelWiringFields} renders them in this order. */
237
+ export declare const MODEL_WIRING_KEYS: readonly ["modelFallbacks", "circuitBreaker", "modelTiers", "modelPool"];
238
+ /** The hybrid-tool keys `wireModels` appends after {@link MODEL_WIRING_KEYS}
239
+ * when the pool declares `strategy.model_directed: true`. Never rendered by
240
+ * {@link renderModelWiringFields}: they are runtime constructions, carried
241
+ * into a bundle by {@link renderHybridWiringFields}. */
242
+ export declare const HYBRID_WIRING_KEYS: readonly ["hybridTools", "escalation"];
243
+ /** 0.6.0 §7.2.3 — the key `wireModels` appends after the hybrid keys when
244
+ * the pool declares `policy: classifier` with a `classifier:` block. A
245
+ * runtime construction, never rendered by {@link renderModelWiringFields}. */
246
+ export declare const CLASSIFIER_WIRING_KEYS: readonly ["routeClassifier"];
247
+ /** The side-call key `wireModels` appends LAST when the pool's strategy
248
+ * declares a guide, a shadow or a committee (PR 9d). A runtime
249
+ * construction: rendered into a bundle by
250
+ * {@link renderHybridWiringFields}, never by
251
+ * {@link renderModelWiringFields}. */
252
+ export declare const SIDE_CALL_WIRING_KEYS: readonly ["sideCalls"];
253
+ /** Every key {@link wireHybrid} can add, in the order it adds them — the
254
+ * runtime constructions {@link renderModelWiringFields} never renders and
255
+ * {@link renderHybridWiringFields} carries into a bundle instead. */
256
+ export declare const HYBRID_CONSTRUCTION_KEYS: readonly ["hybridTools", "escalation", "routeClassifier", "sideCalls"];
257
+ /**
258
+ * Pick the routing slice out of a lowered block EXACTLY as the retired
259
+ * per-emitter renderers read it — only declared keys are carried, and an
260
+ * EMPTY `modelFallbacks` array is treated as absent (the emitters' and the
261
+ * interpreter's `length > 0` guard), so a spec that declares no chain wires
262
+ * no chain. Values are carried by reference, never copied or re-shaped:
263
+ * the pool blob's key order is a byte contract (`model` then `tags` first,
264
+ * every 0.6.0 key after — the compiler's key-order guard).
265
+ */
266
+ export declare function modelWiringFragmentFromIr(block: ModelWiringFragment): ModelWiringFragment;
267
+ /**
268
+ * 0.6.0 §7.9 (PR 9a) — the emit-side twin of `@crewhaus/crew-orchestrator`'s
269
+ * `scopeRolePool`: a block's fragment with its pool's `scope` defaulted to
270
+ * the host's name (a workflow step, a graph node) when the spec pinned none.
271
+ * The compiler deliberately leaves `scope` unstamped at lower time (the IR
272
+ * blob is what README / loop projections read), so the emitter that knows
273
+ * which step or node a `runChatLoop` call belongs to stamps it where the
274
+ * loop options are assembled — runtime-core stamps the result on
275
+ * `model_route.scope`, and the routing store keys arms by it from PR 10 on.
276
+ * A declared `scope` always wins; a fragment without a pool is returned
277
+ * untouched (object identity kept), so un-pooled steps and nodes stay
278
+ * byte-identical.
279
+ */
280
+ export declare function scopedModelWiringFragment(block: ModelWiringFragment, scope: string): ModelWiringFragment;
281
+ /**
282
+ * THE one stable call. Returns the spread-ready `RunChatLoopOptions` slice
283
+ * for a fragment: every key present only when the fragment declares it
284
+ * (spread-return-`{}` discipline — an empty fragment yields `{}` and the
285
+ * runtime defaults stay authoritative), values by reference, keys in
286
+ * {@link MODEL_WIRING_KEYS} order, then {@link HYBRID_WIRING_KEYS} when the
287
+ * pool declares `strategy.model_directed: true`.
288
+ *
289
+ * Still synchronous. The runtime resolves candidate adapters, opens the
290
+ * scoreboard and builds the PolicyRouter inside `runChatLoop` from the four
291
+ * routing options exactly as it did when each emitter rendered them by hand
292
+ * (moving that construction here is PR 9a/10's job). What this root DOES
293
+ * construct today is the model-directed pair: the `Consult` tool over a
294
+ * nested-`runChatLoop` runner on the roster, and the `Escalate` tool with the
295
+ * latch the loop consumes — see {@link wireModelDirected}.
296
+ */
297
+ export declare function wireModels(fragment: ModelWiringFragment, deps: WireModelsDeps): ModelWiringRunOptions;
298
+ /**
299
+ * The pool slice {@link wireHybrid} reads — structural over `IrModelPool`, so
300
+ * the crew orchestrator's widened `RoleModelPool` and the IR pool both fit
301
+ * without a cast (the {@link SideCallPool} discipline, extended with the two
302
+ * keys the classifier and the model-directed pair need).
303
+ */
304
+ export type HybridWiringPool = SideCallPool & {
305
+ readonly policy?: string;
306
+ readonly classifier?: IrModelPoolClassifier;
307
+ };
308
+ /** The slice of {@link ModelWiringRunOptions} {@link wireHybrid} constructs —
309
+ * every key a runtime CLOSURE, none of them expressible in the pool blob. */
310
+ export type HybridWiringRunOptions = Pick<ModelWiringRunOptions, "hybridTools" | "escalation" | "routeClassifier" | "sideCalls">;
311
+ /**
312
+ * 0.6.0 §11.3 (PR 9f) — the three CLOSURE families {@link wireHybrid} can
313
+ * construct, named so a host can decline one. `modelDirected` is the
314
+ * `Consult` + `Escalate` pair (§7.2.4, §7.5), `classifier` the `policy:
315
+ * classifier` label call (§7.2.3), `sideCalls` the guide / shadow / committee
316
+ * lanes (§7.4, §7.6, §7.8).
317
+ */
318
+ export type HybridWiringFamily = "modelDirected" | "classifier" | "sideCalls";
319
+ /** Every family, in the order {@link wireHybrid} constructs them. The default
320
+ * when a caller passes no `hybridFamilies` — the interpreter's posture. */
321
+ export declare const ALL_HYBRID_WIRING_FAMILIES: readonly HybridWiringFamily[];
322
+ /** The fourteen compile targets, as the spec's `target:` literal spells them.
323
+ * Kept structurally identical to `@crewhaus/spec`'s `Spec["target"]` (the
324
+ * compiler pins the two unions equal) without taking a dependency on it. */
325
+ export type HybridWiringShape = "cli" | "workflow" | "channel" | "graph" | "managed" | "pipeline" | "crew" | "research" | "batch" | "voice" | "browser" | "eval" | "onchain" | "onchain-game";
326
+ /**
327
+ * **Plan §11.3, in code.** Shape → the closure families that shape's COMPILED
328
+ * bundle constructs, which since PR 9f is also exactly what its emitter
329
+ * renders and what the compiler declines to warn about. The table is
330
+ * published verbatim in crewhaus/docs `COMPILER-ARCHITECTURE.md` and the
331
+ * book's appendix D and printed per-shape by `models explain`, so it lives
332
+ * HERE — one table three consumers read — rather than being restated at each
333
+ * seam and drifting from the emitters (which is precisely what PR 9e's known
334
+ * shortfall was).
335
+ *
336
+ * Reading the matrix rows:
337
+ *
338
+ * - The ten pool-bearing shapes take `classifier` and `sideCalls`. `committee`
339
+ * is a `sideCalls` member but the strict schema already refuses it anywhere
340
+ * §11.3 marks it `—` (`SpecRoutedHost.committee`), so no shape needs to
341
+ * decline the family for it.
342
+ * - `pipeline` declines `modelDirected`: §11.3 marks `Consult / Escalate` `—`
343
+ * on that row, and the table is the only ground for it. Mechanically the
344
+ * shape could host the pair: {@link wireModelDirected} builds Consult /
345
+ * Escalate from the POOL roster and returns them as ADDITIVE `hybridTools`
346
+ * — it narrows no shape toolset (the consulted model gets none at all), and
347
+ * the emitted pipeline bundle registers a tool catalog of its own.
348
+ * `toolLess` in `@crewhaus/spec` says only that the pipeline SPEC has no
349
+ * `tools:` key, which is why a per-model `tools` list is refused there — a
350
+ * different fact. So this row is a plan decision open to revision, not a
351
+ * shape fact, and the compiler's warning says so.
352
+ * - The four shapes with no `model_pool` block at all (`voice`, `eval`,
353
+ * `onchain`, `onchain-game` — `—` in the pool column) take no family; the
354
+ * strict schema refuses the block before any of this is reached.
355
+ */
356
+ export declare const HYBRID_FAMILIES_BY_SHAPE: Readonly<Record<HybridWiringShape, readonly HybridWiringFamily[]>>;
357
+ /** The §11.3 row for a shape — {@link HYBRID_FAMILIES_BY_SHAPE} with a total
358
+ * signature, so a caller holding a widened `string` gets `[]` (wires
359
+ * nothing) rather than `undefined`. */
360
+ export declare function hybridWiringFamiliesForShape(shape: string): readonly HybridWiringFamily[];
361
+ /** Does a pool declare the given closure family? The per-family half of
362
+ * {@link poolNeedsHybridWiring}, so the gate, the builder and the renderer
363
+ * all ask one question. */
364
+ export declare function poolDeclaresHybridFamily(pool: HybridWiringPool, family: HybridWiringFamily): boolean;
365
+ /**
366
+ * True when a pool declares at least one closure-shaped feature the HOST can
367
+ * construct: `strategy.model_directed` (Consult + Escalate), `policy:
368
+ * classifier` with a `classifier:` block, or `strategy.{guide,shadow,
369
+ * committee}`. The gate every emitter's codegen and import both key on, so
370
+ * "wires nothing" and "renders nothing" can never disagree.
371
+ *
372
+ * `families` narrows the question to the shape's §11.3 row (PR 9f): a
373
+ * `pipeline` pool that declares ONLY `strategy.model_directed` needs no
374
+ * wiring, because that shape constructs no model-directed pair — so it also
375
+ * renders no call and imports nothing, and the compiler warns on the key
376
+ * instead. Omitted, every family counts (the interpreter's posture).
377
+ */
378
+ export declare function poolNeedsHybridWiring(pool: HybridWiringPool | undefined, families?: readonly HybridWiringFamily[]): boolean;
379
+ /**
380
+ * 0.6.0 §7.2.3 / §7.2.4 / §7.4 / §7.6 / §7.8 (PR 9e) — build every runtime
381
+ * closure a pool declares, in ONE call: the model-directed pair, the route
382
+ * classifier, and the guide / shadow / committee side calls. Spread-return-
383
+ * `{}` — a pool declaring none of them yields no keys at all.
384
+ *
385
+ * This is the whole of what `wireModels` appends beyond the four literal
386
+ * routing fields, factored out precisely so a compiled bundle can call it
387
+ * directly: {@link renderHybridWiringFields} renders
388
+ * `...wireHybrid(<pool blob>, { sessionName })` into the generated
389
+ * `runChatLoop({...})`, and the interpreter reaches the same code through
390
+ * `wireModels`. One code path, not a mirror — pinned by test.
391
+ */
392
+ export declare function wireHybrid(pool: HybridWiringPool, deps: WireModelsDeps): HybridWiringRunOptions;
393
+ /**
394
+ * The codegen twin of {@link wireHybrid}: the spread field an emitter renders
395
+ * onto a pooled block's `runChatLoop({...})` (or a channel `createAgent`
396
+ * body) when the pool declares a closure-shaped feature —
397
+ * `\n<indent>...wireHybrid(<pool blob>, { sessionName: "…" }),` — so the
398
+ * bundle constructs the closures at boot through THIS package. `""` for every
399
+ * other pool, which is what keeps pre-0.6.0 bundles byte-identical: no field,
400
+ * and (because the emitter gates its import on the same
401
+ * {@link poolNeedsHybridWiring} predicate) no `@crewhaus/model-service`
402
+ * import either.
403
+ *
404
+ * The pool blob is the same `JSON.stringify` {@link renderModelWiringFields}
405
+ * already writes for `modelPool`, so the closures and the literal option are
406
+ * built from byte-identical config. `sessionName` is the harness name the
407
+ * nested side calls label their spend with.
408
+ *
409
+ * `families` (PR 9f) is the emitter's §11.3 row —
410
+ * {@link hybridWiringFamiliesForShape} for its own target. A shape that
411
+ * declines a family renders `hybridFamilies: [...]` into the call, so the
412
+ * BUNDLE applies the same restriction the interpreter would; a shape that
413
+ * hosts every family renders exactly the 9e text, which is what keeps the six
414
+ * emitters wired then byte-identical now.
415
+ */
416
+ export declare function renderHybridWiringFields(fragment: {
417
+ readonly modelPool?: HybridWiringPool;
418
+ }, indent: string, sessionName: string, families?: readonly HybridWiringFamily[]): string;
419
+ /** The import line a bundle carries when {@link renderHybridWiringFields}
420
+ * rendered a field. One constant so the ten emitters cannot drift. */
421
+ export declare const HYBRID_WIRING_IMPORT = "import { wireHybrid } from \"@crewhaus/model-service\";";
422
+ /**
423
+ * Build the {@link RouteClassifierFn} for a pool's `classifier:` block: one
424
+ * enum-constrained forced-tool call on the classifier model per turn
425
+ * (`@crewhaus/eval-judge`'s `classifyRouteLabel`), published on the RUN bus
426
+ * the loop hands in with `role: "classifier"` — so cost-tracker prices it,
427
+ * the budget meter counts it under `judge_share`, and the session mirror
428
+ * persists it. The labels are the block's own (`tag → description`); the
429
+ * loop re-validates the verdict against the pool's tags. Any throw
430
+ * propagates: runtime-core's `preRoute` turns it into the heuristic fallback
431
+ * with `reason: "classifier failed"`. The model resolves through the
432
+ * model-router on first call unless a test injects `_classifierAdapter`.
433
+ */
434
+ export declare function buildRouteClassifier(classifier: NonNullable<IrModelPool["classifier"]>, deps: WireModelsDeps): RouteClassifierFn;
435
+ /**
436
+ * Build the `Consult` / `Escalate` pair for a pool that declares
437
+ * `strategy.model_directed: true`. The roster is the pool's ENABLED
438
+ * candidates; the escalation target is `strategy.cascade.escalateTo`
439
+ * resolved against the roster (a tag, profile or model string), else the
440
+ * strongest candidate (first `routing.strongTag`-tagged, else the last
441
+ * declared — the router's `escalation()` convention); `strategy.
442
+ * max_escalations` bounds the latch (default 1). A pool the compiler let
443
+ * through with no enabled candidate wires nothing rather than throwing.
444
+ */
445
+ export declare function wireModelDirected(pool: HybridWiringPool, deps: WireModelsDeps): Pick<ModelWiringRunOptions, "hybridTools" | "escalation">;
446
+ /** The consulted model's system prompt — it sees the question, nothing else. */
447
+ export declare 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.";
448
+ /**
449
+ * The Consult side call (plan §7.5 / §7.6) — one nested single-turn
450
+ * `runChatLoop` on the roster target through {@link runNestedSingleTurn}:
451
+ * own child `RunContext` and child bus (the singleTurn path mutates
452
+ * `runContext.turnNumber`, so a shared context would inject phantom turns),
453
+ * model events re-published on the PARENT bus under `role: "consult"` so the
454
+ * parent's cost-tracker prices them and its `budgetMeter` counts them under
455
+ * `judge_share`, and — since PR 9d, plan §16 Q6 — `persistSession: false`,
456
+ * so a consult no longer writes a child session file like a Task child.
457
+ *
458
+ * Returns the raw reply text — classification at TrustOrigin "consult"
459
+ * (`classifyBoundary` + `tagContent`) is the tool's job in
460
+ * `@crewhaus/tool-consult`, exactly once.
461
+ */
462
+ export declare function buildConsultRunner(deps: WireModelsDeps): ConsultRunner;
463
+ /**
464
+ * Render the routing fields of a fragment as object-literal source for a
465
+ * generated `runChatLoop({...})` (or crew `RoleDefinition`) call — the
466
+ * codegen twin of {@link wireModels}, byte-for-byte the string the ten
467
+ * emitters used to build by hand:
468
+ *
469
+ * `\n<indent>modelFallbacks: ["a", "b"],`
470
+ * `\n<indent>circuitBreaker: {"failureThreshold":2},`
471
+ * `\n<indent>modelTiers: {"fast":"…","default":"…"},`
472
+ * `\n<indent>modelPool: {"candidates":[…],"policy":"heuristic"},`
473
+ *
474
+ * Model strings pass through `escapeJsonString` (user-controlled spec values
475
+ * landing in generated source); the breaker / tiers / pool blocks are
476
+ * validated numbers, strings and closed-literal unions, safe to
477
+ * `JSON.stringify` as plain object literals. Returns `""` when the fragment
478
+ * declares nothing, so pre-existing bundles stay byte-identical. `indent`
479
+ * is the caller's field indentation (two spaces for target-cli's top-level
480
+ * call, eight inside a channel `createAgent` body, …).
481
+ *
482
+ * Evaluating the rendered fields yields exactly `wireModels(fragment, {})`
483
+ * — pinned in `index.test.ts` — which is what makes a compiled bundle and
484
+ * the `crewhaus run` interpreter one code path rather than a mirror.
485
+ */
486
+ export declare function renderModelWiringFields(fragment: ModelWiringFragment, indent: string): string;
487
+ /**
488
+ * 0.6.0 §7.7 — render one `IrSubAgentDefinition` as the single-line TS object
489
+ * literal the emitted `__subAgents` Map holds (a runtime
490
+ * `SubAgentDefinition`). ONE renderer for the three emitters that register
491
+ * the Task tool (cli, channel-bot, crew) — until PR 11 each carried a
492
+ * hand-mirrored copy with a "keep the three in sync" comment.
493
+ *
494
+ * Byte contract: the seven fields a 0.5.x definition has (`name`,
495
+ * `description`, `instructions`, `tools`, `model`, `permissions`,
496
+ * `inherit_bypass`) render exactly as the copies did, in that order; every
497
+ * 0.6.0 key (`modelProfile`, `overlay`, the params, the routing quartet,
498
+ * `budgetShare`, `inheritRouting`, `allowedProfiles`) is appended AFTER them and ONLY when
499
+ * present, so a spec whose sub-agents carry only today's fields emits a
500
+ * byte-identical bundle. The 0.6.0 keys use the runtime `SubAgentDefinition`
501
+ * names (camelCase, identical to the IR's) — `inherit_bypass` keeps its
502
+ * legacy spelling.
503
+ */
504
+ export declare function renderSubAgentDef(d: IrSubAgentDefinition): string;
505
+ /**
506
+ * The §6.2 panel knobs an in-loop judge site carries, as
507
+ * `IrEvaluationGrader` (an `llm_judge` grader) and `IrJudge` both
508
+ * declare them. One structural type so the three `renderEvaluation` copies
509
+ * and the two `JUDGE_GATE_HELPER` call sites render ONE fragment — the
510
+ * `renderSubAgentDef` precedent, for the same reason: five hand-mirrored
511
+ * copies of a field list drift.
512
+ */
513
+ export type JudgePanelIr = {
514
+ /** The single judge model (already resolved at lower time). */
515
+ readonly model?: string;
516
+ /** A panel of judge models; overrides `model` at the grader. */
517
+ readonly judges?: readonly string[];
518
+ readonly repeats?: number;
519
+ readonly temperature?: number;
520
+ readonly target?: "output" | "transcript";
521
+ /** 0.6.0 §4.2 — the judge profile's pinned request params. */
522
+ readonly params?: IrModelParams;
523
+ };
524
+ /** The import a judge site's bundle needs for {@link renderJudgePanelFields}. */
525
+ export declare const JUDGE_PANEL_IMPORT = "import { gradeWithJudgePanel, inLoopRunResult } from \"@crewhaus/eval-judge\";";
526
+ /**
527
+ * Render the panel fields of a `gradeWithJudgePanel({ … })` call, in a fixed
528
+ * order (`model`, `judges`, `repeats`, `temperature`, `target`, `params`)
529
+ * and ONLY when present — a spec that declares none of the §6.2 knobs emits
530
+ * exactly `model: "…"`, so its judge behaves as the single-model `judge()`
531
+ * call did before this seam existed.
532
+ *
533
+ * Model strings and the `target` literal pass through `escapeJsonString`
534
+ * (they are user-controlled spec values); `params` is a plain lowered object
535
+ * and renders through `JSON.stringify`.
536
+ */
537
+ export declare function renderJudgePanelFields(panel: JudgePanelIr, indent: string): string;
538
+ /**
539
+ * The INSTRUMENT identity a judge site declares up front (`RunEvaluation.
540
+ * judgeModel`, and the `judge_verdict` fallback): the single judge model, or
541
+ * every panelist joined with `+` in declaration order. Two different panels
542
+ * are two different instruments, so a per-arm quality lineage keyed on this
543
+ * string re-baselines instead of averaging them (§6.3 item 4).
544
+ */
545
+ export declare function judgeInstrumentId(panel: JudgePanelIr, fallbackModel: string): string;