@open-everywhere/core 0.1.0

package/dist/agent/model/routing.js

@@ -0,0 +1,694 @@
+// Domain-routed model — per-channel-group model / provider / reasoning. GENERIC CORE:
+// this module owns the routing DECISION (which route applies to a call's surface) and the
+// thin per-selection wrapper skeleton (fail-soft dispatch, memoization); everything
+// vendor-shaped — how a model id becomes a model instance, how a route's provider hints
+// map onto one call's options — lives behind the ModelBackend seam, implemented per model
+// transport in `@open-everywhere/adapters` (reference: the Vercel AI Gateway backend).
+// Core stays portable: a self-host on OpenRouter / a direct provider SDK writes its own
+// backend and the schema + resolution + wrapper are unchanged (docs/core-app-separation.md).
+//
+// HOW IDENTITY REACHES THE ROUTER (eve 0.22 native `defineDynamic`): the turn model is
+// authored as `defineAgent({ model: defineDynamic({ fallback, events }) })` — eve runs the
+// `step.started` resolver INSIDE the harness and hands it the calling `ctx`
+// (DynamicResolveContext), which is structurally a BindableContext: `ctx.session.auth`
+// carries the same current/initiator principals, `ctx.channel.kind` the platform. So the
+// resolver reconstructs the surface (bindFrom → domain key + dm/public match) straight from
+// ctx and resolves the ModelRoute — NO ALS read, NO module-global surface hint. This is the
+// whole point of the migration: the prior wrapper read the caller off eve's session ALS,
+// which is inert on Vercel's compiled build, and a "surface hint" hook was bolted on to
+// paper over it (bit prod twice). The native resolver ctx works on the hosted build because
+// it is populated by the harness, not scraped from an async-context reach.
+//
+// WHY `step.started`, NOT `turn.started` (eve 0.22 dynamic-model contract — the fix for the
+// regression the migration introduced): the resolver returns a per-selection routed model
+// INSTANCE (makeRoutedModel — a LanguageModel wrapper, needed because eve forwards only the
+// agent-STATIC `reasoning` to the model call, so per-domain reasoning must ride the model).
+// eve's dynamic-model dispatcher (context/dynamic-model-lifecycle.ts dispatchDynamicModelEvent)
+// REJECTS a provider-object return at session/turn scope — those selections must be
+// serialized (a model id string), so a LanguageModel instance is discarded and eve silently
+// falls back to the static `fallback`. Only `step.started` (a virtual, non-serialized
+// selection — LiveStepDynamicModelSelectionKey) accepts an instance and actually runs it
+// (harness/tool-loop.ts resolveActiveRuntimeModel uses `selection.model` directly). Wiring
+// the resolver at `turn.started` therefore killed routing outright AND, because the wrapper's
+// doGenerate never ran, left every usage_events row unstamped (dead cost attribution). The
+// resolver fires once per step now rather than once per turn — cheap (config reads + a memoized
+// pick lookup) and fail-soft, and identity is re-derived from the same ctx each step.
+//
+// WHAT THE RESOLVER RETURNS: `resolvePrimaryModel(ctx, …)` ALWAYS returns a RoutableModel —
+// never null (OPE-412). Routed surfaces get a thin per-selection wrapper; every other path
+// (unrouted, no-op, fail-soft) gets the DEFAULT model constructed concretely, at the exact id
+// eve's static fallback would have run. The wrapper bakes in the route it
+// resolved from ctx and applies it on each doGenerate/doStream — reasoning override
+// (eve forwards only the agent-STATIC `reasoning` to the model call, so per-domain reasoning
+// must ride the model instance) plus the backend's provider-option mapping. Unlike the old
+// wrapper it does NO identity work at call time: the route is a closure constant, resolved
+// once per turn from ctx.
+//
+// ROLES — this file routes ONE slot, and that is deliberate:
+//   primary — `defineAgent.model` = `defineDynamic`; resolved from ctx each step.started.
+//   utility — routed OUTSIDE a session, by SCOPE rather than ctx, for its live consumers: the
+//             dream cycle's judge/distiller and the failure-facet judge
+//             (adapters agent/model/dream-judge.ts `modelRouteFor("utility", …)`).
+//             🔴 It does NOT route compaction, and cannot. eve resolves an authored
+//             `defineAgent.compaction.model` through the AGENT-LEVEL `model` field, so any
+//             model INSTANCE in that slot kills the turn while the agent model is dynamic
+//             (OPE-670). agent/agent.ts authors no compaction model, so eve summarises with the
+//             live turn model — already routed by this file, on the primary path.
+//
+// Per-row cost attribution stamps the resolved id into model/model-stamp.ts's per-session
+// slot; hooks/spend.ts reads it back to attach an exact model to each usage_events row
+// rather than leaning on the assumed-model fallback (per-domain routing means more than one
+// model can be in play in one deployment). The PRIMARY id is stamped by the resolver itself
+// (resolvePrimaryModel, below) — inside the harness-supplied step context, the SAME context
+// the spend hook reads, so the stamp is guaranteed visible REGARDLESS of whether the AI SDK
+// preserves the async context into the wrapper's doGenerate. The wrapper's dispatch ALSO
+// stamps (belt-and-braces).
+//
+// FAIL-SOFT, deliberately NOT fail-closed: routing is a tuning preference, not an access
+// boundary. The resolver NEVER throws (a thrown resolver breaks the turn) — on ANY failure
+// (unbindable ctx, config not registered, resolver error) it resolves to the DEFAULT model and
+// the turn runs on exactly the model eve's static fallback would have picked. Each distinct
+// failure reason is logged once per instance so a silent downgrade is still visible in logs.
+//
+// 🔴 WHY THE FAIL-SOFT PATHS RETURN A MODEL RATHER THAN `null` (OPE-412). They used to return
+// `null`, which eve 0.32 reads as "no dynamic selection" and answers by resolving the static
+// `defineDynamic({ fallback })` reference itself. eve 0.33 REMOVES that affordance: a dynamic
+// resolver that returns null THROWS. Returning `deps.backend.model(defaults.primary.id)`
+// instead is behaviour-preserving TODAY and removes the 0.33 break in advance:
+//   - the id is identical. agent.ts wires `fallback: DEFAULT_MODEL` and `primary.id:
+//     DEFAULT_MODEL` from the same constant, so the concrete model IS eve's static fallback.
+//   - the audit row is unchanged. Every one of these sites already called
+//     `stampModelCall(defaults.primary.id)` — the code already ASSERTED "this call runs the
+//     default"; the return now matches the stamp instead of implying it.
+//   - providerOptions are unchanged. eve's normalizer (runtime/agent/resolve-model.ts
+//     normalizeDynamicRuntimeModelResult) fills a selection that sets no `modelOptions` from
+//     `fallback.providerOptions`, and tool-loop.ts passes the SAME reference
+//     (`dynamicModelDefaultReference ?? modelReference`) as both that `fallback` and the
+//     null-path model — so the two paths carry byte-identical provider options.
+//   - the construction cost is nil: `gateway(id)` is a plain object build, no I/O, measured at
+//     ~1µs, once per step. (NB it is NOT memoized — `makeRoutedModel`'s `inner` map only
+//     memoizes WITHIN one wrapper, and these sites bypass the wrapper entirely. ~1µs/step does
+//     not justify a cache.)
+// The one non-identical detail, and it is cosmetic: eve labels an instance selection
+// `formatLanguageModelGatewayId(model)` = `gateway/<id>` rather than the bare `<id>`. Both are
+// already true of every ROUTED step today, so this makes the fail-soft path match the routed path
+// rather than introducing a new state.
+//
+// ✅ THE WINDOW IS NO LONGER LOST ON ANY OF THESE PATHS (OPE-412, and this supersedes an earlier
+// note here that called the fix "0.33-only" — it was WRONG: `PublicAgentModelSelectionDefinition`
+// exists at 0.32.0). Returning a bare model instance leaves `reference.contextWindowTokens`
+// undefined, which freezes eve's compaction-threshold rescale. The app now wraps THIS FUNCTION'S
+// RETURN — every path of it, at one site — in eve's selection form
+// `{ model, modelContextWindowTokens, modelOptions }` (agent/agent.ts primaryModelSelection), so
+// the window rides every selection. That wrap deliberately lives at the `step.started` boundary
+// and NOT in here: this module is generic core over `RoutableModel`, and threading a selection
+// type through six return paths is exactly the shape in which one path silently forgets it.
+// Keep returning bare `TModel` here.
+import { modelRouteFor, domainMatchFor, reasoningCeilingFor, domainForChannel, criteriaDomain } from "../memory/domain.js";
+import { getConfig } from "../access/config.js";
+import { domainKeyOf, resolvePartition } from "../memory/partition.js";
+import { bindFrom, deploymentOrg } from "../identity/binding.js";
+// A LEAF import: access/worker-seat-state.ts reaches only `eve/context`, so it closes no cycle here.
+import { currentWorkerWake } from "../access/worker-seat-state.js";
+import { stampModelCall } from "./model-stamp.js";
+import { noteTurnStep, reportStepBoundary, withWrapUpNotice, turnBackstopModel, wrapUpNotice, boundaryStopReply } from "./step-boundary.js";
+import { applyModelPolicyToRoute } from "./policy.js";
+import { getOperationalStore } from "../operational/provider.js";
+import { isDmAnchorWindowToken, isSupervisorShapedToken } from "../channels/window-key.js";
+// The per-routine model role's ONE reader (OPE-1627). `routines/routine.ts` is framework-free and
+// imports nothing from this plane, so the edge is one-way and no cycle can form through it.
+import { routineModelRoleStamped } from "../routines/routine.js";
+import { captureArmed, captureSiteFrom, noteUncalledModelStep, withCapture } from "./call-capture.js";
+import { withStreamDropRetry } from "./stream-drop-retry.js";
+import { abBucketKey, abThreadKey, applyModelAb, decideModelAb, modelAbTestArmed, noteModelAbArm, readModelArm, registeredModelAbTest, resolveModelArm, stampModelArm, } from "./ab-test.js";
+// Why-null / warning diagnostics, logged once per distinct reason per instance so a broken
+// resolution is still diagnosable without spamming the log on every turn.
+const loggedOnce = new Set();
+function logOnce(kind, reason) {
+    if (loggedOnce.has(reason))
+        return;
+    loggedOnce.add(reason);
+    (kind === "warn" ? console.warn : console.log)(`[open-everywhere:model-routing] ${reason}`);
+}
+// How long a resolved domain-model pick is trusted before the next read re-hits the store.
+// The primary resolver runs once per turn and reads the pick for its domain twice (once per
+// role — primary and the stamped utility, which share a domainName), so this memo lets the
+// second read reuse the first within a turn; 15s is short enough that an admin's
+// set_domain_model takes effect within roughly one turn's latency. A FAILED read is never
+// cached (see liveDomainModelPick) — only a successful resolution (including an explicit
+// "no pick") is memoized, so a transient store outage recovers as soon as it clears.
+const DOMAIN_MODEL_PICK_TTL_MS = 15_000;
+const domainModelPickCache = new Map();
+/** Cached read of one domain's runtime model pick, keyed by (org, domainName). Fail-soft
+ *  at the caller (liveIdentity.domainModelPick) — a store throw here propagates up and is
+ *  swallowed there, never cached, so the next call retries rather than sticking with a
+ *  stale failure. */
+async function liveDomainModelPick(org, domainName) {
+    const key = `${org} ${domainName}`;
+    const now = Date.now();
+    const cached = domainModelPickCache.get(key);
+    if (cached && cached.expiresAt > now)
+        return cached.value;
+    const row = await getOperationalStore().getDomainModel(org, domainName);
+    const value = row ? { modelId: row.modelId, reasoning: row.reasoning } : null;
+    domainModelPickCache.set(key, { value, expiresAt: now + DOMAIN_MODEL_PICK_TTL_MS });
+    return value;
+}
+/**
+ * The live config/identity seams — how the router learns the DOMAINS/ROLES/POLICY and the
+ * runtime DB pick. (The CALLER identity is no longer a seam here — it comes from the
+ * harness ctx handed to the resolver.) Exported so an adapter package can compose these
+ * with its backend without re-reaching into the config registry.
+ */
+export const liveIdentity = {
+    domains: () => getConfig().loadDomains(),
+    roles: () => getConfig().loadRoles?.() ?? [],
+    modelPolicy: () => getConfig().loadModelPolicy?.(),
+    modelAbTest: () => registeredModelAbTest(),
+    domainModelPick: async (domainName) => {
+        try {
+            return await liveDomainModelPick(deploymentOrg(), domainName);
+        }
+        catch {
+            return null; // fail-soft — a store failure never blocks the model call, git route stands
+        }
+    },
+};
+/**
+ * The surface identity a model call routes by, reconstructed from the harness-supplied
+ * ctx (DynamicResolveContext, structurally a BindableContext). DOMAIN grain (domainKeyOf):
+ * model routes are declared per domain CHANNEL, so a Discord thread routes via its parent
+ * channel (item 22); everywhere else the domain key IS the surface key. Throws only on a
+ * structurally broken ctx — the caller (resolvePrimaryModel) treats any throw as fail-soft.
+ */
+function identityFromContext(ctx) {
+    const surfaceKey = domainKeyOf(resolvePartition(ctx));
+    let surfaceMatch;
+    try {
+        const b = bindFrom(ctx);
+        surfaceMatch = domainMatchFor(b.mode, b.trust);
+    }
+    catch {
+        surfaceMatch = undefined; // criteria layer simply not consulted — org ← explicit only
+    }
+    return { surfaceKey, surfaceMatch };
+}
+/**
+ * Apply the GENERIC route fields to one call: pick the model id and override
+ * `reasoning` (a spec-level AI SDK call option, backend-independent). Provider hints
+ * are then mapped by the backend's applyOptions. Pure — exported for tests.
+ */
+export function applyRoute(route, options, defaultId) {
+    const id = route.id ?? defaultId;
+    return {
+        id,
+        options: route.reasoning !== undefined ? { ...options, reasoning: route.reasoning } : options,
+    };
+}
+/**
+ * Resolve the fully-enveloped ModelRoute for one (role, surface) — the routing DECISION,
+ * with NO transport/backend involvement (returns a plain route object). Resolution order,
+ * all allow-list-clamped by the envelope:
+ *   concrete runtime pick (DomainModelPick) > concrete git-config route id > role/domain
+ *   tier (ModelTier) > fallback.
+ * The optional `ab` argument adds ONE rung under all of those (model/ab-test.ts, OPE-34): when the
+ * route names NO MODEL AND NO TIER of its own — so it would run the deployment default — and the
+ * conversation's bucket falls inside the declared percentage, the challenger id is substituted
+ * BEFORE the envelope. It never overrides a concrete pin or a tier, and the envelope still clamps it.
+ * FAIL-SOFT throughout: any failure resolves to `{}` (→ the caller's default model with
+ * backend static defaults), logged once. Exported for tests and for the compaction slot's
+ * own utility resolution.
+ */
+export async function resolveRoute(role, surfaceKey, surfaceMatch, defaultId, deps, fallbackRole, ab) {
+    try {
+        const domains = deps.domains();
+        const roles = deps.roles?.() ?? [];
+        // `fallbackRole` (used for the `supervisor` role): when THIS role has no configured route
+        // anywhere in the layer merge, resolve `fallbackRole` instead — so a supervisor session in
+        // a channel with no `supervisor` route behaves EXACTLY like a `primary` turn (the change is
+        // inert until a domain routes `supervisor`). Checked on the raw merged route, before the
+        // runtime pick / envelope, since those are role-agnostic and would otherwise mask "unset".
+        let rawRoute = modelRouteFor(role, surfaceKey, domains, roles, surfaceMatch);
+        if (fallbackRole !== undefined && routeUnset(rawRoute)) {
+            rawRoute = modelRouteFor(fallbackRole, surfaceKey, domains, roles, surfaceMatch);
+        }
+        // The runtime DOMAIN pick overlay (control/writes.ts set_domain_model): a domain admin's
+        // self-serve choice, layered BETWEEN the git route and the envelope clamp below — so a
+        // pick still passes through applyModelPolicyToRoute exactly like the git route always did
+        // (defence in depth: the write tool already validated the pick against the envelope at SET
+        // time, but the envelope may have narrowed since). `domainName` is the SAME single-hop
+        // resolution spend/caps.ts's domainNameForScope uses (explicit domain, else the dm/public
+        // criteria domain — `org` is deliberately not pick-able). Its own try/catch so a broken
+        // pick read loses only the pick, never the whole route.
+        let pickedRoute = rawRoute;
+        try {
+            const domainName = domainForChannel(surfaceKey, domains)?.name ?? (surfaceMatch ? criteriaDomain(surfaceMatch, domains)?.name : undefined);
+            if (domainName !== undefined) {
+                const pick = await deps.domainModelPick?.(domainName);
+                if (pick && (pick.modelId !== undefined || pick.reasoning !== undefined)) {
+                    pickedRoute = {
+                        ...rawRoute,
+                        // A picked modelId is a concrete id — drops any inherited `tier`, same
+                        // mutual-exclusion convention as ModelRoute.tier/modelRouteFor.
+                        ...(pick.modelId !== undefined ? { id: pick.modelId, tier: undefined } : {}),
+                        ...(pick.reasoning !== undefined ? { reasoning: pick.reasoning } : {}),
+                    };
+                    logOnce("log", `${role}: domain "${domainName}" runtime pick → ${JSON.stringify(pick)}`);
+                }
+            }
+        }
+        catch (err) {
+            pickedRoute = rawRoute; // fail-soft — a broken pick read never blocks the call, git route stands
+            logOnce("warn", `${role}: domain model pick lookup failed (${String(err)})`);
+        }
+        // THE A/B ARM (model/ab-test.ts, OPE-34) — layered here, BETWEEN the runtime pick and the
+        // envelope, for the same reason the pick is: the substitution is a routing preference and must
+        // still pass the org's model-policy clamp below. `decideModelAb` returns undefined (no
+        // experiment on this route) whenever the test is unarmed OR the route already pins a concrete
+        // model other than the champion — a pin somebody made deliberately is never overruled. Only the
+        // PRIMARY role is ever handed an `ab` argument (see resolveRoutedPrimaryModel), so a supervisor
+        // or utility resolution is untouched.
+        const abDecision = ab ? decideModelAb(pickedRoute, defaultId, ab) : undefined;
+        const armedRoute = applyModelAb(pickedRoute, abDecision);
+        // The model-policy ENVELOPE (model/policy.ts): resolve a `tier` against the org
+        // allow-list, clamp `reasoning` to the per-domain-resolved ceiling, and fail-soft-
+        // substitute a safe model if the resolved id is somehow outside the allow-list /
+        // provider-denied. A dep that omits `modelPolicy` reproduces exactly the pre-envelope
+        // route unchanged (see RoutingDeps.modelPolicy).
+        let policy;
+        try {
+            policy = deps.modelPolicy?.();
+        }
+        catch {
+            policy = undefined;
+        }
+        // The effective reasoning ceiling for THIS surface: the org policy default, raised or
+        // lowered by any domain-layer `reasoningCeiling` (reasoningCeilingFor). Only resolved
+        // when a policy exists (no policy → no clamp at all, backward-compat).
+        let effectiveCeiling;
+        if (policy) {
+            try {
+                effectiveCeiling = reasoningCeilingFor(surfaceKey, domains, roles, surfaceMatch, policy.reasoningCeiling ?? "medium");
+            }
+            catch {
+                effectiveCeiling = undefined;
+            }
+        }
+        // `defaultId` is passed TWICE, as two different claims. As the 3rd argument it is the
+        // last-resort id (what runs when the policy can offer nothing). As `preferredId` it is the
+        // stronger claim this resolver is entitled to make and a bare policy caller is not: it is
+        // THIS ROLE'S OWN configured model (resolvePrimaryModel hands the primary/utility/supervisor
+        // slots their own role's id), so a fail-soft substitution should land there rather than on
+        // whatever the allow-list happens to list cheapest — which, on an allow-list derived from the
+        // roles, can be the vision describer rather than a turn model.
+        const enveloped = applyModelPolicyToRoute(armedRoute, policy, defaultId, effectiveCeiling, defaultId);
+        for (const w of enveloped.warnings)
+            logOnce("warn", `${role}: model policy: ${w}`);
+        // BUILD-PHASE HARD PIN (Tommy 2026-07-17): OE_FORCE_MODEL, when set, forces EVERY resolved route
+        // onto ONE model id — winning over a domain's concrete `id` pin, the runtime domain pick, and the
+        // envelope alike (all applied above; this is the last word). A blunt "pin the whole org to one
+        // model for now" knob, DISTINCT from OE_PRIMARY_MODEL, which is only the DEFAULT id and LOSES to a
+        // domain's concrete pin (e.g. a `supervisor: { id: glm }`). Only the model id is pinned —
+        // `reasoning`/`providers` and the ceiling clamp are untouched; `tier` is dropped (a concrete id and
+        // a tier are mutually exclusive, same convention as the runtime pick). Unset to restore per-domain routing.
+        const forcedId = process.env.OE_FORCE_MODEL?.trim();
+        const route = forcedId
+            ? { ...armedRoute, id: forcedId, tier: undefined, reasoning: enveloped.reasoning }
+            : { ...armedRoute, id: enveloped.id, reasoning: enveloped.reasoning };
+        // 🔴 THE ARM IS STAMPED FROM WHAT RESOLVED, NEVER FROM WHAT THE BUCKET ASKED FOR. A challenger
+        // the envelope substituted away — or `OE_FORCE_MODEL` pinned over — ran the champion, and the
+        // `usage_events` row and the audit row must say champion. `resolveModelArm` is that comparison; see
+        // model/ab-test.ts. Fail-soft by construction (stampModelArm no-ops outside a session).
+        if (abDecision !== undefined) {
+            const ranId = route.id ?? defaultId;
+            stampModelArm({ arm: resolveModelArm(abDecision, ranId), bucketKey: abDecision.bucketKey, modelId: ranId });
+        }
+        // Observability: a route that actually overrides something is logged once per
+        // surface+shape per instance — the positive signal that per-domain routing is live.
+        if (route.id !== undefined || route.reasoning !== undefined || route.providers !== undefined) {
+            logOnce("log", `${role}: ${surfaceKey} → ${JSON.stringify(route)}`);
+        }
+        return route;
+    }
+    catch (err) {
+        logOnce("warn", `${role}: domain config unavailable (${String(err)}) — default model`);
+        return {};
+    }
+}
+/** Whether a resolved route asks for nothing beyond the default model (no id change, no
+ *  reasoning/providers/tier override) — the primary resolver returns `null` for these so
+ *  eve uses its static fallback directly instead of a redundant wrapper. */
+function isNoOpRoute(route, defaultId) {
+    return (route.id ?? defaultId) === defaultId && route.reasoning === undefined && route.providers === undefined && route.tier === undefined;
+}
+/** Whether a merged role route (modelRouteFor's output) is entirely UNSET — no layer named
+ *  this role at all. Used by resolveRoute's `fallbackRole` seam: an all-undefined route means
+ *  "nothing configured this role", so fall back to another role's route. (Distinct from
+ *  isNoOpRoute, which is about "resolves to the default model" AFTER the envelope.) */
+function routeUnset(route) {
+    return route.id === undefined && route.tier === undefined && route.providers === undefined && route.reasoning === undefined;
+}
+// The channel-supervisor session's reserved continuation token embeds the `oe-sup:g<gen>`
+// sentinel (channels/slack-events.ts supervisorSentinel / supervisorToken:
+// `${channelId}:oe-sup:g<gen>` via slackContinuationToken). eve hands that token to the
+// step.started resolver as `ctx.channel.continuationToken` (context/dynamic-resolve-context),
+// so a supervisor session is identifiable HERE without any channel-code import. The sentinel
+// can never collide with a real Slack thread ts, so a match is unambiguous. Mirror any change
+// to the sentinel format in slack-events.ts here.
+//
+// UNIFIED cross-surface supervisor: the domain-keyed
+// token `oe-dom:<domain>:oe-sup:g<gen>` (channels/unified-supervisor.ts unifiedSupervisorToken) ALSO
+// ends in `:oe-sup:g<gen>`, so the classifier matches it UNCHANGED — a unified supervisor session
+// resolves the cheap `supervisor` ModelRole exactly like a per-container one. The surface routing
+// (identityFromContext → domainKeyOf) still reads the WOKEN message's real channel off the delivery
+// auth, so per-domain model routing resolves the right domain regardless of which surface a wake
+// arrived on.
+//
+// The old anchored regex `SUPERVISOR_TOKEN_RE = /(?:^|:)oe-sup:g\d+$/` is now the codec's
+// `isSupervisorShapedToken` (channels/window-key.ts) — kind ∈ {window, task, thread-seat,
+// container-supervisor}, byte-identical to the regex over every real + malformed token shape it was
+// ever asked to classify (pinned by scripts/session-id-codec-test.ts), with ONE DELIBERATE widening:
+// OPE-58's `g<n>-<sha>` rotation salt is a genuinely NEW, additive suffix form the old regex never
+// saw — the codec accepts it (still resolves `supervisor`), the old bare oracle would have rejected
+// it (see session-id-codec-test.ts PART 7). Do NOT reintroduce a local regex here.
+/**
+ * Is this a channel-supervisor session (→ resolve the `supervisor` ModelRole, the cheap
+ * ambient tier)? True iff the resolver ctx carries a supervisor-SHAPED continuation token (any
+ * OE-structured standing/task/thread/window token). Fail-soft: any missing/odd ctx shape → false
+ * (a normal turn), never throws.
+ *
+ * 🔴 ONE SUBTRACTION FROM "SUPERVISOR-SHAPED": A DM WINDOW (OPE-351). Stage 2 re-seats a DM on a
+ * degenerate window token over the `oe-dm/<surfaceKey>` pseudo-domain, which IS supervisor-shaped —
+ * so without this arm, giving a DM a rotatable window would silently demote every DM turn to the
+ * cheap ambient tier. That is exactly the hazard channels/window-key.ts's dm-seat section already
+ * closed once for the OPE-90 token (`:oe-dm:g` was chosen INERT to every `:oe-sup:g` detector for
+ * this reason): a DM is a person talking to the agent one-to-one, the highest-intent traffic there
+ * is, and it must route to the PRIMARY model. Re-seating it must not undo that ruling.
+ *
+ * WHY HERE AND NOT IN {@link isSupervisorShapedToken}. That predicate is the BROAD "is this an
+ * OE-structured session" test, and the spend counter, the rotation machinery and the registry-key
+ * derivation all want a DM window inside it — a DM window has a real `channel_session` row and a real
+ * generation to bump. Narrowing the codec would break those. The exclusion belongs to the ROLE
+ * question alone, which is this function.
+ *
+ * IT IS ALSO THE RIGHT ANSWER FOR THIS FUNCTION'S OTHER TWO CONSUMERS, which is why it sits here
+ * rather than in resolvePrimaryModel: `renderSupervisorPersona` (instructions/access.ts) and the
+ * mid-session memory re-sync arming (hooks/memory.ts) both key off "is this an ambient supervisor
+ * seat". A DM is not one — it is an addressed 1:1 conversation — and today's native-token DM answers
+ * false for all three. So the exclusion PRESERVES the DM's current posture across the re-seat rather
+ * than changing it, which is the property that makes stage 2 a re-key and not a behaviour change.
+ *
+ * THE ARM FIRES ON EVERY DM WAKE. `channels/dm-seat.ts` `getOrCreateDmSeat` mints the DM seat's token
+ * as `saltSupervisorGeneration(formatWindowToken(dmWindowKey(…)))`, and the Slack, Teams and Discord
+ * DM legs divert each wake onto it — so this is the routing answer a live DM reads. A
+ * DM-anchored WORKER (a `t/` task token on the same pseudo-domain, OPE-306 — which DOES exist today)
+ * is deliberately NOT excluded: it is supervisor-shaped now, it resolves the supervisor role now, and
+ * nothing here changes that. {@link isDmAnchorWindowToken} is standing-grain-only precisely so this
+ * arm cannot reach it.
+ */
+export function isSupervisorSession(ctx) {
+    const token = ctx.channel?.continuationToken;
+    if (isDmAnchorWindowToken(token))
+        return false;
+    return isSupervisorShapedToken(token);
+}
+/**
+ * A per-selection routed model: bakes in a resolved route (via the `getRoute` thunk) and
+ * applies it on each call — id selection + reasoning override (applyRoute) then the
+ * backend's provider-option mapping. NO identity work at call time (the route is a closure
+ * constant / a per-session stamp read). Identity/properties mirror the default inner model;
+ * `do*` delegate with rewritten options. Inner models are memoized per id.
+ *
+ * Used for the primary selection (getRoute = the route resolved from ctx).
+ */
+export function makeRoutedModel(getRoute, defaults, backend) {
+    const inner = new Map();
+    const modelFor = (id) => {
+        let m = inner.get(id);
+        if (!m) {
+            m = backend.model(id);
+            inner.set(id, m);
+        }
+        return m;
+    };
+    const dispatch = (options) => {
+        const route = getRoute();
+        const generic = applyRoute(route, options, defaults.id);
+        const mapped = backend.applyOptions(route, generic.options, { id: generic.id, defaultId: defaults.id });
+        // Stamp the id THIS call resolved to (model-stamp.ts) — hooks/spend.ts reads it back
+        // when the following step.completed fires, so the usage_events row carries an EXACT
+        // model. Fail-soft (no-op outside a session) — never blocks the model call.
+        stampModelCall(generic.id);
+        return { model: modelFor(generic.id), options: mapped };
+    };
+    const fallback = modelFor(defaults.id);
+    const routed = {
+        specificationVersion: fallback.specificationVersion,
+        provider: fallback.provider,
+        modelId: defaults.id,
+        supportedUrls: fallback.supportedUrls,
+        async doGenerate(options) {
+            const d = dispatch(options);
+            return d.model.doGenerate(d.options);
+        },
+        async doStream(options) {
+            const d = dispatch(options);
+            return d.model.doStream(d.options);
+        },
+    };
+    return routed;
+}
+/**
+ * The primary (turn) model resolver core: reconstruct the surface from the harness ctx,
+ * resolve the primary route, STAMP the utility route (same identity, for the compaction
+ * slot which has no ctx of its own) AND stamp the resolved primary model id for per-row
+ * cost attribution, and return a per-selection routed model — or the DEFAULT model, built
+ * concretely, when the surface routes to nothing. NEVER returns null (OPE-412 — see the
+ * module header for why, and why it is behaviour-preserving) and NEVER throws (a thrown
+ * resolver breaks the turn); every failure path resolves to the default model at
+ * `defaults.primary.id` and stamps a cleared utility route.
+ *
+ * WHY THE RESOLVER STAMPS THE PRIMARY ID (not just the wrapper's dispatch): the resolver
+ * runs inside the harness-supplied step context — the SAME per-session state container the
+ * spend hook (hooks/spend.ts, `step.completed`) reads back with readModelStamp(). Stamping
+ * here makes the usage_events model column correct even for the NO-OP/default path (no
+ * wrapper is built, so dispatch never runs) and even if the AI SDK were to run the wrapper's
+ * doGenerate outside the resolver's async context. Fail-soft: stampModelCall no-ops outside a
+ * session (model-stamp.ts). The id stamped is exactly what the call will run: the enveloped
+ * `route.id` (or the default when the route names none), matching the dispatch's applyRoute.
+ *
+ * Wire as the `step.started` handler of `defineDynamic({ fallback, events })` on the agent
+ * `model` field (normally via an adapter convenience, e.g. the gateway backend's
+ * `gatewayModelResolver`). NOTE: it MUST be `step.started`, not `turn.started` — eve rejects
+ * a model-INSTANCE return at session/turn scope (see the module header). At `turn.started`
+ * eve discards the wrapper, routing goes dead, and no row is ever stamped.
+ *
+ * THE PER-TURN STEP BOUNDARY WRAPS THIS (model/step-boundary.ts, OPE-407) — see the exported
+ * {@link resolvePrimaryModel} just below. Everything in here is pure ROUTING; the boundary is
+ * counted before any of it runs, so no routing outcome can bypass it.
+ */
+async function resolveRoutedPrimaryModel(ctx, defaults, deps, event) {
+    // 🔴 CLEAR ANY ARM THIS SESSION STAMPED ON AN EARLIER TURN — FIRST, BEFORE EVERY OTHER LINE. The
+    // slot is per-SESSION and a session outlives a turn, so without this a room that ran one armed
+    // turn would keep reporting that arm forever: on turns the experiment stopped covering, on turns
+    // after the operator switched it off, and — the reason this sits ABOVE the try below rather than
+    // after it — on every fail-soft path here, each of which returns the DEFAULT model while an
+    // uncleared slot would still say `challenger`. That row would contradict its own `model` column.
+    // `resolveRoute` re-stamps when a decision applies; a turn with no decision records no arm.
+    stampModelArm(null);
+    let surfaceKey;
+    let surfaceMatch;
+    try {
+        const id = identityFromContext(ctx);
+        surfaceKey = id.surfaceKey;
+        surfaceMatch = id.surfaceMatch;
+    }
+    catch (err) {
+        logOnce("warn", `primary: surface unbindable from ctx (${String(err)}) — default model, routing inactive`);
+        stampModelCall(defaults.primary.id); // the default model runs → price the row as the default
+        return deps.backend.model(defaults.primary.id);
+    }
+    // Resolve the turn route and wrap it (unless it's a no-op → fallback). A channel-SUPERVISOR
+    // session (identified by its reserved continuation token) resolves the `supervisor` role —
+    // the cheap ambient tier — instead of `primary`, falling back to `primary` when no supervisor
+    // route is configured (so the role is inert until a domain routes it). A normal thread/turn
+    // session resolves `primary` exactly as before. Both share the same static default id.
+    const supervisor = isSupervisorSession(ctx);
+    // THE PER-ROUTINE MODEL ROLE (OPE-1627) — a routine that named one resolves THAT role instead,
+    // and it wins over the supervisor branch above.
+    //
+    // 🔴 IT HAS TO WIN, AND THE REASON IS MEASURED. A routine fire that goes through the unified
+    // window carries a window token, and `isSupervisorSession` answers TRUE for one — so such a fire
+    // already resolves `supervisor` today while a native-path fire of the same routine resolves
+    // `primary`. Reading the stamp after that branch would leave the operator's declared choice
+    // silently overridden on exactly one of the two delivery paths, which is the shape of bug this
+    // field exists to remove rather than add.
+    //
+    // 🔴 UNDEFINED IS INHERIT, and every failure lands there. The stamp is host-set off the stored row
+    // (routines/fire-auth.ts) and re-validated by `routineModelRoleStamped`, so an absent, unknown or
+    // hand-set value leaves this line resolving what it resolved before the field existed. The
+    // fallback role stays `primary` for the same reason the supervisor branch's does: a role the
+    // deployment routes nowhere is INERT, never a downgrade and never an error.
+    let routineRole;
+    try {
+        // `current ?? initiator` is the SAME precedence identity/binding.ts's own `authOf` reads the
+        // bag under; that helper is module-private, and a routing-side copy of two field names is
+        // cheaper than widening the identity layer's surface for one reader.
+        const auth = ctx.session?.auth?.current ?? ctx.session?.auth?.initiator ?? undefined;
+        routineRole = routineModelRoleStamped(auth?.attributes);
+    }
+    catch (err) {
+        logOnce("warn", `primary: routine model-role stamp unreadable (${String(err)}) — inherit`);
+    }
+    /** The role THIS turn resolves. With no routine stamp it is exactly what the two branches above
+     *  always produced, which is what makes the field inert until a routine names one. */
+    const effectiveRole = routineRole ?? (supervisor ? "supervisor" : "primary");
+    // THE A/B INPUT (OPE-34), built ONLY for a turn that resolves the PRIMARY role.
+    //
+    // 🔴 THE EXCLUDED SET IS EVERY OE-STRUCTURED SEAT, not just the ambient supervisor. `supervisor`
+    // here is `isSupervisorSession`, which is `isSupervisorShapedToken` minus the DM anchor — window,
+    // task, thread-seat AND container-supervisor tokens all answer true (channels/window-key.ts). So a
+    // `t/` task WORKER is excluded too, and a person can read a worker's answer. Those turns are out
+    // of the experiment because they resolve the `supervisor` ModelRole, not the champion, so
+    // substituting the challenger there would compare the challenger against whatever the supervisor
+    // route resolved rather than against the champion. Naming the set exactly matters downstream:
+    // `/oe rate` in such a room finds no arm row, and its reply must not claim the test is off.
+    //
+    // Unarmed (or undeclared) ⇒ `undefined`, and `resolveRoute` then behaves exactly as it did before
+    // this feature existed.
+    let ab;
+    try {
+        const test = deps.modelAbTest?.();
+        // The test is keyed on `effectiveRole`, not on `supervisor`, so a routine that named a role
+        // other than `primary` is out of the experiment for the SAME reason a supervisor-shaped seat
+        // is: it does not resolve the champion, so substituting the challenger there would compare the
+        // challenger against whatever that role routed. A routine naming `primary` stays in.
+        if (effectiveRole === "primary" && modelAbTestArmed(test))
+            ab = { test, bucketKey: abBucketKey(surfaceKey, abThreadKey(ctx)) };
+    }
+    catch (err) {
+        logOnce("warn", `primary: model A/B test read failed (${String(err)}) — no arm`);
+    }
+    let route;
+    try {
+        route =
+            effectiveRole === "primary"
+                ? await resolveRoute("primary", surfaceKey, surfaceMatch, defaults.primary.id, deps, undefined, ab)
+                : await resolveRoute(effectiveRole, surfaceKey, surfaceMatch, defaults.primary.id, deps, "primary");
+    }
+    catch (err) {
+        logOnce("warn", `primary: route resolution failed (${String(err)}) — default model`);
+        stampModelCall(defaults.primary.id); // fail-soft → the default model runs; price the row as the default
+        return deps.backend.model(defaults.primary.id);
+    }
+    // Stamp the id the call WILL run — for both the default/no-op path (no wrapper is built) and
+    // the routed path (the wrapper's dispatch re-stamps the same id). This is the guaranteed
+    // per-row cost attribution point; see the doc above.
+    stampModelCall(route.id ?? defaults.primary.id);
+    // THE A/B AUDIT ROW (OPE-34) — one row per armed TURN, written from the stamp `resolveRoute`
+    // just wrote, so the audit row and the `usage_events` row can never disagree about the arm. A no-op on
+    // every deployment that has not armed the experiment (nothing stamped ⇒ nothing written), and
+    // best-effort throughout: it never throws and never blocks the model call.
+    noteModelAbArm(ctx, readModelArm(), event);
+    // A no-op route asks for nothing beyond the default (isNoOpRoute: same id, no reasoning/
+    // providers/tier), so skip the wrapper and hand back the bare default model — same id, same
+    // options, one less indirection.
+    if (isNoOpRoute(route, defaults.primary.id))
+        return deps.backend.model(defaults.primary.id);
+    return makeRoutedModel(() => route, defaults.primary, deps.backend);
+}
+/**
+ * THE `step.started` PRIMARY-MODEL RESOLVER — per-domain routing (above) with the PER-TURN STEP
+ * BOUNDARY in front of it (model/step-boundary.ts, OPE-407, which retired the `__oeCeil*` half of
+ * the eve byte-patch). Wire this, not {@link resolveRoutedPrimaryModel}.
+ *
+ * 🔴 THE BOUNDARY IS COUNTED FIRST, BEFORE ANY ROUTE RESOLUTION. Every failure path in the routing
+ * half degrades to the DEFAULT model, so a guard placed after resolution would be skipped on
+ * exactly the paths most likely to accompany a spiral (an unbindable ctx, a broken route read).
+ * Counting first means no routing outcome — routed, no-op or fail-soft — can bypass it. This
+ * ordering IS the guarantee; do not move the call.
+ *
+ * The two tiers (see step-boundary.ts for the full rationale):
+ *   SOFT — past `turn.stepBudget`, the resolved model is wrapped so every call carries a wrap-up
+ *     instruction. The turn is not killed and the model keeps its agency. The routing half always
+ *     hands back a concrete model — the DEFAULT one on the no-op/fail-soft path (OPE-412) — so the
+ *     notice cannot be dodged by an unrouted surface.
+ *   HARD — past `budget × turn.stepBackstopMultiple`, a text-only stub replaces the model entirely.
+ *     It makes no network call, so a runaway stops costing immediately, and its tool-call-free
+ *     assistant message ends the turn through eve's OWN continue-decision.
+ *   CLOSED — the turn had already closed its reply obligation and the host refused its next attempt
+ *     to speak (OPE-1520). The SAME text-only stub ends the turn, one round-trip after the refusal
+ *     rather than at round-trip 121, so a background worker the turn dispatched starts at once.
+ *     Independent of the round-trip count and of whether the step budget is armed at all.
+ *
+ * Still NEVER throws (the fail-soft contract the routing half documents) — every step-boundary
+ * entry point swallows its own failures and degrades to "no boundary".
+ *
+ * `event` is the dynamic-model resolver's own first argument, passed through from
+ * `gatewayModelResolver` (packages/adapters/agent/model/gateway.ts) — `noteTurnStep` needs it to
+ * find a turn id at all (OPE-462: `ctx.session.turn` does not exist on the resolver context; the
+ * event's `data.turnId` is the field that does carry one). Optional so the many unit-test callers
+ * that construct their own turn-bearing `ctx` fixture keep working unchanged.
+ */
+export async function resolvePrimaryModel(ctx, defaults, deps, event) {
+    // 🔴 OPE-593's `[Agents]` SUBTRACTION USED TO RUN HERE, AND DELIBERATELY NO LONGER DOES.
+    // Through eve 0.47.3 this resolver was handed the tool loop's own turn array as `ctx.messages`,
+    // so an in-place splice here reached the model. eve 0.48.0 builds the model's list through a copy
+    // and a call here became a no-op against the bytes the model receives (OPE-1396). The subtraction
+    // now runs at the eve patch's part-6 seam instead — `access/worker-continuation.ts` installs the
+    // hook and its header carries the measurement. Do not re-add a call here expecting it to work.
+    // AWAITED since OPE-1522: the count and the closeout latch live in a durable per-turn row, so a
+    // turn resumed on a fresh serverless instance continues its count instead of restarting it. The
+    // ordering is unchanged — this is still the FIRST thing the resolver does, before any route
+    // resolution, which is the fail-safe the header above turns on.
+    const boundary = await noteTurnStep(ctx, event);
+    // THE SOAK CAPTURE HOOK (OPE-846), armed by `soak.capture` and OFF on every ordinary deployment.
+    // It decorates the BACKEND rather than the returned model, so every path below — routed wrapper,
+    // no-op default, fail-soft default — is built from a capture-wrapped `backend.model(id)`. That is
+    // the one position that records the bytes the model actually saw: `applyRoute`/`applyOptions` and
+    // the soft wrap-up notice all edit the options OUTSIDE it and flow inward through this seam. When
+    // disarmed `withCapture` returns `deps` unchanged, so the disarmed cost is one boolean read.
+    // See model/call-capture.ts for the sensitivity posture and the cross-check.
+    const captureSite = captureArmed() ? captureSiteFrom(ctx, event) : undefined;
+    const capturingDeps = withCapture(deps, captureSite);
+    // THE DELEGATED WORKER'S ONE STREAM-DROP RETRY (OPE-2132). Armed on the grain-`task` worker bit
+    // alone — `currentWorkerWake()`, the same discriminator every other worker-scoped rule reads, and
+    // strictly narrower than `isSubagentChildContext`, which would buffer subagent children the ticket
+    // never scoped. Wrapped OUTSIDE the capture shim on purpose: a retried attempt is a second model
+    // call and the capture's own cross-check counts calls, so the shim must see both.
+    const retryingDeps = withStreamDropRetry(capturingDeps, currentWorkerWake());
+    // The two TURN-ENDING tiers take one path: both replace the model with the text-only stub, and
+    // they differ only in the text it says (`boundaryStopReply`) and in the audit detail the row
+    // carries. Everything below — the capture excuse, the un-cleared counter, the price stamp — is
+    // true of a closed turn for exactly the reasons it is true of a backstopped one.
+    if (boundary.tier === "hard" || boundary.tier === "closed") {
+        reportStepBoundary(ctx, boundary);
+        // The stub answers from process memory and makes NO network call, so this step completes with
+        // no bytes to capture. Excuse it EXPLICITLY — the capture cross-check must not have to infer
+        // which completed steps were allowed to be missing.
+        noteUncalledModelStep(captureSite);
+        // 🔴 The counter is NOT cleared here, unlike the patched loop's `on trip, delete` behaviour.
+        // A cleared counter would let a turn that somehow continued past the stub start the whole
+        // budget again — i.e. the one case the backstop exists for is the one case a reset would
+        // re-arm. Once a turn is past the backstop it stays past it; the LRU bound in
+        // step-boundary.ts is what keeps the map from growing.
+        // Price the (never-sent) call as the default, exactly like every other fallback path here.
+        stampModelCall(defaults.primary.id);
+        // Deliberately the UNDECORATED backend: the stub never calls this inner model, so a capture
+        // shim here would only allocate and mislead the next reader.
+        return turnBackstopModel(deps.backend.model(defaults.primary.id), boundaryStopReply(boundary));
+    }
+    const routed = await resolveRoutedPrimaryModel(ctx, defaults, retryingDeps, event);
+    if (boundary.tier !== "soft")
+        return routed;
+    reportStepBoundary(ctx, boundary);
+    // `routed` is always concrete now (OPE-412) — on the no-op/fail-soft path it IS
+    // `deps.backend.model(defaults.primary.id)`, which is what this used to substitute via `??`.
+    return withWrapUpNotice(routed, wrapUpNotice(boundary));
+}
+// There is deliberately NO compaction-model wrapper here, and no per-session utility stamp to
+// feed one. eve resolves an authored `defineAgent.compaction.model` by re-loading agent.ts and
+// reading its AGENT-LEVEL `model` field, so a wrapper INSTANCE in that slot is never reached and
+// kills the turn while that field is dynamic (OPE-670). Compaction summarises with the live turn
+// model, which `resolvePrimaryModel` above has already routed.
+//# sourceMappingURL=routing.js.map