@aitne/daemon 0.1.7 → 0.1.9

package/dist/api/routes/schedule-model-resolver.d.ts

@@ -0,0 +1,152 @@
+import type { BackendId } from "@aitne/shared";
+import { type AgentErrorIssue } from "../helpers/agent-errors.js";
+import { type ModelRegistrySnapshot } from "./schedule-validation.js";
+/**
+ * Phase D bridge between `validateModelToken` (Phase B helper, returns
+ * a discriminated union over the four resolution kinds) and the
+ * schedule routes' INSERT/UPDATE call sites. Encapsulates:
+ *
+ *   1. The tier ↔ model mutual-exclusion check
+ *      (`schedule.tier_and_model_conflict`).
+ *   2. The §4.3 persistence rule — only one of
+ *      `(tier_override)` / `(model, backend_id)` is non-NULL on any
+ *      row; the alias path persists `tier_override` and clears both
+ *      `(model, backend_id)`, the registered-model path does the
+ *      opposite, and pure-tier rows leave both NULL except for
+ *      `tier_override`.
+ *   3. The §5.0.5 deprecation warning channel — registered-but-
+ *      deprecated ids still persist, but the route emits a
+ *      `schedule.model_deprecated` warning carrying the non-deprecated
+ *      replacements so the next LLM turn can refine.
+ *
+ * Kept as a separate module from `agent-schedule.ts` so the same
+ * resolution logic powers the three schedule call sites (POST,
+ * POST batch row, PATCH) and the recurring routes via one consistent
+ * code path. Pure module — no DB, no I/O — therefore lands inside the
+ * 100% coverage tier per `vitest.config.ts`.
+ *
+ * See `docs/design/appendices/morning-routine-optimization.md`
+ * §"Error messaging contract" for the issue-shape contract this
+ * helper writes into.
+ */
+/**
+ * Outcome of resolving the (model, tier) pair on a single row.
+ *
+ * Discriminated by `ok`:
+ *   - `ok:true`  — caller persists `(model, tierOverride, backendId)`.
+ *                  `warnings` may be non-empty when the resolved model
+ *                  is registered but flagged deprecated.
+ *   - `ok:false` — caller rejects the row (400 / 422) with `errors[]`.
+ */
+export type ResolveModelResult = {
+    ok: true;
+    model: string | null;
+    tierOverride: "lite" | "medium" | "high" | null;
+    backendId: BackendId | null;
+    warnings: AgentErrorIssue[];
+} | {
+    ok: false;
+    errors: AgentErrorIssue[];
+};
+/**
+ * Resolve a row's `(model, tier)` pair against the live model registry
+ * snapshot. Stateless — call once per row.
+ *
+ * The four `validateModelToken` kinds map onto persistence as
+ * documented in §4.3's table:
+ *
+ *   | kind        | model            | tier_override | backend_id |
+ *   |-------------|------------------|---------------|------------|
+ *   | alias       | NULL             | "medium"/"high" | NULL     |
+ *   | model       | <modelId>        | NULL          | <backendId>|
+ *   | ambiguous   | — (errors[])     | —             | —          |
+ *   | unknown     | — (errors[])     | —             | —          |
+ *
+ * The `tier`-only path (no `model`) falls through with `tierOverride
+ * = tier ?? null`, `model = null`, `backendId = null`. The pure-omit
+ * path (neither field set) returns all-null and the row inherits the
+ * dispatcher's process-key default at fire time.
+ *
+ * `fieldBase` is the JSON-pointer-ish prefix that issues' `field`
+ * paths get rooted at — `"model"` for single-row endpoints,
+ * `"rows[i].model"` for batch rows. `rowIndex` is the integer row
+ * index for batch rows, `null` for single-row endpoints.
+ *
+ * @param model       Caller-supplied token. `undefined` = unset.
+ * @param tier        Caller-supplied tier override. `undefined` = unset.
+ * @param fieldBase   JSON-pointer-ish path the issues' `field` is
+ *                    rooted at. Use `"model"` for /schedule and
+ *                    `"rows[N].model"` for /schedule/batch.
+ * @param tierField   Sibling field path used by the conflict issue's
+ *                    `field` half. `"tier"` for /schedule;
+ *                    `"rows[N].tier"` for the batch path.
+ * @param rowIndex    Integer batch-row index, or `null` outside batch.
+ * @param snapshot    Optional snapshot override (Phase B test surface);
+ *                    defaults to a freshly taken `snapshotModelRegistry()`.
+ */
+export declare function resolveModelToken(args: {
+    model: string | undefined;
+    tier: "lite" | "medium" | "high" | undefined;
+    fieldBase: string;
+    tierField: string;
+    rowIndex: number | null;
+    snapshot?: ModelRegistrySnapshot;
+}): ResolveModelResult;
+/**
+ * PATCH variant — accepts `null` on either field as the explicit
+ * "clear" sentinel. Returns three partial updates the route then
+ * threads into its dynamic-SQL builder:
+ *
+ *   - `model`: present + value means "write this column"; absent
+ *     means "leave the column alone".
+ *   - `tierOverride`: same.
+ *   - `backendId`: same. Always coupled to `model` — either both
+ *     present or both absent.
+ *
+ * The conflict + alias + deprecated-warning rules from
+ * `resolveModelToken` carry over verbatim. PATCH-only differences:
+ *
+ *   - `model: null` clears BOTH `model` and `backend_id`.
+ *   - `model: <token>` with `tier === undefined` leaves the existing
+ *     `tier_override` column untouched. (Equivalent to passing `tier:
+ *     null` and `model: <token>` on the row's prior state — the row's
+ *     prior `tier_override` column may already be NULL because the
+ *     INSERT path normalises one or the other to NULL. If a stray
+ *     row predates this normalisation, the route's `model:<token>`
+ *     branch additionally writes `tier_override = NULL` so the row
+ *     ends up consistent — see the route's UPDATE assembly.)
+ *
+ * Why a separate function: the create path's `model:undefined`
+ * branch falls through to "no pin", but the PATCH path's
+ * `model:undefined` is "no change". Reusing one function would force
+ * either ambiguity (which doesn't survive PATCH `{}`) or a third
+ * sentinel — a separate entry point is cleaner.
+ */
+export type PatchModelResult = {
+    ok: true;
+    /** `present:true, value:null` clears; `present:true, value:<x>` sets; `present:false` leaves untouched. */
+    model: {
+        present: boolean;
+        value: string | null;
+    };
+    tierOverride: {
+        present: boolean;
+        value: "lite" | "medium" | "high" | null;
+    };
+    backendId: {
+        present: boolean;
+        value: BackendId | null;
+    };
+    warnings: AgentErrorIssue[];
+} | {
+    ok: false;
+    errors: AgentErrorIssue[];
+};
+export declare function resolveModelTokenForPatch(args: {
+    model: string | null | undefined;
+    tier: "lite" | "medium" | "high" | null | undefined;
+    fieldBase: string;
+    tierField: string;
+    rowIndex: number | null;
+    snapshot?: ModelRegistrySnapshot;
+}): PatchModelResult;

