@sema-agent/core 7.67.0 → 7.67.1

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/CHANGELOG.md CHANGED
@@ -1,3 +1,38 @@
1
+ ## 7.67.1 — 2026-11-11
2
+
3
+ ### A word read over a host's own catalog resolves the entry's `fallbacks` chain over that catalog — a host read judges the entry it reads and the entries its chain names, nothing else; `catalogOfDeps` is root-exported, the catalog door as a function (#4150, #4216; widening: a catalog entry carrying `fallbacks` is no longer refused at a host read; narrowing: none; behavior change — a refusal v7.67.0 already gave changed code on one form and sentence on two, below, open to veto @server; hard-breaking: none; closed sets: none; exports: +1 function `catalogOfDeps`; wire: none) (@server @client-core)
4
+
5
+ - **Rule.** A read by word answers the model door's snapshot of the entry behind the word, received as the catalog entry it is, with its chain. An entry a caller wrote is received at the read, and its `fallbacks` words are resolved over the catalog it sits in: each hop is the catalog's entry for its word, judged by the catalog door's own chain judgment, and the chain is recorded on the snapshot. One body judges every chain — the door over its generation, a read over the catalog it reads, a host's tier expansion over the expansion. A snapshot a catalog holds (a Runner's catalog, a slice or a copy of it, a key a tier expansion laid out) is its own answer, chain included. Nothing else in the catalog is read.
6
+ - **Before (v7.67.0).** `resolveModel`, `resolveTaskModel`, `roleModelIfSet`, `expandTiers`, `runSideQuery` and the classifier seat received an entry of a host's catalog as a Model object outside any catalog, so an entry carrying `fallbacks` was refused `config.model_fallback_invalid` wherever a host read reached it: by word, by role, under a tier binding, and under a `{ select }` role whenever the catalog merely held one. A chain was resolved and recorded only inside the door (`new Runner` / `swapDeps`), so a host could not hand a WebFetch summarizer (or any lane) a model carrying its chain.
7
+ - **Now.** By word, by role, at a role seat: the entry resolves to the snapshot carrying its chain, and a side query, or a WebFetch summarizer handed that snapshot, walks it. Under a tier binding (`expandTiers`): each key laid out carries its chain resolved over the expansion, so a tier word in a chain is a key there, and an expansion over a replaced hop names the snapshot that carries the new hop. Under `{ select }`: every candidate is received once at `roles.<role>.select`, as before, and the pick is read with its chain over the candidates already received — what is judged is what is picked, nothing is received twice. One host catalog read twice names one snapshot, also after a hop it names changed and changed back: one fork per (entry, chain), as the door keeps across generations.
8
+ - **Refusals at a read** name the read's seat in `detail.field`, as v7.67.0's read refusals did, and name the entry in the sentence. A chain word the catalog does not hold, the entry itself as a hop, a repeated hop and more than three words are refused `config.model_fallback_invalid` ("the `fallbacks` of the catalog entry "p" (read at model) names "nope", which this catalog does not hold …"); a hop the model door refuses is refused by the model door's own code, named as a fallback of the entry; under a tier binding the seat is `tiers.<the bound tier>`. A chain word that is a tier word, over a catalog handed over without its expansion, says so and names the fix (hand over the bindings beside it, or `expandTiers(models, tiers)`); the door's sentence carries the same note.
9
+ - **Refusals that changed against v7.67.0 (open to veto @server)** — forms v7.67.0 refused too; measured on both built packages:
10
+ - **Code (one form).** A read by word of an entry whose chain names a hop the model door refuses (a hop with no `api`, say): v7.67.0 `config.model_fallback_invalid`, `detail.field` `model` (the chain itself was refused: "model is "p" (a catalog entry) carrying `fallbacks`, which only a catalog entry declares — …") → 7.67.1 the hop's own door code, `config.unknown_role` with `detail.reason` `not_a_model_ref`, `detail.field` `model` ("model is "bad" (a fallback of the catalog entry "p") whose `api` is absent — …"). A host that branches on the code meets the other arm.
11
+ - **Sentence (same code, same field).** A read by word of an entry whose chain names a word the catalog does not hold (also, by the same judgment, the entry itself, a repeated hop, more than three words): v7.67.0 the sentence above ("… carrying `fallbacks`, which only a catalog entry declares …") → the chain judgment's own sentence, naming the entry and the read's seat ("the `fallbacks` of the catalog entry "p" (read at model) names "c", which this catalog does not hold — a fallback is a catalog word.").
12
+ - **Sentence (same code, same field), at the door and at a read.** A chain word that is a tier word, over a catalog handed over without its tier expansion: the sentence ends with the added note (`new Runner` / `swapDeps` / `catalogOfDeps`: "RunnerDeps.models.p.fallbacks names "flash", which this catalog does not hold — a fallback is a catalog word. "flash" is a tier word, and this catalog was handed over without its tier expansion: hand over the tier bindings beside it (`tiers`), or its expansion (`expandTiers(models, tiers)`), and the word is one of its keys.").
13
+ - Every other refusal of the door reads as v7.67.0's `new Runner` did — code, `detail.field` and sentence (measured: an entry no read reaches with a bad chain, a hop with no `api`, a retired member, a catalog that is a list, four hops).
14
+ - **What a read reads, and what it costs.** Each read receives the entry behind the word and each hop of its chain once, as v7.67.0 received the entry at each read: values edited in place read as they are now, and an entry no read reaches is never read and refuses nothing — a bad entry, a bad chain or a catalog record of another kind elsewhere included, as on v7.67.0. No judgment is held for a catalog. So a read of an entry without a chain costs what v7.67.0's read cost — the one receipt of that entry — and a read of an entry with a chain adds one receipt per hop; `expandTiers` lays out what v7.67.0 laid out and resolves the chain of each key it laid out that carries one.
15
+ - **`catalogOfDeps` is root-exported (#4216)** — the catalog door `new Runner` takes a catalog through (`receiveModelCatalog` at `RunnerDeps`), as a function: a host judges a catalog it is about to hand over (a hot swap, a new Runner) without building a Runner, and meets the refusal `new Runner` gives the same catalog, the same `code` and the same sentence (pinned for a chain word the catalog does not hold, the entry itself as a hop, a repeated hop, more than three hops, an entry with no `api`, a catalog that is no plain record, and a binding naming a word the catalog does not hold); a catalog the door made is handed back as itself. It judges the whole catalog at every call; nothing is held. Its refusal codes are members of the root-exported closed set `CONFIG_REFUSAL_CODES`: `config.invalid_argument` (the catalog or the bindings no plain record), `config.unknown_role` (an entry or a binding that is no model, `detail.reason` `not_a_model_ref` / `unknown_model_ref`), `config.model_fallback_invalid` (a chain), `config.deps_retired_key` (a retired member). @server
16
+ - **Not changed.** A catalog with no chain reads as before. `expandTiers` without bindings (`undefined` or `{}`) is the catalog itself; with bindings it is a new, unfrozen catalog of the caller's own entries with a frozen snapshot at each tier key, and it reads the caller's catalog and bindings as v7.67.0 did. Tier defaults stand over a host's expansion and over a copy of it. A Model object that is no catalog entry (a task's, a role's) still refuses `fallbacks`. The door — `new Runner`, `swapDeps`, `catalogOfDeps`, the consolidation seat, the classifier seat with tier bindings, the face question — judges a whole catalog, as before.
17
+ - **Withdrawn before release** (the 7.67.1 candidate commits handed over earlier carried them; none is in a published version): a host read judging the whole catalog as `new Runner` does (the narrowing named there — nothing narrows now); the classifier seat's `catalogRefusal` member and the `CatalogRefusal` type; `expandTiers` refusing a bindings record that is no plain record; the judgment held per catalog shape and per bindings shape, its held refusals, and `expandTiers` reading through it. **What a host that took those candidates meets now (@server):** an entry no tier key names, whose chain is bad, is no longer refused at `expandTiers` or at a read over the expansion (the candidates refused it there; v7.67.0 did not judge it there either); it is refused where a whole catalog is judged — `new Runner`, `swapDeps`, `catalogOfDeps`. A host that wants a catalog judged whole before it adopts it (a staged hot swap, a boot that falls back to the last good configuration) calls `catalogOfDeps({ models, tiers })` first.
18
+ - **A WebFetch summarizer** walks a chain when it is handed the model a host read resolves for a word (`resolveModel(word, catalog)`): that snapshot carries the chain. The host's own entry object carries none.
19
+ - **Rules.** Judgments of a chain: 1 (the door's) → 1 (the same body, over the catalog the chain is resolved in: the door's generation, the catalog a read reads, a host's expansion). Readings of "the catalog these deps name": as on v7.67.0. Holders: none (a read holds nothing beyond the model door's own interning of an entry and one fork per chain). Special cases: 0 new — a snapshot a catalog holds is its own answer by the model door's existing rule.
20
+ - **Pins.** `test/backlog3567-model-lane.test.ts` "#4150 a word read over a host's own catalog resolves the entry's chain …": every resolver, the side query and the summarizer, the classifier seat, the door's identity, a Model object outside a catalog, what `expandTiers` reads, a fork per chain, the tier-word sentence, the control. "#4150 a read judges what it reads …": an entry no read reaches is never read and refuses nothing, through every reader; a refusal names the read's seat; one receipt of the entry and of each hop per read, getter-counted, values read as they are now; `{ select }` one receipt per candidate and the pick read with its chain; a snapshot a catalog holds is its own answer — a Runner's catalog, a slice, a copy, a tier key; a workflow node that picks a chained model through the allowlist's one-entry slice of the Runner's catalog walks the chain (real Runner); `expandTiers` chains over the expansion and over a replaced hop; #4216 `catalogOfDeps` and `new Runner` refuse each bad form with the same code and sentence; a wall-clock tripwire. `backlog2769-model-door`, `backlog2846-model-door`, `backlog1950-resume-config-doors-preclaim` and `backlog830-classifier-seat-export` read as on v7.67.0, unchanged.
21
+ - **Consumers.** @server (R-1): the host-side reads stop refusing a chain entry and judge only what they read; a seat that hands a raw table should hand its expansion when a chain names a tier word; `catalogOfDeps` is the pre-swap check (#4216). @client-core: one root export added (`catalogOfDeps`).
22
+
23
+ ### A fallback hop the deployment Brain's route judgment refuses before sending is named — on the answer's marker, `TaskResult.degraded` and the `model.fallback` notice; a walk that sent no hop at all is announced (#4151; widening: a notice now appears where a walk left no trace; hard-breaking: none; exports: +`SkippedHop` / `FallbackUnsent` types, +`readFallbackUnsent` / `FALLBACK_UNSENT_DIAGNOSTIC_TYPE`, `skipped?` on `DegradationInfo` and `TaskResult.degraded`, `outcome?` / `answeredBy?` on `TaskResult.degraded`, all additive; wire: `model.fallback` detail +`skipped?`, and a new presence form, open to veto @server @client-core)
24
+
25
+ - **Rule.** The marker and `TaskResult.degraded` describe the hops a walk tried; the `model.fallback` notice describes the attempt itself, including the hops that could not be sent. A refused hop is never sent and never billed; it is named with the refusal code the judgment stated.
26
+ - **Before (v7.67.0).** The model lane skipped a hop the deployment Brain's `adjudicateRoute` refused before dispatch and left no trace of it (`brain/model-lane.ts` — the skip ran before the hop was recorded as tried): a chain `[mispaired, paired]` answered by `paired` read `chain: ["paired"]` on the marker, the result and the notice; a chain whose every later hop was refused answered the requested model's failure with no marker, no `TaskResult.degraded` and no notice — zero runtime trace of the fallback attempt.
27
+ - **Now.** A walk that tried a hop carries `skipped: [{ model, code? }]` (chain order) on its marker (`readDegradation`), on `TaskResult.degraded` and in the notice's `detail`, and the notice's sentence names them ("Not tried — its route was refused before sending: mispaired (route.credential_mismatch)."). `to` keeps its reading — the last hop tried. A walk that began and sent no hop answers, as before, the requested model's own failure with no marker and no `TaskResult.degraded`; its answer carries a statement of the attempt (diagnostic `fallback_unsent`: `{ from, reason, skipped }`, read by `readFallbackUnsent`), and the leg announces it once: `model.fallback` with `outcome: "exhausted"`, `chain: []`, `skipped`, and no `to` / `toWindow` — "primary could not serve this request (rate_limit); none of its fallbacks was sent — its route was refused before sending: mispaired (route.credential_mismatch); the request ended with primary's own failure." — and `RunnerDeps.onError` (phase `degraded`) says the same sentence once on the main lane.
28
+ - **`TaskResult.degraded` says who answered** (additive): `outcome` (`served` / `exhausted`, the marker's word) and `answeredBy` (`to` when a hop served, `from` when the chain was exhausted) ride the walked turn's record, so a caller reading only the result no longer takes an exhausted walk's `to` — the last hop tried — for the model that answered. Absent on the budget path.
29
+ - **One statement per walk.** A message the deployment Brain hands back more than once carries only the latest walk's statement: writing the marker removes a `fallback_unsent` statement, and writing that statement removes a marker.
30
+ - **Widening (open to veto @server @client-core).** `model.fallback` now appears for a request no fallback hop was sent for (outcome `exhausted`, `chain` empty, no `to`): a reader that takes every `model.fallback` to carry `to` reads it as absent there. The notice's `detail` is the notice's open record (`EngineNotice.detail: Record<string, unknown>`), no exported per-code type changes. A side query has no leg book, so a side query whose walk sent no hop announces nothing (as a side query announces no walk).
31
+ - **Not changed.** Hops that were tried, `chain`, `to`, `answeredBy`, the bills and the left-behind list read as before; a walk with no refused hop carries no `skipped` member.
32
+ - **Rules.** Readings of a refused hop: 1 (the lane's skip) → 1 (the same skip, now recorded where it happens); faces of the attempt: the marker for a walk that tried a hop, the `fallback_unsent` statement for one that sent none — one statement per walk, never both. Special cases: 0.
33
+ - **Pins.** `test/backlog3567-model-lane.test.ts` "#4151 …": a refused hop before the one that served (stream and complete), a refused hop after the last one tried (exhausted, `to` the last tried), no hop sent (no marker, one notice without `to`, one alert), a judgment that states no code, a list that does not read, and the control (no refused hop ⇒ no `skipped`).
34
+ - **Consumers.** @server: R-3 lands; the run-terminal projection table meets the new leaves `degraded.skipped.[].model` / `.code`, `degraded.outcome`, `degraded.answeredBy`. @client-core: `TaskResult.degraded` passes through with the additive member; a `model.fallback` reader meets the no-`to` form.
35
+
1
36
  ## 7.67.0 — 2026-11-10
2
37
 
3
38
  ### `forceDurableGate` forces a park only where a leg can be resumed — a delegated leg its parent forwarded no opt-in to parks no ask and refuses all three kinds of ask unconsulted (#4079; behavior change: a synchronous or fork child under a forced principal no longer parks a row nobody can resume; narrowing: two, below, open to veto @server @cli @client-core; widening: none; hard-breaking: none; closed sets: none; exports: none; wire: one detail value, `config.durable_gate_unavailable` `detail.cause: "leg_not_resumable"`) (@server @cli @client-core @test)
@@ -20,13 +20,14 @@
20
20
  * deployment Brain's non-streaming face hop by hop ({@link completeOf}: its own `complete`, else its stream read to its result),
21
21
  * returning the hop's message as the Brain answered it (its `errorKind` included).
22
22
  * - `adjudicateRoute` is the deployment Brain's own (the requested model is served first); each later hop is judged by it
23
- * before it is dispatched, and a hop whose pairing it refuses is skipped.
23
+ * before it is dispatched, and a hop whose pairing it refuses is skipped — never sent, and named on the answer's marker with the
24
+ * refusal code (`skipped`).
24
25
  *
25
26
  * Hops other than the first are dispatched without the request's per-call identity (`apiKey`, `headers`, `metadata`): those
26
27
  * were resolved for the requested model, and a hop is served with what the deployment Brain holds for the hop's own model.
27
28
  *
28
29
  * A walked request's answer carries a marker diagnostic ({@link DEGRADED_DIAGNOSTIC_TYPE}): who asked, which hops were tried,
29
- * why the walk began, whether a hop served or the chain was exhausted, and which hop's message this is. An exhausted chain
30
+ * which were refused before dispatch, why the walk began, whether a hop served or the chain was exhausted, and which hop's message this is. An exhausted chain
30
31
  * answers the FIRST hop's own terminal: the requested model's failure is the one its caller's recovery is built for.
31
32
  *
32
33
  * Every request an answer left behind on its way rides the answer in ONE diagnostic ({@link LEFT_BEHIND_DIAGNOSTIC_TYPE}): the
@@ -66,6 +67,23 @@ export interface DegradationInfo {
66
67
  outcome?: FallbackOutcome;
67
68
  /** Whose message the answer is: `to` when a hop served, `from` when the chain was exhausted. */
68
69
  answeredBy?: string;
70
+ /** The later hops the deployment Brain's route judgment refused before they were dispatched, in chain order — each the
71
+ * model it names and the refusal code the judgment stated (absent when it stated none). Absent when no hop was refused. */
72
+ skipped?: SkippedHop[];
73
+ }
74
+ /** A hop of a walk the deployment Brain's route judgment refused before dispatch: never sent, never billed. */
75
+ export interface SkippedHop {
76
+ model: string;
77
+ code?: string;
78
+ }
79
+ /** The `type` of the diagnostic a request's answer carries when its walk began and every later hop was refused before dispatch:
80
+ * no hop was tried, so the answer is the requested model's own and carries no marker — this says why none was tried. */
81
+ export declare const FALLBACK_UNSENT_DIAGNOSTIC_TYPE = "fallback_unsent";
82
+ /** A walk that sent no hop, as read back off an answer: the requested model's id, why the request left it, and the hops refused. */
83
+ export interface FallbackUnsent {
84
+ from: string;
85
+ reason: DegradeReason;
86
+ skipped: SkippedHop[];
69
87
  }
70
88
  /**
71
89
  * The marker off an answer, or `undefined`. Strict on every member: a marker whose required members do not parse, or whose
@@ -75,6 +93,10 @@ export interface DegradationInfo {
75
93
  export declare function readDegradation(msg: {
76
94
  diagnostics?: AssistantMessageDiagnostic[];
77
95
  } | undefined): DegradationInfo | undefined;
96
+ /** The walk that sent no hop off an answer ({@link FALLBACK_UNSENT_DIAGNOSTIC_TYPE}), or `undefined` — strict on every member, as the marker is. */
97
+ export declare function readFallbackUnsent(msg: {
98
+ diagnostics?: AssistantMessageDiagnostic[];
99
+ } | undefined): FallbackUnsent | undefined;
78
100
  /**
79
101
  * What a request left behind stands for in the list of the answer that moved past it: the requests IT left behind (its own list —
80
102
  * a gateway the failover decorator moved off before this hop failed too), then itself, at the model it asked for. A message that
@@ -95,6 +117,8 @@ export interface ServedReading {
95
117
  }[];
96
118
  /** The marker, when the answer is a walked request's. */
97
119
  readonly degraded?: DegradationInfo;
120
+ /** The walk that began and sent no hop (every later hop refused before dispatch), when the answer is such a request's own. */
121
+ readonly unsent?: FallbackUnsent;
98
122
  }
99
123
  /**
100
124
  * THE reading every accounting point makes of an answer: which model answered and which requests were left behind beside it,
@@ -9,6 +9,7 @@ import { ANY_HOP_FAILURE, DEFAULT_MODEL_FALLBACK_POLICY, hopGateAdmits, isDegrad
9
9
  export { DEGRADE_REASONS } from "../core/model-fallbacks.js";
10
10
  export const DEGRADED_DIAGNOSTIC_TYPE = "degraded";
11
11
  export const LEFT_BEHIND_DIAGNOSTIC_TYPE = "left_behind";
12
+ export const FALLBACK_UNSENT_DIAGNOSTIC_TYPE = "fallback_unsent";
12
13
  function readUsage(raw) {
13
14
  const num = (v) => typeof v === "number" && Number.isFinite(v);
14
15
  const input = readMember(raw, "input");
@@ -43,8 +44,11 @@ function diagnosticOf(msg, type) {
43
44
  }
44
45
  return undefined;
45
46
  }
46
- function putDiagnostic(msg, diag) {
47
- const others = (readElements(readMember(msg, "diagnostics")) ?? []).filter((d) => readMember(d, "type") !== diag.type);
47
+ function putDiagnostic(msg, diag, replaces = []) {
48
+ const others = (readElements(readMember(msg, "diagnostics")) ?? []).filter((d) => {
49
+ const t = readMember(d, "type");
50
+ return t !== diag.type && !(typeof t === "string" && replaces.includes(t));
51
+ });
48
52
  msg.diagnostics = [...others, diag];
49
53
  }
50
54
  export function readDegradation(msg) {
@@ -57,6 +61,7 @@ export function readDegradation(msg) {
57
61
  const chain = readMemberOrUnreadable(det, "chain");
58
62
  const outcome = readMemberOrUnreadable(det, "outcome");
59
63
  const answeredBy = readMemberOrUnreadable(det, "answeredBy");
64
+ const skippedList = readMemberOrUnreadable(det, "skipped");
60
65
  if (typeof from !== "string" || typeof to !== "string" || !isDegradeReason(reason))
61
66
  return undefined;
62
67
  const hops = chain === undefined ? undefined : readElements(chain);
@@ -66,6 +71,9 @@ export function readDegradation(msg) {
66
71
  return undefined;
67
72
  if (answeredBy !== undefined && typeof answeredBy !== "string")
68
73
  return undefined;
74
+ const skipped = skippedList === undefined ? undefined : readSkippedHops(skippedList);
75
+ if (skipped === null)
76
+ return undefined;
69
77
  return {
70
78
  from,
71
79
  to,
@@ -73,8 +81,34 @@ export function readDegradation(msg) {
73
81
  ...(hops !== undefined ? { chain: hops } : {}),
74
82
  ...(outcome !== undefined ? { outcome } : {}),
75
83
  ...(answeredBy !== undefined ? { answeredBy } : {}),
84
+ ...(skipped !== undefined ? { skipped } : {}),
76
85
  };
77
86
  }
87
+ function readSkippedHops(list) {
88
+ const entries = readElements(list);
89
+ if (entries === undefined)
90
+ return null;
91
+ const skipped = [];
92
+ for (const entry of entries) {
93
+ const model = readMember(entry, "model");
94
+ const code = readMemberOrUnreadable(entry, "code");
95
+ if (typeof model !== "string" || (code !== undefined && typeof code !== "string"))
96
+ return null;
97
+ skipped.push({ model, ...(code !== undefined ? { code } : {}) });
98
+ }
99
+ return skipped;
100
+ }
101
+ export function readFallbackUnsent(msg) {
102
+ const det = diagnosticOf(msg, FALLBACK_UNSENT_DIAGNOSTIC_TYPE)?.details;
103
+ if (typeof det !== "object" || det === null)
104
+ return undefined;
105
+ const from = readMember(det, "from");
106
+ const reason = readMember(det, "reason");
107
+ const skipped = readSkippedHops(readMember(det, "skipped"));
108
+ if (typeof from !== "string" || !isDegradeReason(reason) || skipped === null || skipped.length === 0)
109
+ return undefined;
110
+ return { from, reason, skipped };
111
+ }
78
112
  const reportsKnownUsage = (flag) => flag === undefined || flag === false;
79
113
  const unplacedRequest = () => ({ model: "", usage: ZERO_USAGE, usageMissing: true });
80
114
  function readLeftRequest(raw) {
@@ -113,10 +147,16 @@ export function servedReadingOf(requested, msg) {
113
147
  });
114
148
  const marker = readDegradation(msg);
115
149
  const served = marker !== undefined && marker.from === requested.id ? byId(marker.answeredBy ?? marker.to) : undefined;
116
- return served === undefined || marker === undefined ? { served: requested, attempts } : { served, attempts, degraded: marker };
150
+ if (served !== undefined && marker !== undefined)
151
+ return { served, attempts, degraded: marker };
152
+ const unsent = readFallbackUnsent(msg);
153
+ return unsent !== undefined && unsent.from === requested.id ? { served: requested, attempts, unsent } : { served: requested, attempts };
154
+ }
155
+ function tagUnsent(msg, info) {
156
+ putDiagnostic(msg, { type: FALLBACK_UNSENT_DIAGNOSTIC_TYPE, timestamp: Date.now(), details: { from: info.from, reason: info.reason, skipped: info.skipped.map((s) => ({ ...s })) } }, [DEGRADED_DIAGNOSTIC_TYPE]);
117
157
  }
118
158
  function tagDegraded(msg, info) {
119
- putDiagnostic(msg, { type: DEGRADED_DIAGNOSTIC_TYPE, timestamp: Date.now(), details: { ...info } });
159
+ putDiagnostic(msg, { type: DEGRADED_DIAGNOSTIC_TYPE, timestamp: Date.now(), details: { ...info } }, [FALLBACK_UNSENT_DIAGNOSTIC_TYPE]);
120
160
  }
121
161
  export function errorMessageOf(model, e, aborted) {
122
162
  return {
@@ -188,6 +228,13 @@ export function gateReadingOf(msg, hop, expired, callerAborted, gate) {
188
228
  }
189
229
  return hopGateAdmits(gate, reason) ? reason : undefined;
190
230
  }
231
+ function refusedHop(inner, hop) {
232
+ const verdict = inner.adjudicateRoute?.(hop);
233
+ if (verdict?.ok !== false)
234
+ return undefined;
235
+ const code = readMember(verdict, "code");
236
+ return { model: hop.id, ...(typeof code === "string" ? { code } : {}) };
237
+ }
191
238
  function hopOptionsOf(options) {
192
239
  return options === undefined ? undefined : { ...options, apiKey: undefined, headers: undefined, metadata: undefined };
193
240
  }
@@ -264,6 +311,7 @@ function walkStream(inner, policy, requested, chain, context, options) {
264
311
  let first;
265
312
  let reason;
266
313
  const tried = [];
314
+ const skipped = [];
267
315
  const left = [];
268
316
  const markerOf = (outcome, answeredBy) => ({
269
317
  from: requested.id,
@@ -272,12 +320,15 @@ function walkStream(inner, policy, requested, chain, context, options) {
272
320
  chain: [...tried],
273
321
  outcome,
274
322
  answeredBy: answeredBy.id,
323
+ ...(skipped.length > 0 ? { skipped: [...skipped] } : {}),
275
324
  });
276
325
  const answer = (run, info) => {
277
326
  const terminal = run.terminal ?? terminalOf(run.message);
278
327
  const message = terminalMessage(terminal, run.message);
279
328
  if (info !== undefined)
280
329
  tagDegraded(message, info);
330
+ else if (reason !== undefined && tried.length === 0 && skipped.length > 0)
331
+ tagUnsent(message, { from: requested.id, reason, skipped });
281
332
  carryLeftBehind(message, left.filter((l) => l.run !== run).flatMap((l) => leftEntriesOf(l.run.message, l.model.id)));
282
333
  if (!run.committed)
283
334
  for (const h of run.held)
@@ -290,8 +341,11 @@ function walkStream(inner, policy, requested, chain, context, options) {
290
341
  if (i > 0) {
291
342
  if (options?.signal?.aborted === true)
292
343
  break;
293
- if (inner.adjudicateRoute?.(hop)?.ok === false)
344
+ const refused = refusedHop(inner, hop);
345
+ if (refused !== undefined) {
346
+ skipped.push(refused);
294
347
  continue;
348
+ }
295
349
  tried.push(hop.id);
296
350
  }
297
351
  const isLast = i === hops.length - 1;
@@ -331,6 +385,7 @@ async function walkComplete(complete, inner, policy, requested, chain, context,
331
385
  let first;
332
386
  let reason;
333
387
  const tried = [];
388
+ const skipped = [];
334
389
  const left = [];
335
390
  const marked = (msg, outcome, answeredBy) => {
336
391
  tagDegraded(msg, {
@@ -340,6 +395,7 @@ async function walkComplete(complete, inner, policy, requested, chain, context,
340
395
  chain: [...tried],
341
396
  outcome,
342
397
  answeredBy: answeredBy.id,
398
+ ...(skipped.length > 0 ? { skipped: [...skipped] } : {}),
343
399
  });
344
400
  carryLeftBehind(msg, left.filter((l) => l.message !== msg).flatMap((l) => leftEntriesOf(l.message, l.model.id)));
345
401
  return msg;
@@ -349,8 +405,11 @@ async function walkComplete(complete, inner, policy, requested, chain, context,
349
405
  if (i > 0) {
350
406
  if (options?.signal?.aborted === true)
351
407
  break;
352
- if (inner.adjudicateRoute?.(hop)?.ok === false)
408
+ const refused = refusedHop(inner, hop);
409
+ if (refused !== undefined) {
410
+ skipped.push(refused);
353
411
  continue;
412
+ }
354
413
  tried.push(hop.id);
355
414
  }
356
415
  let msg;
@@ -376,6 +435,8 @@ async function walkComplete(complete, inner, policy, requested, chain, context,
376
435
  reason = reading;
377
436
  }
378
437
  const head = first;
438
+ if (reason !== undefined && tried.length === 0 && skipped.length > 0)
439
+ tagUnsent(head, { from: requested.id, reason, skipped });
379
440
  return reason === undefined || tried.length === 0 ? head : marked(head, "exhausted", requested);
380
441
  }
381
442
  const LANES = new WeakMap();
@@ -464,8 +464,11 @@ export interface EngineNotice {
464
464
  * chain: a fallback model answered (`outcome: "served"`) or none could (`"exhausted"`, the request ending with the requested
465
465
  * model's own failure). Read off the answer's marker where the run books each answer — the main loop (`lane: "main"`) and
466
466
  * the side-call book (`compaction` / `classifier` / `mod` / `advisor`); a call outside a leg's book announces nothing.
467
- * ONCE PER LEG PER (from, to, reason, outcome). Audience `user`; `detail: { from, to, reason, outcome, chain, lane,
468
- * fromWindow?, toWindow?, sessionId, runId? }` — `chain` the hops tried after `from`, the windows the models' `contextWindow`.
467
+ * ONCE PER LEG PER (from, to, reason, outcome). Audience `user`; `detail: { from, to, reason, outcome, chain, skipped?, lane,
468
+ * fromWindow?, toWindow?, sessionId, runId? }` — `chain` the hops tried after `from`, `skipped` the hops the deployment Brain's
469
+ * route judgment refused before sending (`{ model, code? }`, chain order), the windows the models' `contextWindow`. A walk that
470
+ * began and sent no hop (every later hop's route refused) is announced too — `exhausted`, `chain: []`, `skipped`, and no `to` /
471
+ * `toWindow` (no hop was tried; the answer, its marker-less message and `TaskResult.degraded` stay the requested model's own).
469
472
  * - `"context.tool_turn_repaired"` (#1224) — a provider request was built from a transcript that breaks the
470
473
  * tool-turn law, and the request view restored it (`engine/llm/tool-turns.ts`; the transcript is never
471
474
  * rewritten): a block after an assistant's tool calls moved ahead of them (`trailing_text`), a result recorded
@@ -63,12 +63,14 @@ export declare function modelFallbackRefusal(field: string, message: string): Er
63
63
  field: string;
64
64
  };
65
65
  };
66
- /** The chain the catalog door resolved for `model` — the hops after it, nearest first; empty for a model without one (an entry
66
+ /** The chain resolved for `model` over its catalog — the hops after it, nearest first; empty for a model without one (an entry
67
67
  * that declares none, a Model object that is no catalog entry). */
68
68
  export declare function modelFallbackChainOf(model: Model): readonly Model[];
69
- /** The chain recorded for `model`, or `undefined` when none was (the catalog door's read; the lane reads {@link modelFallbackChainOf}). */
69
+ /** The chain recorded for `model`, or `undefined` when none was (the chain judgment's read, `roles.ts`; the lane reads
70
+ * {@link modelFallbackChainOf}). */
70
71
  export declare function recordedFallbackChainOf(model: Model): readonly Model[] | undefined;
71
- /** The catalog door's write: `model`'s chain as this generation resolved it. Only the catalog door calls it, once per snapshot. */
72
+ /** The chain's one write: `model`'s chain as a catalog resolved it — the catalog door's generation, a read of a caller's catalog, a
73
+ * host's tier expansion (`roles.ts`, `chainedSnapshot`) — once per snapshot. */
72
74
  export declare function recordFallbackChain(model: Model, hops: readonly Model[]): void;
73
75
  /** The deployment's fallback policy as written at `RunnerDeps.modelFallback`. */
74
76
  export interface ModelFallbackPolicy {
@@ -7,9 +7,12 @@ export type { ModelRole, RoleSpec, ModelRoles } from "./types.js";
7
7
  export { MODEL_ROLES } from "./types.js";
8
8
  export { bindingShown } from "./model-receipt.js";
9
9
  /**
10
- * The catalog's answer for a model word — every read of a catalog's entry: the entry's snapshot from the model door (an entry of a
11
- * catalog the catalog door received is one already, handed back as itself; an entry of a catalog a caller built is received here, at
12
- * the read). `seat` names where the word was written; the entry is named as the catalog entry that word resolved to.
10
+ * The catalog's answer for a model word — every read of a catalog's entry: the entry's snapshot from the model door, received as the
11
+ * catalog entry it is, with its `fallbacks` chain. An entry a caller wrote is received here, at the read, and its words are resolved
12
+ * over the catalog it sits in ({@link chainedRead}); a snapshot the catalog holds — an entry of a catalog the catalog door received, or
13
+ * of a slice or copy of one, or a key a tier expansion laid out — is handed back as itself, with the chain it was resolved with. Only
14
+ * the entry behind the word and the entries its chain names are read. `seat` names where the word was written; the entry is named as
15
+ * the catalog entry that word resolved to.
13
16
  */
14
17
  export declare function catalogModel(ref: string, models: Record<string, Model> | undefined, seat: string, what?: string): Model | undefined;
15
18
  /** Whether `ref` names an entry of this catalog: the membership half of {@link catalogModel}, for a reader that lists names
@@ -44,30 +47,20 @@ export declare const CC_MODEL_TIER_ALIASES: Readonly<Record<string, string>>;
44
47
  * honest name — and passes through unchanged. Display only; routing (`expandTiers`) is untouched. */
45
48
  export declare function resolveModelDisplayLabel(ref: string): string;
46
49
  /**
47
- * Expand a deployment's tier bindings into the model catalog: every tier name (and every CC alias whose
48
- * tier resolves) becomes a catalog key pointing at the bound Model, so the ENTIRE resolve surface
49
- * (`resolveModel` / roles / `@model` mentions / Agent tool `model` / workflow `agent() opts.model`)
50
- * accepts tier vocabulary with ZERO per-callsite changes. Called ONCE at Runner construction.
51
- *
52
- * Rules:
53
- * - a tier with no binding falls back DOWN {@link DEFAULT_TIER_ORDER} to the first bound tier
54
- * (e.g. `max` unbound + `pro` bound ⇒ "max" resolves to the pro model — availability over strictness;
55
- * the gap stays visible in the deployment's catalog audit, not silently absent);
56
- * - an existing catalog key of the same name WINS (deployment SHADOW semantics, mirroring agents):
57
- * a deployment that already ships a model literally named "pro" keeps it untouched;
58
- * - a binding may itself be a catalog name or a Model object (resolved through `resolveModel`);
59
- * an unknown binding name throws at construction (config error surfaces at boot, not first use);
60
- * - `"best"` (dynamic head-of-chain alias, CC `$L` parity) resolves to the FIRST tier in
61
- * {@link DEFAULT_TIER_ORDER} that carries a DIRECT binding — "the strongest model this deployment
62
- * actually bound", not a fixed tier — under the same SHADOW rule (a deployment catalog key named
63
- * `best` wins); with no bound known-order tier (or no tiers at all) the key stays absent and
64
- * `resolveModel("best")` refuses like any unknown ref.
50
+ * A host's tier expansion of its own catalog ({@link expandTierKeys}, the body the catalog door expands with): without bindings
51
+ * (absent, or a record of none) the catalog itself; with them a new, unfrozen catalog holding the caller's own entries and, under the
52
+ * tier words, the snapshots of the entries the bindings name — each with its `fallbacks` chain resolved over this expansion, as the
53
+ * door resolves its generation's (a tier word in a chain is a key here; an entry expanded again over a replaced hop names the snapshot
54
+ * that carries the new one). Only the entries a binding names, and the entries their chains name, are read. A refusal names the
55
+ * binding seat (`tiers.<the bound tier>`).
65
56
  */
66
57
  export declare function expandTiers(models: Record<string, Model> | undefined, tiers: Record<string, ModelRef> | undefined): Record<string, Model> | undefined;
67
58
  /** Whether `models` is a catalog the catalog door made ({@link receiveModelCatalog}). */
68
59
  export declare function isReceivedCatalog(models: Record<string, Model> | undefined): boolean;
69
- /** The catalog a deps bag answers with — the catalog door's generation: a Runner's own (received at its construction) as it is, a bag a
70
- * caller built received here. The one reading of "the catalog these deps name", wherever deps are read outside a Runner's own seat. */
60
+ /** The catalog door's generation of a deps bag's catalog and the tier bindings beside it: a catalog the door made (a Runner's own) as
61
+ * it is; any other received here by the door `new Runner` takes it through ({@link receiveModelCatalog} at `RunnerDeps`), whole, at
62
+ * every call (nothing is held) — so a host that judges a catalog before it hands it over meets the refusal `new Runner` gives the same
63
+ * catalog, and gets the generation a Runner would read. A read by word reads only what the word reaches ({@link catalogModel}). */
71
64
  export declare function catalogOfDeps(deps: {
72
65
  models?: Record<string, Model>;
73
66
  tiers?: Record<string, ModelRef>;
@@ -77,7 +70,7 @@ export declare function catalogOfDeps(deps: {
77
70
  * `new Runner` and at `swapDeps`. The catalog is a plain record read once; every entry with a model behind it is received by the model door
78
71
  * now (a catalog entry no task names yet is judged as well as one a task names: a catalog is configuration, and a bad entry is a boot error,
79
72
  * not a first-use one); the bindings are a plain record read once, every binding a word or a Model object (received), a binding a catalog
80
- * key shadows included; THEN the bindings are expanded over the received catalog ({@link expandTiers} — its marks are written on its own
73
+ * key shadows included; THEN the bindings are expanded over the received catalog ({@link expandTierKeys} — its marks are written on its own
81
74
  * output, so they are never lost to a copy) and the result frozen. `field` names the door (`RunnerDeps` / `swapDeps`). Throws the first
82
75
  * refusal; nothing is written by the caller before it returns.
83
76
  */
@@ -120,7 +113,7 @@ export interface ModelMention {
120
113
  *
121
114
  * **Feed it the EXPANDED table.** The allowlist this takes is the host's own, and on a deployment that
122
115
  * configured `RunnerDeps.tiers` the host's `deps.models` is NOT what the Runner resolves against: the
123
- * constructor runs {@link expandTiers} once and keeps the expansion PRIVATE, so tier words and CC
116
+ * constructor runs {@link expandTierKeys} once and keeps the expansion PRIVATE, so tier words and CC
124
117
  * aliases (`pro`/`flash`/`opus`/`sonnet`/`best`/…) are catalog keys inside the Runner and absent from
125
118
  * the host's table. Passing `Object.keys(deps.models)` therefore makes a user's `@opus` silently not
126
119
  * match — the mention falls through as ordinary text and the task quietly runs on the default role.