@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.d.ts
ADDED
|
@@ -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;
|