package/dist/api/routes/schedule-model-resolver.js

@@ -0,0 +1,285 @@
+import { composeIssue, composeWarning, } from "../helpers/agent-errors.js";
+import { snapshotModelRegistry, validateModelToken, } from "./schedule-validation.js";
+/**
+ * For the deprecation warning's `validValues.availableModels`,
+ * project the snapshot's non-deprecated entries for the resolved
+ * backend. Mirrors `simplifyForUnknownPayload` in
+ * `schedule-validation.ts` but per-backend so the agent's retry can
+ * pick a same-backend replacement without browsing the full registry.
+ */
+function nonDeprecatedAvailableModels(snapshot, backendId) {
+    return snapshot.models[backendId]
+        .filter((m) => !m.deprecated)
+        .map((m) => m.id);
+}
+/**
+ * Resolve a row's `(model, tier)` pair against the live model registry
+ * snapshot. Stateless — call once per row.
+ *
+ * The four `validateModelToken` kinds map onto persistence as
+ * documented in §4.3's table:
+ *
+ *   | kind        | model            | tier_override | backend_id |
+ *   |-------------|------------------|---------------|------------|
+ *   | alias       | NULL             | "medium"/"high" | NULL     |
+ *   | model       | <modelId>        | NULL          | <backendId>|
+ *   | ambiguous   | — (errors[])     | —             | —          |
+ *   | unknown     | — (errors[])     | —             | —          |
+ *
+ * The `tier`-only path (no `model`) falls through with `tierOverride
+ * = tier ?? null`, `model = null`, `backendId = null`. The pure-omit
+ * path (neither field set) returns all-null and the row inherits the
+ * dispatcher's process-key default at fire time.
+ *
+ * `fieldBase` is the JSON-pointer-ish prefix that issues' `field`
+ * paths get rooted at — `"model"` for single-row endpoints,
+ * `"rows[i].model"` for batch rows. `rowIndex` is the integer row
+ * index for batch rows, `null` for single-row endpoints.
+ *
+ * @param model       Caller-supplied token. `undefined` = unset.
+ * @param tier        Caller-supplied tier override. `undefined` = unset.
+ * @param fieldBase   JSON-pointer-ish path the issues' `field` is
+ *                    rooted at. Use `"model"` for /schedule and
+ *                    `"rows[N].model"` for /schedule/batch.
+ * @param tierField   Sibling field path used by the conflict issue's
+ *                    `field` half. `"tier"` for /schedule;
+ *                    `"rows[N].tier"` for the batch path.
+ * @param rowIndex    Integer batch-row index, or `null` outside batch.
+ * @param snapshot    Optional snapshot override (Phase B test surface);
+ *                    defaults to a freshly taken `snapshotModelRegistry()`.
+ */
+export function resolveModelToken(args) {
+    const { model, tier, fieldBase, tierField, rowIndex } = args;
+    const snapshot = args.snapshot ?? snapshotModelRegistry();
+    // §4.3 mutual exclusion. Both unset is fine — the row resolves via
+    // process-key defaults. Both set is a hard reject so the row's
+    // intent is unambiguous (the LLM error loop adapts in one retry).
+    if (model !== undefined && tier !== undefined) {
+        return {
+            ok: false,
+            errors: [
+                composeIssue("schedule.tier_and_model_conflict", {
+                    field: fieldBase,
+                    received: { model, tier },
+                    rowIndex,
+                    validValues: {
+                        rule: "specify tier OR model, not both",
+                        tierField,
+                        modelField: fieldBase,
+                    },
+                }),
+            ],
+        };
+    }
+    // Neither set → row inherits dispatcher's process-key default.
+    if (model === undefined && tier === undefined) {
+        return { ok: true, model: null, tierOverride: null, backendId: null, warnings: [] };
+    }
+    // Tier only → store the tier and clear the model pin. `tier` is
+    // guaranteed defined here (the both-undefined case returned above and
+    // the both-defined case errored above), but TS does not propagate that
+    // narrowing through the disjunction — the non-null assertion is the
+    // narrowest fix and keeps the branch count honest.
+    if (model === undefined) {
+        return {
+            ok: true,
+            model: null,
+            tierOverride: tier,
+            backendId: null,
+            warnings: [],
+        };
+    }
+    // Model token present — resolve against the registry.
+    const result = validateModelToken(model, snapshot);
+    switch (result.kind) {
+        case "alias":
+            // Rewrite "sonnet" → tier:medium, "opus" → tier:high. The row
+            // no longer carries the alias verbatim — one canonical form.
+            return {
+                ok: true,
+                model: null,
+                tierOverride: result.tierToken,
+                backendId: null,
+                warnings: [],
+            };
+        case "model": {
+            const warnings = [];
+            if (result.deprecated) {
+                // §5.0.5: registered-but-deprecated stays persisted, surfaces
+                // a warning so the LLM can refine on the next turn. The row
+                // is still load-bearing — recurring rules that pin a known
+                // deprecated id shouldn't die on a registry version bump.
+                warnings.push(composeWarning("schedule.model_deprecated", {
+                    field: fieldBase,
+                    received: model,
+                    rowIndex,
+                    validValues: {
+                        model,
+                        backendId: result.backendId,
+                        availableModels: nonDeprecatedAvailableModels(snapshot, result.backendId),
+                    },
+                }));
+            }
+            return {
+                ok: true,
+                model: result.modelId,
+                tierOverride: null,
+                backendId: result.backendId,
+                warnings,
+            };
+        }
+        case "ambiguous":
+            return {
+                ok: false,
+                errors: [
+                    composeIssue("schedule.model_ambiguous", {
+                        field: fieldBase,
+                        received: model,
+                        rowIndex,
+                        validValues: result.validValues,
+                    }),
+                ],
+            };
+        case "unknown":
+            return {
+                ok: false,
+                errors: [
+                    composeIssue("schedule.model_unknown", {
+                        field: fieldBase,
+                        received: model,
+                        rowIndex,
+                        validValues: result.validValues,
+                    }),
+                ],
+            };
+    }
+}
+export function resolveModelTokenForPatch(args) {
+    const { model, tier, fieldBase, tierField, rowIndex } = args;
+    const snapshot = args.snapshot ?? snapshotModelRegistry();
+    // Conflict check — only triggers when BOTH fields are present AND
+    // non-null. The clear-one-set-the-other PATCH form is the
+    // documented contract for swapping rows from tier-pinned to
+    // model-pinned (and vice-versa) in a single request.
+    if (model !== undefined &&
+        model !== null &&
+        tier !== undefined &&
+        tier !== null) {
+        return {
+            ok: false,
+            errors: [
+                composeIssue("schedule.tier_and_model_conflict", {
+                    field: fieldBase,
+                    received: { model, tier },
+                    rowIndex,
+                    validValues: {
+                        rule: "specify tier OR model, not both",
+                        tierField,
+                        modelField: fieldBase,
+                    },
+                }),
+            ],
+        };
+    }
+    // `tier` partial — pass through verbatim. PATCH semantics: `null`
+    // clears the column; a concrete value sets it; `undefined` leaves
+    // the column alone.
+    const tierPartial = tier === undefined
+        ? { present: false, value: null }
+        : { present: true, value: tier };
+    // `model: undefined` → no change to model / backend_id either.
+    if (model === undefined) {
+        return {
+            ok: true,
+            model: { present: false, value: null },
+            tierOverride: tierPartial,
+            backendId: { present: false, value: null },
+            warnings: [],
+        };
+    }
+    // `model: null` → explicit clear. Both `model` and `backend_id`
+    // get NULLed in the same UPDATE so the dispatcher's override block
+    // doesn't see a half-cleared row.
+    if (model === null) {
+        return {
+            ok: true,
+            model: { present: true, value: null },
+            tierOverride: tierPartial,
+            backendId: { present: true, value: null },
+            warnings: [],
+        };
+    }
+    // Model token set — resolve against the registry. Same four kinds
+    // as the create path; only the persistence wiring differs.
+    const result = validateModelToken(model, snapshot);
+    switch (result.kind) {
+        case "alias":
+            // Setting `model: "sonnet"` on PATCH is equivalent to setting
+            // `tier: "medium"`. Normalise to the canonical form: write
+            // `tier_override`, clear `model` + `backend_id`. If the caller
+            // ALSO supplied `tier`, the conflict block above already fired
+            // (so this branch only fires when `tier === undefined` or
+            // `tier === null` — both of which we override here).
+            return {
+                ok: true,
+                model: { present: true, value: null },
+                tierOverride: { present: true, value: result.tierToken },
+                backendId: { present: true, value: null },
+                warnings: [],
+            };
+        case "model": {
+            const warnings = [];
+            if (result.deprecated) {
+                warnings.push(composeWarning("schedule.model_deprecated", {
+                    field: fieldBase,
+                    received: model,
+                    rowIndex,
+                    validValues: {
+                        model,
+                        backendId: result.backendId,
+                        availableModels: nonDeprecatedAvailableModels(snapshot, result.backendId),
+                    },
+                }));
+            }
+            // Setting a registered model on PATCH always clears any prior
+            // `tier_override` so the row ends up with exactly one pin
+            // (per §4.3 — model+tier never both non-null at rest). The
+            // route forwards `tierOverride: {present:true, value:null}`
+            // when the caller did not supply their own `tier:null`.
+            const explicitTierClear = tier === undefined;
+            return {
+                ok: true,
+                model: { present: true, value: result.modelId },
+                tierOverride: explicitTierClear
+                    ? { present: true, value: null }
+                    : tierPartial,
+                backendId: { present: true, value: result.backendId },
+                warnings,
+            };
+        }
+        case "ambiguous":
+            return {
+                ok: false,
+                errors: [
+                    composeIssue("schedule.model_ambiguous", {
+                        field: fieldBase,
+                        received: model,
+                        rowIndex,
+                        validValues: result.validValues,
+                    }),
+                ],
+            };
+        case "unknown":
+            return {
+                ok: false,
+                errors: [
+                    composeIssue("schedule.model_unknown", {
+                        field: fieldBase,
+                        received: model,
+                        rowIndex,
+                        validValues: result.validValues,
+                    }),
+                ],
+            };
+    }
+}

