@crewhaus/runtime-core 0.5.8 → 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/alert-watchdog.d.ts +53 -0
- package/dist/alert-watchdog.js +88 -7
- package/dist/ephemeral.d.ts +6 -0
- package/dist/ephemeral.js +88 -0
- package/dist/index.d.ts +795 -21
- package/dist/index.js +2573 -208
- package/dist/model-latency.d.ts +43 -0
- package/dist/model-latency.js +61 -0
- package/dist/observability.d.ts +47 -2
- package/dist/observability.js +104 -3
- package/dist/pre-route.d.ts +149 -0
- package/dist/pre-route.js +271 -0
- package/dist/slo-monitor.d.ts +20 -0
- package/dist/slo-monitor.js +45 -1
- package/package.json +42 -40
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 0.6.0 §7.9 — latency hygiene for the pool reward.
|
|
3
|
+
*
|
|
4
|
+
* The reward's latency term (`RouteObservation.latencyMs`) was measured as
|
|
5
|
+
* `now - t0Model` at the streaming fold, which spans every tool the
|
|
6
|
+
* streaming executor ran MID-STREAM (a tool dispatches the moment its
|
|
7
|
+
* `input_json` closes, while the model is still generating, and the drain
|
|
8
|
+
* after `message_stop` waits for the stragglers). A tool-heavy cheap arm was
|
|
9
|
+
* therefore penalised for latency it did not cause — and the learned policy
|
|
10
|
+
* learned the wrong thing from it. The non-streaming path never had the
|
|
11
|
+
* problem: tools run after the fold there.
|
|
12
|
+
*
|
|
13
|
+
* `createSpanUnionTracker` accumulates the UNION of overlapping spans (not
|
|
14
|
+
* their sum — up to `maxConcurrentTools` tools run at once, and summing would
|
|
15
|
+
* over-subtract), so `modelLatencyMs = wall - toolBusyMs` is the model's own
|
|
16
|
+
* time. Wall time is untouched: `model_response.durationMs` and `turn_end`
|
|
17
|
+
* keep measuring the turn the user waited for.
|
|
18
|
+
*
|
|
19
|
+
* Pure and clock-injectable so the union semantics are unit-tested with a
|
|
20
|
+
* fake clock — the runtime never asserts wall-clock timing.
|
|
21
|
+
*/
|
|
22
|
+
export type SpanUnionTracker = {
|
|
23
|
+
/** A span opened (a `runTool` dispatch started). */
|
|
24
|
+
readonly enter: () => void;
|
|
25
|
+
/** A span closed (that dispatch settled — success, error or abort alike). */
|
|
26
|
+
readonly exit: () => void;
|
|
27
|
+
/** Total time, in ms, during which AT LEAST ONE span was open. */
|
|
28
|
+
readonly busyMs: () => number;
|
|
29
|
+
};
|
|
30
|
+
/**
|
|
31
|
+
* Track the union of concurrent spans against `now` (defaults to
|
|
32
|
+
* `performance.now`). `busyMs()` may be read while spans are still open — it
|
|
33
|
+
* then includes the in-progress stretch up to `now()`.
|
|
34
|
+
*/
|
|
35
|
+
export declare function createSpanUnionTracker(now?: () => number): SpanUnionTracker;
|
|
36
|
+
/**
|
|
37
|
+
* The model's own latency for a streamed call: the wall span from request
|
|
38
|
+
* open (`t0Model`) to the fold (`nowMs`), minus the tool-busy union. Clamped
|
|
39
|
+
* at 0 so a tool span that (through clock skew) outlives the wall span can
|
|
40
|
+
* never yield a negative latency — which would be read as "infinitely fast"
|
|
41
|
+
* by the reward.
|
|
42
|
+
*/
|
|
43
|
+
export declare function modelLatencyMs(t0Model: number, nowMs: number, toolBusyMs: number): number;
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 0.6.0 §7.9 — latency hygiene for the pool reward.
|
|
3
|
+
*
|
|
4
|
+
* The reward's latency term (`RouteObservation.latencyMs`) was measured as
|
|
5
|
+
* `now - t0Model` at the streaming fold, which spans every tool the
|
|
6
|
+
* streaming executor ran MID-STREAM (a tool dispatches the moment its
|
|
7
|
+
* `input_json` closes, while the model is still generating, and the drain
|
|
8
|
+
* after `message_stop` waits for the stragglers). A tool-heavy cheap arm was
|
|
9
|
+
* therefore penalised for latency it did not cause — and the learned policy
|
|
10
|
+
* learned the wrong thing from it. The non-streaming path never had the
|
|
11
|
+
* problem: tools run after the fold there.
|
|
12
|
+
*
|
|
13
|
+
* `createSpanUnionTracker` accumulates the UNION of overlapping spans (not
|
|
14
|
+
* their sum — up to `maxConcurrentTools` tools run at once, and summing would
|
|
15
|
+
* over-subtract), so `modelLatencyMs = wall - toolBusyMs` is the model's own
|
|
16
|
+
* time. Wall time is untouched: `model_response.durationMs` and `turn_end`
|
|
17
|
+
* keep measuring the turn the user waited for.
|
|
18
|
+
*
|
|
19
|
+
* Pure and clock-injectable so the union semantics are unit-tested with a
|
|
20
|
+
* fake clock — the runtime never asserts wall-clock timing.
|
|
21
|
+
*/
|
|
22
|
+
/**
|
|
23
|
+
* Track the union of concurrent spans against `now` (defaults to
|
|
24
|
+
* `performance.now`). `busyMs()` may be read while spans are still open — it
|
|
25
|
+
* then includes the in-progress stretch up to `now()`.
|
|
26
|
+
*/
|
|
27
|
+
export function createSpanUnionTracker(now = () => performance.now()) {
|
|
28
|
+
let open = 0;
|
|
29
|
+
let openedAt;
|
|
30
|
+
let settled = 0;
|
|
31
|
+
return {
|
|
32
|
+
enter() {
|
|
33
|
+
if (open === 0)
|
|
34
|
+
openedAt = now();
|
|
35
|
+
open += 1;
|
|
36
|
+
},
|
|
37
|
+
exit() {
|
|
38
|
+
if (open === 0)
|
|
39
|
+
return; // tolerate an unmatched exit rather than go negative
|
|
40
|
+
open -= 1;
|
|
41
|
+
if (open === 0 && openedAt !== undefined) {
|
|
42
|
+
settled += Math.max(0, now() - openedAt);
|
|
43
|
+
openedAt = undefined;
|
|
44
|
+
}
|
|
45
|
+
},
|
|
46
|
+
busyMs() {
|
|
47
|
+
const live = open > 0 && openedAt !== undefined ? Math.max(0, now() - openedAt) : 0;
|
|
48
|
+
return settled + live;
|
|
49
|
+
},
|
|
50
|
+
};
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* The model's own latency for a streamed call: the wall span from request
|
|
54
|
+
* open (`t0Model`) to the fold (`nowMs`), minus the tool-busy union. Clamped
|
|
55
|
+
* at 0 so a tool span that (through clock skew) outlives the wall span can
|
|
56
|
+
* never yield a negative latency — which would be read as "infinitely fast"
|
|
57
|
+
* by the reward.
|
|
58
|
+
*/
|
|
59
|
+
export function modelLatencyMs(t0Model, nowMs, toolBusyMs) {
|
|
60
|
+
return Math.max(0, nowMs - t0Model - Math.max(0, toolBusyMs));
|
|
61
|
+
}
|
package/dist/observability.d.ts
CHANGED
|
@@ -168,9 +168,18 @@ export type AttachedAdvisorPersistence = {
|
|
|
168
168
|
* `event-log` append path the run already writes its transcript with:
|
|
169
169
|
*
|
|
170
170
|
* error_recovered → `recovery` { errorName, action, depth }
|
|
171
|
-
* tool_call_end → `tool_stats` { toolName, durationMs, isError }
|
|
171
|
+
* tool_call_end → `tool_stats` { toolName, durationMs, isError, profile? }
|
|
172
172
|
* permission_decision → `permission` { toolName, decision, askOutcome }
|
|
173
|
-
* model_response → `model_meta` { stopReason, model
|
|
173
|
+
* model_response → `model_meta` { stopReason, model, role?, profile?,
|
|
174
|
+
* usage, durationMs, turnNumber }
|
|
175
|
+
*
|
|
176
|
+
* 0.6.0 (design §8.4) — `model_meta` carries exact per-turn attribution
|
|
177
|
+
* (`usage`, whole-ms `durationMs`, the envelope `turnNumber`, and the
|
|
178
|
+
* `role` / `profile` the response was published with) so `watchme report`'s
|
|
179
|
+
* `attributeModels` can be `exact` from the session log alone, without the
|
|
180
|
+
* opt-in `CREWHAUS_WATCHME` sidecar. `role`/`profile` are written only when
|
|
181
|
+
* the response carries them (absent role ⇒ primary), and readers that
|
|
182
|
+
* predate the enrichment keep reading `stopReason`/`model` unchanged.
|
|
174
183
|
*
|
|
175
184
|
* Unlike the other `attach*IfEnvSet` subscribers this one is DEFAULT-ON:
|
|
176
185
|
* the lines are tiny (see the granularity note on the `tool_stats` kind in
|
|
@@ -212,6 +221,42 @@ export type AttachedMcpStatsPersistence = {
|
|
|
212
221
|
* persistence hiccup must not abort a turn.
|
|
213
222
|
*/
|
|
214
223
|
export declare function attachMcpStatsPersistence(bus: TraceEventBus, eventLog: EventLog, runContext: RunContext, env?: NodeJS.ProcessEnv): AttachedMcpStatsPersistence | undefined;
|
|
224
|
+
export type AttachedRoutingPersistence = {
|
|
225
|
+
unsubscribe: Unsubscribe;
|
|
226
|
+
};
|
|
227
|
+
/**
|
|
228
|
+
* 0.6.0 (design §8.1) — mirror the routing decisions that were trace-bus-only
|
|
229
|
+
* in 0.5.x into the session JSONL, as the durable event-log kinds of the same
|
|
230
|
+
* name, so `crewhaus route explain`, `sessions tail`, Hangar's session gutter
|
|
231
|
+
* and `--resume` read them offline:
|
|
232
|
+
*
|
|
233
|
+
* model_failover → `model_failover` { turnNumber, from, to, reason }
|
|
234
|
+
* model_stage → `model_stage` { turnNumber, stage, strategy, role, model, profile?, outcome, cause?, costUsdMicros? }
|
|
235
|
+
* model_directive → `model_directive` { turnNumber, source, requested, resolved?, accepted, reason? }
|
|
236
|
+
* judge_verdict → `judge_verdict` { turnNumber, stepOrNode, verdict, score, rationale?, judgeModel?, panel?, costUsdMicros? }
|
|
237
|
+
*
|
|
238
|
+
* A bus subscriber rather than a `logEvent` at each publish site because two
|
|
239
|
+
* of these are published OUTSIDE runtime-core: the failover chain in
|
|
240
|
+
* `@crewhaus/model-router` (which has no event log) and the `kind: judge`
|
|
241
|
+
* gate helpers emitted into workflow/graph bundles. `model_tier_route` is
|
|
242
|
+
* the exception — its only publisher is runtime-core's own tier branch, which
|
|
243
|
+
* writes the durable line directly beside the publish, exactly as
|
|
244
|
+
* `model_route` does.
|
|
245
|
+
*
|
|
246
|
+
* UNGATED, like the `model_route` line and unlike the advisor mirrors: these
|
|
247
|
+
* records are what replay reads (`--resume` reconstructs a directive pin from
|
|
248
|
+
* `model_directive`; `route explain` reconstructs a turn's stages), so an env
|
|
249
|
+
* flag that dropped them would make replay diverge from the run. The lines
|
|
250
|
+
* are small and fire once per decision, not per token. `append()` failures
|
|
251
|
+
* are logged, never thrown — a persistence hiccup must not abort a turn.
|
|
252
|
+
*/
|
|
253
|
+
export type RoutingPersistedKind = "model_failover" | "model_stage" | "model_directive" | "judge_verdict";
|
|
254
|
+
export declare function attachRoutingPersistence(bus: TraceEventBus, eventLog: EventLog, runContext: RunContext, opts?: {
|
|
255
|
+
/** 0.6.0 PR 9c — persist only these kinds (a host's between-loop sink
|
|
256
|
+
* passes `["judge_verdict"]` so it never duplicates the lines the live
|
|
257
|
+
* loop's own subscriber writes). Absent → every routing kind. */
|
|
258
|
+
readonly kinds?: ReadonlyArray<RoutingPersistedKind>;
|
|
259
|
+
}): AttachedRoutingPersistence;
|
|
215
260
|
export declare const WATCHME_MIRRORED_KINDS: ReadonlySet<string>;
|
|
216
261
|
export type AttachedWatchmeCapture = {
|
|
217
262
|
unsubscribe(): void;
|
package/dist/observability.js
CHANGED
|
@@ -363,9 +363,18 @@ const CLEAN_STOP_REASONS = new Set(["end_turn", "tool_use", "stop_sequence"]);
|
|
|
363
363
|
* `event-log` append path the run already writes its transcript with:
|
|
364
364
|
*
|
|
365
365
|
* error_recovered → `recovery` { errorName, action, depth }
|
|
366
|
-
* tool_call_end → `tool_stats` { toolName, durationMs, isError }
|
|
366
|
+
* tool_call_end → `tool_stats` { toolName, durationMs, isError, profile? }
|
|
367
367
|
* permission_decision → `permission` { toolName, decision, askOutcome }
|
|
368
|
-
* model_response → `model_meta` { stopReason, model
|
|
368
|
+
* model_response → `model_meta` { stopReason, model, role?, profile?,
|
|
369
|
+
* usage, durationMs, turnNumber }
|
|
370
|
+
*
|
|
371
|
+
* 0.6.0 (design §8.4) — `model_meta` carries exact per-turn attribution
|
|
372
|
+
* (`usage`, whole-ms `durationMs`, the envelope `turnNumber`, and the
|
|
373
|
+
* `role` / `profile` the response was published with) so `watchme report`'s
|
|
374
|
+
* `attributeModels` can be `exact` from the session log alone, without the
|
|
375
|
+
* opt-in `CREWHAUS_WATCHME` sidecar. `role`/`profile` are written only when
|
|
376
|
+
* the response carries them (absent role ⇒ primary), and readers that
|
|
377
|
+
* predate the enrichment keep reading `stopReason`/`model` unchanged.
|
|
369
378
|
*
|
|
370
379
|
* Unlike the other `attach*IfEnvSet` subscribers this one is DEFAULT-ON:
|
|
371
380
|
* the lines are tiny (see the granularity note on the `tool_stats` kind in
|
|
@@ -427,6 +436,9 @@ export function attachAdvisorPersistence(bus, eventLog, runContext, env = proces
|
|
|
427
436
|
// without adding advisory signal.
|
|
428
437
|
durationMs: Math.round(event.durationMs),
|
|
429
438
|
isError: event.isError,
|
|
439
|
+
// 0.6.0 §5.6 — the serving profile, so `tools audit` can group
|
|
440
|
+
// failures by profile; absent (byte-identical) on a single-model run.
|
|
441
|
+
...(event.profile !== undefined ? { profile: event.profile } : {}),
|
|
430
442
|
});
|
|
431
443
|
return;
|
|
432
444
|
}
|
|
@@ -452,7 +464,17 @@ export function attachAdvisorPersistence(bus, eventLog, runContext, env = proces
|
|
|
452
464
|
responses += 1;
|
|
453
465
|
if (!CLEAN_STOP_REASONS.has(event.stopReason))
|
|
454
466
|
anomalousStops += 1;
|
|
455
|
-
persist("model_meta", {
|
|
467
|
+
persist("model_meta", {
|
|
468
|
+
stopReason: event.stopReason,
|
|
469
|
+
model: event.model,
|
|
470
|
+
...(event.role !== undefined ? { role: event.role } : {}),
|
|
471
|
+
...(event.profile !== undefined ? { profile: event.profile } : {}),
|
|
472
|
+
usage: event.usage,
|
|
473
|
+
// Whole milliseconds — performance.now() floats add line bytes
|
|
474
|
+
// without adding attribution signal.
|
|
475
|
+
durationMs: Math.round(event.durationMs),
|
|
476
|
+
turnNumber: event.turnNumber,
|
|
477
|
+
});
|
|
456
478
|
return;
|
|
457
479
|
}
|
|
458
480
|
case "compaction_fired": {
|
|
@@ -533,6 +555,77 @@ export function attachMcpStatsPersistence(bus, eventLog, runContext, env = proce
|
|
|
533
555
|
});
|
|
534
556
|
return { unsubscribe };
|
|
535
557
|
}
|
|
558
|
+
export function attachRoutingPersistence(bus, eventLog, runContext, opts = {}) {
|
|
559
|
+
const persist = (kind, payload) => {
|
|
560
|
+
void eventLog.append({ kind, payload }).catch((err) => {
|
|
561
|
+
runContext.logger.error("routing_event.persist_failed", {
|
|
562
|
+
kind,
|
|
563
|
+
message: err instanceof Error ? err.message : String(err),
|
|
564
|
+
});
|
|
565
|
+
});
|
|
566
|
+
};
|
|
567
|
+
const wanted = opts.kinds;
|
|
568
|
+
const unsubscribe = bus.subscribe((event) => {
|
|
569
|
+
if (wanted !== undefined && !wanted.includes(event.kind))
|
|
570
|
+
return;
|
|
571
|
+
switch (event.kind) {
|
|
572
|
+
case "model_failover": {
|
|
573
|
+
const e = event;
|
|
574
|
+
persist("model_failover", {
|
|
575
|
+
turnNumber: e.turnNumber,
|
|
576
|
+
from: e.from,
|
|
577
|
+
to: e.to,
|
|
578
|
+
reason: e.reason,
|
|
579
|
+
});
|
|
580
|
+
return;
|
|
581
|
+
}
|
|
582
|
+
case "model_stage": {
|
|
583
|
+
const e = event;
|
|
584
|
+
persist("model_stage", {
|
|
585
|
+
turnNumber: e.turnNumber,
|
|
586
|
+
stage: e.stage,
|
|
587
|
+
strategy: e.strategy,
|
|
588
|
+
role: e.role,
|
|
589
|
+
model: e.model,
|
|
590
|
+
...(e.profile !== undefined ? { profile: e.profile } : {}),
|
|
591
|
+
outcome: e.outcome,
|
|
592
|
+
...(e.cause !== undefined ? { cause: e.cause } : {}),
|
|
593
|
+
...(e.costUsdMicros !== undefined ? { costUsdMicros: e.costUsdMicros } : {}),
|
|
594
|
+
});
|
|
595
|
+
return;
|
|
596
|
+
}
|
|
597
|
+
case "model_directive": {
|
|
598
|
+
const e = event;
|
|
599
|
+
persist("model_directive", {
|
|
600
|
+
turnNumber: e.turnNumber,
|
|
601
|
+
source: e.source,
|
|
602
|
+
requested: e.requested,
|
|
603
|
+
...(e.resolved !== undefined ? { resolved: e.resolved } : {}),
|
|
604
|
+
accepted: e.accepted,
|
|
605
|
+
...(e.reason !== undefined ? { reason: e.reason } : {}),
|
|
606
|
+
});
|
|
607
|
+
return;
|
|
608
|
+
}
|
|
609
|
+
case "judge_verdict": {
|
|
610
|
+
const e = event;
|
|
611
|
+
persist("judge_verdict", {
|
|
612
|
+
turnNumber: e.turnNumber,
|
|
613
|
+
stepOrNode: e.stepOrNode,
|
|
614
|
+
verdict: e.verdict,
|
|
615
|
+
score: e.score,
|
|
616
|
+
...(e.rationale !== undefined ? { rationale: e.rationale } : {}),
|
|
617
|
+
...(e.judgeModel !== undefined ? { judgeModel: e.judgeModel } : {}),
|
|
618
|
+
...(e.panel !== undefined ? { panel: e.panel } : {}),
|
|
619
|
+
...(e.costUsdMicros !== undefined ? { costUsdMicros: e.costUsdMicros } : {}),
|
|
620
|
+
});
|
|
621
|
+
return;
|
|
622
|
+
}
|
|
623
|
+
default:
|
|
624
|
+
return;
|
|
625
|
+
}
|
|
626
|
+
});
|
|
627
|
+
return { unsubscribe };
|
|
628
|
+
}
|
|
536
629
|
// -------- "watch me" live capture tap (design/watch-me.md §6.1) --------
|
|
537
630
|
/**
|
|
538
631
|
* Reconciliation with the SHIPPED G26 `observability:` block (watch-me §4.5 —
|
|
@@ -589,6 +682,14 @@ const WATCHME_MIRRORED_KIND_RECORD = {
|
|
|
589
682
|
model_meta: true,
|
|
590
683
|
mcp_stats: true,
|
|
591
684
|
model_route: true,
|
|
685
|
+
// 0.6.0 (design §8.1) — the routing decisions made durable in this release:
|
|
686
|
+
// the tier twin of model_route (written beside its publish) and the four
|
|
687
|
+
// kinds `attachRoutingPersistence` mirrors from the bus.
|
|
688
|
+
model_tier_route: true,
|
|
689
|
+
model_failover: true,
|
|
690
|
+
model_stage: true,
|
|
691
|
+
model_directive: true,
|
|
692
|
+
judge_verdict: true,
|
|
592
693
|
wiki_write: true,
|
|
593
694
|
plan_update: true,
|
|
594
695
|
goal_update: true,
|
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 0.6.0 §7.2 / §7.11 — the `preRoute` decision phase: what runs BEFORE the
|
|
3
|
+
* synchronous `PolicyRouter.route()` call on every pooled model call and
|
|
4
|
+
* produces the `RouteHint` the router consumes. Pure over its context (the
|
|
5
|
+
* one `await` is the opt-in classifier call the loop injects), so every
|
|
6
|
+
* decision replays exactly from the persisted `model_route` line.
|
|
7
|
+
*
|
|
8
|
+
* Order — forced → directive → rules → classifier → policy over `eligible[]`
|
|
9
|
+
* (plan §7.2; the forced lane comes FIRST so a `/model` pin can never disarm
|
|
10
|
+
* a budget degrade or an escalation):
|
|
11
|
+
*
|
|
12
|
+
* 1. eligibility (N1) — the turn's requirement vector (image blocks in the
|
|
13
|
+
* transcript, tools in play, the context size, a matched rule's
|
|
14
|
+
* `requires`) intersected with each candidate's features / declared
|
|
15
|
+
* `requires` / breaker state / `enabled` / remaining per-profile cost
|
|
16
|
+
* cap → `eligible[]`, persisted;
|
|
17
|
+
* 2. forced — a budget degrade or the escalation latch names the arm
|
|
18
|
+
* (substituted by the loop; the hint records the lane). The forced arm
|
|
19
|
+
* is run through the SAME requirement check: an ineligible degrade rung
|
|
20
|
+
* gives way to the cheapest eligible roster arm, an ineligible
|
|
21
|
+
* escalation target to the strongest eligible one (§7.11: ineligible
|
|
22
|
+
* rather than a request-time error), and when nothing eligible remains
|
|
23
|
+
* the forced arm stands with `no-eligible-candidate` recorded;
|
|
24
|
+
* 3. directive — the session's `/model` pin, when it is on the roster AND
|
|
25
|
+
* eligible this turn (an ineligible pin is noted and skipped);
|
|
26
|
+
* 4. rules — first-match `model_pool.rules[]`; `use: <tag|arm>` forces that
|
|
27
|
+
* arm, `use: { requires }` narrows `eligible[]` and picks the cheapest
|
|
28
|
+
* survivor; the `ruleId` is persisted;
|
|
29
|
+
* 5. classifier — `policy: classifier` runs the injected enum-constrained
|
|
30
|
+
* label call; any failure falls back to the heuristic policy with the
|
|
31
|
+
* reason `classifier failed`;
|
|
32
|
+
* 6. otherwise the hint only carries `eligible[]` and the policy decides.
|
|
33
|
+
*
|
|
34
|
+
* Also here: the SYNTHETIC-message marker. runtime-core pushes five kinds of
|
|
35
|
+
* non-human `role: "user"` messages onto the transcript (the grader-rationale
|
|
36
|
+
* correction, the continue nudge, the tombstone retry, loop-detection
|
|
37
|
+
* notices, the resume/toolset marker); they are `synthetic: true` in the
|
|
38
|
+
* event log and marked in memory here so `latestHumanUserMessage` — the
|
|
39
|
+
* text the rules and the classifier read — never sees them (a `/model fast`
|
|
40
|
+
* echoed inside a judge's rationale must not steer routing, §7.2.1).
|
|
41
|
+
* Directives themselves are parsed at the typed INPUT seams (the REPL input,
|
|
42
|
+
* the single-turn seed), never from the transcript.
|
|
43
|
+
*/
|
|
44
|
+
import type Anthropic from "@anthropic-ai/sdk";
|
|
45
|
+
import { type EligibilityCandidate, type EligibilityExclusionReason, type RouteHint, type RouteRule, type RouteSignals, type RuleSkip, type TurnRequirement } from "@crewhaus/model-plan";
|
|
46
|
+
/** Mark a runtime-injected `role: "user"` message as NOT human input. Returns it. */
|
|
47
|
+
export declare function markSynthetic<T extends Anthropic.MessageParam>(message: T): T;
|
|
48
|
+
/** Was this message injected by the runtime (or replayed from a `synthetic: true` log line)? */
|
|
49
|
+
export declare function isSyntheticMessage(message: Anthropic.MessageParam): boolean;
|
|
50
|
+
/** The text blocks of a message joined by newlines (`""` for a tool-result-only message). */
|
|
51
|
+
export declare function messageText(message: Anthropic.MessageParam): string;
|
|
52
|
+
/** Does the message carry an image block (directly, not inside a tool_result)? */
|
|
53
|
+
export declare function messageHasImages(message: Anthropic.MessageParam): boolean;
|
|
54
|
+
/**
|
|
55
|
+
* The latest HUMAN user message: the last `role: "user"` entry that is not
|
|
56
|
+
* synthetic and carries human words or an image (a bare tool-result tail is
|
|
57
|
+
* skipped). `undefined` when none exists.
|
|
58
|
+
*/
|
|
59
|
+
export declare function latestHumanUserMessage(messages: ReadonlyArray<Anthropic.MessageParam>): Anthropic.MessageParam | undefined;
|
|
60
|
+
/**
|
|
61
|
+
* The request-local copy of a user message with its `/model …` token
|
|
62
|
+
* removed: a string message becomes `rest`; a block message keeps every
|
|
63
|
+
* non-text block and replaces its text with `rest` (dropping the text block
|
|
64
|
+
* when `rest` is empty and other blocks remain). The PERSISTED transcript
|
|
65
|
+
* keeps the token — only the request copy is stripped (§7.2.1).
|
|
66
|
+
*/
|
|
67
|
+
export declare function stripDirectiveFromMessage(message: Anthropic.MessageParam, rest: string): Anthropic.MessageParam;
|
|
68
|
+
/** One roster arm as `preRoute` sees it: the eligibility inputs plus its routing identity. */
|
|
69
|
+
export type PreRouteArm = EligibilityCandidate & {
|
|
70
|
+
readonly armId: string;
|
|
71
|
+
readonly modelString: string;
|
|
72
|
+
readonly tags: readonly string[];
|
|
73
|
+
};
|
|
74
|
+
/** The forced lane's input: a budget degrade or the escalation latch. */
|
|
75
|
+
export type PreRouteForced = {
|
|
76
|
+
/** The forced arm's id when it is on the roster (a non-roster degrade rung has none). */
|
|
77
|
+
readonly armId?: string;
|
|
78
|
+
/**
|
|
79
|
+
* The eligibility inputs of a degrade rung that sits OFF the roster (a
|
|
80
|
+
* roster arm is checked through `roster`). Absent → the rung's
|
|
81
|
+
* eligibility is unknown and it is served as-is.
|
|
82
|
+
*/
|
|
83
|
+
readonly candidate?: EligibilityCandidate;
|
|
84
|
+
readonly lane: "budget" | "escalation";
|
|
85
|
+
readonly reason: string;
|
|
86
|
+
};
|
|
87
|
+
export type PreRouteClassifierVerdict = {
|
|
88
|
+
/** One of the pool's declared tags. */
|
|
89
|
+
readonly label: string;
|
|
90
|
+
/** Wire model id of the classifier call. */
|
|
91
|
+
readonly model?: string;
|
|
92
|
+
readonly costUsdMicros?: number;
|
|
93
|
+
};
|
|
94
|
+
export type PreRouteContext = {
|
|
95
|
+
/** The pool's enabled candidates, declared order. */
|
|
96
|
+
readonly roster: readonly PreRouteArm[];
|
|
97
|
+
readonly signals: RouteSignals;
|
|
98
|
+
/** The turn's requirement vector (N1). */
|
|
99
|
+
readonly turn: TurnRequirement;
|
|
100
|
+
readonly policy: "static" | "heuristic" | "learned" | "classifier";
|
|
101
|
+
readonly forced?: PreRouteForced;
|
|
102
|
+
/** The run's `/model` pin (already roster-validated); honoured only when eligible. */
|
|
103
|
+
readonly pin?: string;
|
|
104
|
+
readonly rules?: readonly RouteRule[];
|
|
105
|
+
/**
|
|
106
|
+
* The injected classifier call (`policy: classifier` only) — resolves to
|
|
107
|
+
* the label, throws on any failure. Absent → "no classifier wired".
|
|
108
|
+
*/
|
|
109
|
+
readonly classifier?: () => Promise<PreRouteClassifierVerdict>;
|
|
110
|
+
/** The classifier's declared labels — the closed vocabulary a verdict must come from. */
|
|
111
|
+
readonly classifierLabels?: readonly string[];
|
|
112
|
+
/** Set by the loop when the classifier must not run (e.g. `judge_share_exhausted`). */
|
|
113
|
+
readonly classifierSkipReason?: string;
|
|
114
|
+
/** `model_pool.routing.strongTag` (default `strong`) — for the rule/classifier tag lookup. */
|
|
115
|
+
readonly strongTag?: string;
|
|
116
|
+
};
|
|
117
|
+
export type PreRouteResult = {
|
|
118
|
+
readonly hint: RouteHint;
|
|
119
|
+
/** Eligible arm ids, declared order (the hint's `eligible`, after any rule narrowing). */
|
|
120
|
+
readonly eligible: readonly string[];
|
|
121
|
+
readonly excluded: ReadonlyArray<{
|
|
122
|
+
readonly armId: string;
|
|
123
|
+
readonly reason: EligibilityExclusionReason;
|
|
124
|
+
}>;
|
|
125
|
+
/** The first-match rule that steered the turn, when one did. */
|
|
126
|
+
readonly ruleId?: string;
|
|
127
|
+
readonly skippedRules: readonly RuleSkip[];
|
|
128
|
+
readonly classifierVerdict?: PreRouteClassifierVerdict;
|
|
129
|
+
/**
|
|
130
|
+
* Set when the forced lane's arm was INELIGIBLE this turn (§7.11): `served`
|
|
131
|
+
* names the eligible roster arm substituted for it — the cheapest for a
|
|
132
|
+
* budget degrade, the strongest for an escalation — and is absent when no
|
|
133
|
+
* eligible arm remained (the loop then keeps the forced arm, records
|
|
134
|
+
* `no-eligible-candidate` and warns).
|
|
135
|
+
*/
|
|
136
|
+
readonly forcedIneligible?: {
|
|
137
|
+
readonly armId: string;
|
|
138
|
+
readonly reason: string;
|
|
139
|
+
readonly served?: string;
|
|
140
|
+
};
|
|
141
|
+
/**
|
|
142
|
+
* Human-readable notes for the decision's `reason` — a pin that sat out,
|
|
143
|
+
* a rule whose target was ineligible, a classifier failure. Never user text.
|
|
144
|
+
*/
|
|
145
|
+
readonly notes: readonly string[];
|
|
146
|
+
};
|
|
147
|
+
export declare function preRoute(ctx: PreRouteContext): Promise<PreRouteResult>;
|
|
148
|
+
/** Render a hint's evidence as `k=v` pairs for the persisted `hint.evidence` string. */
|
|
149
|
+
export declare function describeHintEvidence(evidence: Readonly<Record<string, unknown>>): string;
|