package/dist/api/routes/schedule-options.d.ts

@@ -0,0 +1,24 @@
+import { Hono } from "hono";
+import type { AgentConfig } from "../../config.js";
+/**
+ * SCHEDULE_API_REDESIGN_PLAN.md §4.4 — read-only discovery endpoint.
+ *
+ * `GET /api/schedule/options` returns every value the LLM needs to
+ * compose a valid POST /api/schedule (or /recurring-schedules) call:
+ * tiers, model aliases, registered models per backend, recurrence
+ * frequencies, day-of-week labels, time format, and the configured
+ * default timezone.
+ *
+ * The error envelope (schedule.model_unknown, schedule.frequency_unknown,
+ * schedule.days_of_week_invalid, schedule.timezone_unknown) cites this
+ * endpoint via `docsUrl` so the LLM can fetch the live shape on the next
+ * turn instead of guessing.
+ *
+ * Pure read — no DB hit. The snapshot is built from the static
+ * `MODEL_REGISTRY` plus the operator-configured timezone. Phase G may
+ * hang a dashboard surface off this same payload.
+ */
+export interface ScheduleOptionsRouteDependencies {
+    config: AgentConfig;
+}
+export declare function createScheduleOptionsRoutes(deps: ScheduleOptionsRouteDependencies): Hono;

package/dist/api/routes/schedule-options.js

@@ -0,0 +1,76 @@
+import { Hono } from "hono";
+import { snapshotModelRegistry } from "./schedule-validation.js";
+/**
+ * Day-of-week labels exposed in `/schedule/options.daysOfWeek`. Mirrors
+ * the `daysOfWeek` integer enum in `recurrenceRuleSchema` (`0=Sun`..`6=Sat`)
+ * so the LLM can map between the schema and a human-readable label.
+ *
+ * Static — locale-aware labels are out of scope (Aitne is single-owner
+ * and the daemon answers in English per `feedback_skill_content_english_only`).
+ */
+const DAYS_OF_WEEK = {
+    "0": "Sun",
+    "1": "Mon",
+    "2": "Tue",
+    "3": "Wed",
+    "4": "Thu",
+    "5": "Fri",
+    "6": "Sat",
+};
+/** Static enum surface — kept in sync with `recurrenceRuleSchema.frequency`. */
+const FREQUENCIES = ["hourly", "daily", "weekly", "monthly"];
+const TIERS = ["lite", "medium", "high"];
+/**
+ * Per-frequency composition bounds. Surfaced so the LLM has a one-stop
+ * discovery endpoint for composing any recurring rule on the first try
+ * instead of probing via Phase D's error envelope. Mirrors the
+ * superRefine ranges in `recurrenceRuleSchema` — keep these in lockstep
+ * with the schema (`packages/shared/src/schemas.ts`); the
+ * schedule-options.test.ts contract pins the pair.
+ *
+ * `onMissingDay.default` reflects the §12.6 "lastDayOfMonth"
+ * recommendation: callers that omit the field on a monthly rule with
+ * `daysOfMonth` containing 29/30/31 get the bit-compatible clamp
+ * behavior of the pre-redesign engine.
+ */
+const RECURRENCE = {
+    intervalHours: { min: 1, max: 23 },
+    minuteOfHour: { min: 0, max: 59 },
+    daysOfMonth: { min: 1, max: 31 },
+    onMissingDay: {
+        values: ["skip", "lastDayOfMonth"],
+        default: "lastDayOfMonth",
+    },
+};
+function resolveDefaultTimezone(config) {
+    // Prefer the operator's configured primary timezone. When unset (the
+    // first-boot default), fall back to the system-resolved IANA zone so
+    // the LLM still gets a real default rather than an empty string.
+    if (config.timezone && config.timezone.length > 0) {
+        return config.timezone;
+    }
+    return Intl.DateTimeFormat().resolvedOptions().timeZone;
+}
+export function createScheduleOptionsRoutes(deps) {
+    const app = new Hono();
+    app.get("/schedule/options", (c) => {
+        const snapshot = snapshotModelRegistry();
+        const defaultTimezone = resolveDefaultTimezone(deps.config);
+        return c.json({
+            tiers: TIERS,
+            modelAliases: snapshot.modelAliases,
+            models: snapshot.models,
+            frequencies: FREQUENCIES,
+            daysOfWeek: DAYS_OF_WEEK,
+            // Composition bounds for hourly + monthly rules. Without these the
+            // LLM has to probe via Phase D's error envelope to learn that
+            // `intervalHours` caps at 23 (not 24) and `onMissingDay` is the
+            // non-obvious `"skip" | "lastDayOfMonth"` enum.
+            recurrence: RECURRENCE,
+            timeFormat: "HH:MM (24h)",
+            timezoneExample: "Asia/Tokyo",
+            defaults: { timezone: defaultTimezone },
+        });
+    });
+    return app;
+}

package/dist/api/routes/schedule-validation.d.ts

@@ -0,0 +1,145 @@
+import { type BackendId, type BackendModelTier } from "@aitne/shared";
+/**
+ * Phase B helper for SCHEDULE_API_REDESIGN_PLAN.md §4.3.
+ *
+ * `validateModelToken` is the single chokepoint Phase D's schedule routes
+ * use to translate the free-form `model` field on schedule create/PATCH
+ * payloads into either:
+ *
+ *   - a legacy-alias rewrite to `tier_override` (`"sonnet"` → `"medium"`,
+ *     `"opus"` → `"high"`),
+ *   - a registry-backed `(backendId, modelId)` pin captured at write-time
+ *     (closes the §4.3a `requestedBackendId` silent-drop bug),
+ *   - an ambiguous match across multiple backends (today unreachable, but
+ *     `MODEL_REGISTRY` is editable so a future entry could collide),
+ *   - or unknown — caller emits `schedule.model_unknown` with a snapshot
+ *     of every registered model the operator could have meant.
+ *
+ * `snapshotModelRegistry` projects `MODEL_REGISTRY` to the shape the new
+ * `GET /api/schedule/options` endpoint returns (§4.4) AND the shape the
+ * error envelope's `validValues` cites (§5). The same projection serves
+ * both because /options carries the rich `{id, tier, deprecated}` rows
+ * the dashboard wants and `validateModelToken` derives the simpler
+ * `{aliases, models: Record<backend, string[]>}` error payload from it.
+ *
+ * `validateModelToken` matches entirely against its `snapshot` argument
+ * (no direct registry reads). That keeps the helper pure — tests can
+ * construct a synthetic snapshot to exercise the ambiguous branch which
+ * is currently unreachable from the live registry. Pure module — no DB,
+ * no I/O. 100% coverage tier per `vitest.config.ts`.
+ */
+/** Per-model entry shown in `/schedule/options.models[backendId]`. */
+export interface BackendModelDetail {
+    id: string;
+    tier: BackendModelTier;
+    deprecated: boolean;
+}
+/**
+ * Read-only projection of `MODEL_REGISTRY` consumed by /schedule/options
+ * AND by `validateModelToken`. Kept stable across the two consumers so
+ * a registry change only needs one update site.
+ */
+export interface ModelRegistrySnapshot {
+    /**
+     * Legacy alias → process tier mapping. Mirrors the `model: "sonnet" | "opus"`
+     * field the pre-redesign schemas carried. New schedules should prefer
+     * `tier` directly; aliases remain accepted for backward compat
+     * (§9 "Backward compatibility" — existing rows with `model='sonnet'|'opus'`).
+     */
+    modelAliases: {
+        sonnet: BackendModelTier;
+        opus: BackendModelTier;
+    };
+    /** Per-backend list of every registered model. Stable registry order. */
+    models: Record<BackendId, BackendModelDetail[]>;
+}
+/**
+ * Build a snapshot of `MODEL_REGISTRY`. Used by:
+ *   - `GET /api/schedule/options` — returned verbatim under `models` +
+ *     `modelAliases` keys (§4.4).
+ *   - `validateModelToken` — fed in as the second argument so the unknown
+ *     branch can cite valid alternatives without re-walking the registry.
+ *
+ * Entries appear in registry declaration order; callers that need a
+ * sorted view should re-sort. Deprecated entries are kept in the snapshot
+ * (so the dashboard can still surface them) but excluded from the error
+ * envelope's `validValues` payload (so the agent's retry can't loop on a
+ * model the registry would have warned about) — see
+ * `simplifyForUnknownPayload`.
+ */
+export declare function snapshotModelRegistry(): ModelRegistrySnapshot;
+/**
+ * Result of `validateModelToken`. Discriminated by `kind`:
+ *
+ *   - `"alias"`     — legacy `"sonnet"`/`"opus"`. Route rewrites to
+ *                     `tier_override` and clears `model` + `backend_id`.
+ *   - `"model"`     — registered exact-match. Route persists both
+ *                     `(backend_id, model)` and clears `tier_override`.
+ *                     `deprecated: true` adds a §5.0.5 warnings[] entry
+ *                     but does NOT reject the row.
+ *   - `"ambiguous"` — token matched > 1 backend. Route emits
+ *                     `schedule.model_ambiguous` with the matches list
+ *                     so the caller can resubmit using the
+ *                     `<backendId>/<modelId>` composite form.
+ *   - `"unknown"`   — no alias, no registered match. Route emits
+ *                     `schedule.model_unknown` with the full validValues
+ *                     snapshot so the caller's retry can pick a real id.
+ *
+ * `validValues` is shaped to drop straight into
+ * `AgentErrorIssue.validValues` (§5.3). The four kinds are sealed in this
+ * union; new kinds require a registry-code addition + Phase D route
+ * branch update.
+ */
+export type ValidateModelResult = {
+    kind: "alias";
+    tierToken: BackendModelTier;
+} | {
+    kind: "model";
+    backendId: BackendId;
+    modelId: string;
+    deprecated: boolean;
+} | {
+    kind: "ambiguous";
+    matches: ReadonlyArray<{
+        backendId: BackendId;
+        modelId: string;
+    }>;
+    validValues: {
+        matches: ReadonlyArray<{
+            backendId: BackendId;
+            modelId: string;
+        }>;
+        hint: string;
+    };
+} | {
+    kind: "unknown";
+    validValues: {
+        aliases: ReadonlyArray<"sonnet" | "opus">;
+        models: Record<BackendId, string[]>;
+    };
+};
+/**
+ * Resolve a caller-supplied `model` token to one of four outcomes. See
+ * `ValidateModelResult` for the contract.
+ *
+ * Resolution order (per SCHEDULE_API_REDESIGN_PLAN.md §4.3):
+ *   1. Legacy alias ("sonnet" / "opus") → kind:"alias".
+ *   2. Composite form "<backendId>/<modelId>" — opt-in disambiguator.
+ *      Only honored when the prefix is exactly one of `BACKEND_IDS`. A
+ *      composite token that fails to resolve falls through to "unknown"
+ *      (not "ambiguous"); the caller named a specific backend, so an
+ *      ambiguous match is impossible by construction. A slash-bearing
+ *      token whose prefix is NOT a backend id falls through to the
+ *      cross-backend scan — opencode model ids like
+ *      `anthropic/claude-opus-4-8` would otherwise be unreachable.
+ *   3. Cross-backend exact match in the snapshot:
+ *        - exactly one match → kind:"model"
+ *        - multiple matches  → kind:"ambiguous" (future-proof; today
+ *          unreachable because `claude-opus-4-8` and opencode's
+ *          `anthropic/claude-opus-4-8` differ — but the registry is
+ *          editable and a future entry could collide).
+ *   4. No match → kind:"unknown" with the simplified validValues payload.
+ *
+ * Pure — relies only on the snapshot argument.
+ */
+export declare function validateModelToken(token: string, snapshot: ModelRegistrySnapshot): ValidateModelResult;