@cruxy/cli 0.16.0 → 0.18.0

package/dist/memory/store.js

@@ -0,0 +1,100 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { globalDir } from "../config/paths.js";
+import { GLOBAL_DIR_NAME, MEMORY_DIR_NAME, MEMORY_FILE_NAME, } from "../constants.js";
+import { containsSecret } from "./secrets.js";
+import { MemoryEntrySchema, MemoryFileSchema, MEMORY_FILE_VERSION, } from "./types.js";
+/** The default source files for a project root. */
+export function defaultMemorySources(cwd) {
+    const root = path.resolve(cwd);
+    return {
+        user: path.join(globalDir(), MEMORY_DIR_NAME, MEMORY_FILE_NAME),
+        project: path.join(root, GLOBAL_DIR_NAME, MEMORY_DIR_NAME, MEMORY_FILE_NAME),
+    };
+}
+/**
+ * Read and validate one scope's file. A missing file yields an empty result
+ * (not an error). Each entry is (1) schema-validated and (2) scanned for secret
+ * content; failures are excluded and collected. The returned `entries` all carry
+ * the requested `scope` (the on-disk `scope` field is normalized to it, so a
+ * mislabeled entry can't cross scopes).
+ */
+export function loadScope(file, scope) {
+    let raw;
+    try {
+        raw = readFileSync(file, "utf8");
+    }
+    catch {
+        // Missing / unreadable → nothing recalled from this scope (not an error).
+        return { entries: [], errors: [] };
+    }
+    let parsedFile;
+    try {
+        parsedFile = JSON.parse(raw);
+    }
+    catch {
+        return {
+            entries: [],
+            errors: [
+                { scope, reason: "invalid", id: "(file)", message: "not valid JSON" },
+            ],
+        };
+    }
+    const fileResult = MemoryFileSchema.safeParse(parsedFile);
+    if (!fileResult.success) {
+        return {
+            entries: [],
+            errors: [
+                {
+                    scope,
+                    reason: "invalid",
+                    id: "(file)",
+                    message: `malformed memory file: ${fileResult.error.issues[0]?.message ?? "invalid shape"}`,
+                },
+            ],
+        };
+    }
+    const entries = [];
+    const errors = [];
+    fileResult.data.entries.forEach((candidate, i) => {
+        const parsed = MemoryEntrySchema.safeParse(candidate);
+        if (!parsed.success) {
+            const id = candidate && typeof candidate === "object" && "id" in candidate
+                ? String(candidate.id)
+                : `#${i}`;
+            errors.push({
+                scope,
+                reason: "invalid",
+                id,
+                message: parsed.error.issues[0]?.message ?? "invalid entry",
+            });
+            return;
+        }
+        // Secrets denylist on LOAD (defense in depth): a hand-edited file cannot
+        // smuggle a secret into context even though `remember` also refuses on write.
+        const scan = containsSecret(parsed.data.content);
+        if (scan.secret) {
+            errors.push({
+                scope,
+                reason: "secret",
+                id: parsed.data.id,
+                message: `excluded — content looks like a secret (${scan.kind})`,
+            });
+            return;
+        }
+        // Normalize scope to the file it came from (never trust the on-disk label to
+        // move an entry across scopes).
+        entries.push({ ...parsed.data, scope });
+    });
+    return { entries, errors };
+}
+/**
+ * Persist a scope's entries, overwriting the file. Creates the memory dir if
+ * needed. The user scope is written `0600` (it is personal, cross-project data);
+ * the project scope inherits normal repo permissions (it may be committed).
+ */
+export function saveScope(file, entries, scope) {
+    mkdirSync(path.dirname(file), { recursive: true });
+    const body = JSON.stringify({ version: MEMORY_FILE_VERSION, entries }, null, 2);
+    writeFileSync(file, body, scope === "user" ? { mode: 0o600 } : undefined);
+}

package/dist/memory/trust.d.ts

@@ -0,0 +1,52 @@
+import type { MemoryEntry, MemoryTrust } from "./types.js";
+/**
+ * The project-MEMORY trust model (C.29) — the exact supply-chain treatment C.19
+ * applies to project hooks, but with its OWN store so memory and hook trust are
+ * independent (the hook `trust.json` keys a single fingerprint per root; sharing
+ * it would couple the two, so memory gets `~/.cruxy/memory-trust.json`).
+ *
+ * Trust is recorded in the GLOBAL dir — in the user's home, NEVER inside a repo —
+ * so cloning a repo carries zero memory trust and an attacker cannot ship a
+ * pre-trusted marker. It is bound to a {@link fingerprintMemory fingerprint} of
+ * the exact project entries seen at trust time and re-checked on every run: if
+ * the project's memory changes, the fingerprint no longer matches and trust is
+ * stale → the entries are not recalled until re-trusted. This defeats
+ * trust-then-swap.
+ */
+/** ~/.cruxy/memory-trust.json */
+export declare function memoryTrustPath(): string;
+/**
+ * A stable content fingerprint of a repo's PROJECT memory entries. Canonical by
+ * construction so a benign reformat (reordered entries, whitespace, added/removed
+ * `id`/`createdAt` metadata) does NOT change it, while any change to the
+ * meaning-bearing content DOES:
+ * - only `kind` + `content` are hashed (id/createdAt/scope are not meaning);
+ * - content is whitespace-normalized (trim + collapse runs);
+ * - entries are sorted so order doesn't matter.
+ *
+ * The empty set has a fixed fingerprint — trusting "no project memory" is
+ * meaningful (adding the first foreign entry re-gates).
+ */
+export declare function fingerprintMemory(entries: readonly MemoryEntry[]): string;
+/** The persisted trust seam — file-backed in production, injectable for tests. */
+export interface MemoryTrustStore {
+    /** The recorded decision for a repo root, or undefined if never trusted. */
+    get(root: string): MemoryTrust | undefined;
+    /** Persist a trust decision (overwrites any prior one for the same root). */
+    record(trust: MemoryTrust): void;
+}
+/**
+ * Is this repo's current project memory trusted? True only when a decision
+ * exists AND its fingerprint matches the current one — changed project memory is
+ * treated as untrusted (stale), forcing a fresh `cruxy memory trust`.
+ */
+export declare function isMemoryTrusted(store: MemoryTrustStore, root: string, currentFingerprint: string): boolean;
+/**
+ * The real store, persisting to `~/.cruxy/memory-trust.json` as
+ * `{ [root]: MemoryTrust }`. Reads are lazy + cached; a corrupt file is treated
+ * as "no trust recorded" (fail-closed — a broken trust file must never grant
+ * trust).
+ */
+export declare function fileMemoryTrustStore(file?: string): MemoryTrustStore;
+/** An in-memory store for tests (and any ephemeral run). */
+export declare function memoryMemoryTrustStore(seed?: MemoryTrust[]): MemoryTrustStore;

package/dist/memory/trust.js

@@ -0,0 +1,106 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { globalDir } from "../config/paths.js";
+import { MEMORY_TRUST_FILE_NAME } from "../constants.js";
+/**
+ * The project-MEMORY trust model (C.29) — the exact supply-chain treatment C.19
+ * applies to project hooks, but with its OWN store so memory and hook trust are
+ * independent (the hook `trust.json` keys a single fingerprint per root; sharing
+ * it would couple the two, so memory gets `~/.cruxy/memory-trust.json`).
+ *
+ * Trust is recorded in the GLOBAL dir — in the user's home, NEVER inside a repo —
+ * so cloning a repo carries zero memory trust and an attacker cannot ship a
+ * pre-trusted marker. It is bound to a {@link fingerprintMemory fingerprint} of
+ * the exact project entries seen at trust time and re-checked on every run: if
+ * the project's memory changes, the fingerprint no longer matches and trust is
+ * stale → the entries are not recalled until re-trusted. This defeats
+ * trust-then-swap.
+ */
+/** ~/.cruxy/memory-trust.json */
+export function memoryTrustPath() {
+    return path.join(globalDir(), MEMORY_TRUST_FILE_NAME);
+}
+/**
+ * A stable content fingerprint of a repo's PROJECT memory entries. Canonical by
+ * construction so a benign reformat (reordered entries, whitespace, added/removed
+ * `id`/`createdAt` metadata) does NOT change it, while any change to the
+ * meaning-bearing content DOES:
+ * - only `kind` + `content` are hashed (id/createdAt/scope are not meaning);
+ * - content is whitespace-normalized (trim + collapse runs);
+ * - entries are sorted so order doesn't matter.
+ *
+ * The empty set has a fixed fingerprint — trusting "no project memory" is
+ * meaningful (adding the first foreign entry re-gates).
+ */
+export function fingerprintMemory(entries) {
+    const canonical = entries
+        .map((e) => [e.kind, e.content.trim().replace(/\s+/g, " ")])
+        .sort((a, b) => a[0] === b[0] ? a[1].localeCompare(b[1]) : a[0].localeCompare(b[0]));
+    return createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
+}
+/**
+ * Is this repo's current project memory trusted? True only when a decision
+ * exists AND its fingerprint matches the current one — changed project memory is
+ * treated as untrusted (stale), forcing a fresh `cruxy memory trust`.
+ */
+export function isMemoryTrusted(store, root, currentFingerprint) {
+    const record = store.get(path.resolve(root));
+    return record !== undefined && record.fingerprint === currentFingerprint;
+}
+// ── file-backed store ─────────────────────────────────────────────────────────
+/**
+ * The real store, persisting to `~/.cruxy/memory-trust.json` as
+ * `{ [root]: MemoryTrust }`. Reads are lazy + cached; a corrupt file is treated
+ * as "no trust recorded" (fail-closed — a broken trust file must never grant
+ * trust).
+ */
+export function fileMemoryTrustStore(file = memoryTrustPath()) {
+    let cache = null;
+    const load = () => {
+        if (cache)
+            return cache;
+        try {
+            const raw = JSON.parse(readFileSync(file, "utf8"));
+            cache =
+                raw && typeof raw === "object"
+                    ? raw
+                    : {};
+        }
+        catch {
+            // Missing or corrupt → no trust (fail-closed).
+            cache = {};
+        }
+        return cache;
+    };
+    return {
+        get(root) {
+            return load()[path.resolve(root)];
+        },
+        record(trust) {
+            const store = load();
+            store[path.resolve(trust.root)] = {
+                ...trust,
+                root: path.resolve(trust.root),
+            };
+            mkdirSync(path.dirname(file), { recursive: true });
+            // 0600: trust records name local paths; keep them owner-only.
+            writeFileSync(file, JSON.stringify(store, null, 2), { mode: 0o600 });
+            if (existsSync(file))
+                cache = store;
+        },
+    };
+}
+/** An in-memory store for tests (and any ephemeral run). */
+export function memoryMemoryTrustStore(seed = []) {
+    const store = new Map();
+    for (const t of seed)
+        store.set(path.resolve(t.root), t);
+    return {
+        get: (root) => store.get(path.resolve(root)),
+        record: (trust) => void store.set(path.resolve(trust.root), {
+            ...trust,
+            root: path.resolve(trust.root),
+        }),
+    };
+}

package/dist/memory/types.d.ts

@@ -0,0 +1,101 @@
+import { z } from "zod";
+/**
+ * Types for persistent memory (C.29). Everything here is **data**: a memory
+ * entry is validated (fail-loud, malformed excluded) and stored as structured
+ * JSON that is NEVER eval'd. Recalled entries are injected into the model's
+ * context as clearly-demarcated REFERENCE DATA (see `recall.ts`) — they are not
+ * instructions and can never grant authority: the U.3 approval gate is
+ * structural and does not read memory at all (proven in `recall.test.ts`).
+ */
+/**
+ * What a memory entry records. A small, closed set — the enum is the extension
+ * point (out of scope: freeform blobs, which we deliberately reject).
+ * - `fact` — a durable fact about the user or project.
+ * - `decision` — a choice made and its rationale.
+ * - `preference` — how the user likes things done.
+ */
+export declare const MEMORY_KINDS: readonly ["fact", "decision", "preference"];
+export type MemoryKind = (typeof MEMORY_KINDS)[number];
+/**
+ * Where an entry lives. `user` (`~/.cruxy/memory`) is your own memory, authored
+ * on this machine → trusted. `project` (`<repo>/.cruxy/memory`) can arrive with
+ * a cloned repo (another author) → untrusted until explicitly trusted (see
+ * `trust.ts`). This is the supply-chain boundary.
+ */
+export declare const MEMORY_SCOPES: readonly ["user", "project"];
+export type MemoryScope = (typeof MEMORY_SCOPES)[number];
+/** Recall renders `user` first (trusted, cross-project), then `project`. */
+export declare const MEMORY_SCOPE_ORDER: readonly MemoryScope[];
+/** Hard cap on a single note's length — memory is for terse facts, not blobs;
+ * this also bounds the per-entry cost of the recall budget. */
+export declare const MAX_CONTENT_CHARS = 2000;
+/**
+ * Strict schema for one memory entry as persisted. `.strict()` rejects unknown
+ * keys so a malformed/foreign object is a loud validation error (excluded), not
+ * silently absorbed. Parsed with this on every load — the file is never trusted
+ * shape-wise just because it is JSON.
+ */
+export declare const MemoryEntrySchema: z.ZodObject<{
+    /** Stable unique id (crypto.randomUUID) — the handle for `forget`. */
+    id: z.ZodString;
+    kind: z.ZodEnum<["fact", "decision", "preference"]>;
+    /** The note. DATA, never instructions. Non-empty, length-capped. */
+    content: z.ZodString;
+    scope: z.ZodEnum<["user", "project"]>;
+    /** ISO 8601 timestamp the entry was recorded. */
+    createdAt: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    kind: "fact" | "decision" | "preference";
+    createdAt: string;
+    content: string;
+    scope: "project" | "user";
+}, {
+    id: string;
+    kind: "fact" | "decision" | "preference";
+    createdAt: string;
+    content: string;
+    scope: "project" | "user";
+}>;
+export type MemoryEntry = z.infer<typeof MemoryEntrySchema>;
+/** Current on-disk file version — lets a future migration detect old files. */
+export declare const MEMORY_FILE_VERSION = 1;
+/** The whole `entries.json` file shape (one file per scope). */
+export declare const MemoryFileSchema: z.ZodObject<{
+    version: z.ZodDefault<z.ZodNumber>;
+    entries: z.ZodDefault<z.ZodArray<z.ZodUnknown, "many">>;
+}, "strict", z.ZodTypeAny, {
+    entries: unknown[];
+    version: number;
+}, {
+    entries?: unknown[] | undefined;
+    version?: number | undefined;
+}>;
+/** Why an entry was rejected on load — surfaced, never silently dropped. */
+export type MemoryLoadReason = "invalid" | "secret";
+/** A rejected entry (malformed, or a detected secret), excluded from recall and
+ * from the writable set, and surfaced loudly. */
+export interface MemoryLoadError {
+    scope: MemoryScope;
+    reason: MemoryLoadReason;
+    /** The offending entry's id when known (else a positional marker). */
+    id: string;
+    message: string;
+}
+/** The validated result of loading one scope's file: the good entries plus the
+ * excluded ones. A missing file is not an error — it yields an empty result. */
+export interface MemoryLoad {
+    entries: MemoryEntry[];
+    errors: MemoryLoadError[];
+}
+/** One repo's recorded PROJECT-memory trust decision (persisted in
+ * `~/.cruxy/memory-trust.json`). The `fingerprint` binds trust to the exact
+ * project entries seen at trust time, so editing them re-gates (see `trust.ts`). */
+export interface MemoryTrust {
+    /** Absolute project root. */
+    root: string;
+    /** sha256 of the canonicalized project entries (see `fingerprintMemory`). */
+    fingerprint: string;
+    /** ISO timestamp the decision was recorded. */
+    at: string;
+}

package/dist/memory/types.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+/**
+ * Types for persistent memory (C.29). Everything here is **data**: a memory
+ * entry is validated (fail-loud, malformed excluded) and stored as structured
+ * JSON that is NEVER eval'd. Recalled entries are injected into the model's
+ * context as clearly-demarcated REFERENCE DATA (see `recall.ts`) — they are not
+ * instructions and can never grant authority: the U.3 approval gate is
+ * structural and does not read memory at all (proven in `recall.test.ts`).
+ */
+// ── entry kind + scope ────────────────────────────────────────────────────────
+/**
+ * What a memory entry records. A small, closed set — the enum is the extension
+ * point (out of scope: freeform blobs, which we deliberately reject).
+ * - `fact` — a durable fact about the user or project.
+ * - `decision` — a choice made and its rationale.
+ * - `preference` — how the user likes things done.
+ */
+export const MEMORY_KINDS = ["fact", "decision", "preference"];
+/**
+ * Where an entry lives. `user` (`~/.cruxy/memory`) is your own memory, authored
+ * on this machine → trusted. `project` (`<repo>/.cruxy/memory`) can arrive with
+ * a cloned repo (another author) → untrusted until explicitly trusted (see
+ * `trust.ts`). This is the supply-chain boundary.
+ */
+export const MEMORY_SCOPES = ["user", "project"];
+/** Recall renders `user` first (trusted, cross-project), then `project`. */
+export const MEMORY_SCOPE_ORDER = ["user", "project"];
+// ── entry schema ──────────────────────────────────────────────────────────────
+/** Hard cap on a single note's length — memory is for terse facts, not blobs;
+ * this also bounds the per-entry cost of the recall budget. */
+export const MAX_CONTENT_CHARS = 2000;
+/**
+ * Strict schema for one memory entry as persisted. `.strict()` rejects unknown
+ * keys so a malformed/foreign object is a loud validation error (excluded), not
+ * silently absorbed. Parsed with this on every load — the file is never trusted
+ * shape-wise just because it is JSON.
+ */
+export const MemoryEntrySchema = z
+    .object({
+    /** Stable unique id (crypto.randomUUID) — the handle for `forget`. */
+    id: z.string().min(1),
+    kind: z.enum(MEMORY_KINDS),
+    /** The note. DATA, never instructions. Non-empty, length-capped. */
+    content: z.string().min(1).max(MAX_CONTENT_CHARS),
+    scope: z.enum(MEMORY_SCOPES),
+    /** ISO 8601 timestamp the entry was recorded. */
+    createdAt: z.string().min(1),
+})
+    .strict();
+/** Current on-disk file version — lets a future migration detect old files. */
+export const MEMORY_FILE_VERSION = 1;
+/** The whole `entries.json` file shape (one file per scope). */
+export const MemoryFileSchema = z
+    .object({
+    version: z.number().int().positive().default(MEMORY_FILE_VERSION),
+    entries: z.array(z.unknown()).default([]),
+})
+    .strict();

package/dist/plan/service.d.ts

@@ -4,6 +4,7 @@ import type { PromptIO } from "../approval/index.js";
 import { ToolRegistry, type ToolContext } from "../tools/index.js";
 import { type AgentResult } from "../agent/loop.js";
 import type { StreamRenderer } from "../render/index.js";
+import type { Router } from "../routing/index.js";
 import { PlanExecutionPolicy } from "./policy.js";
 /**
  * Orchestrates a plan-mode turn (C.31): propose → approve/revise (capped) →
@@ -33,8 +34,16 @@ export interface PlanSessionArgs {
         dirty: boolean;
     } | null;
     projectInstructions?: string | null;
+    /** Persistent memory (C.29): recall block injected into the propose + execute
+     * phases' system prompts (reference data only). */
+    recalledMemory?: string | null;
     renderer?: StreamRenderer;
     /** Revision cap (defaults to {@link MAX_PLAN_REVISIONS}). */
     maxRevisions?: number;
+    /**
+     * Multi-model routing (C.30). When set, the propose phase routes on `plan`
+     * and step execution on `main-turn`; omitted → the provider default.
+     */
+    router?: Router;
 }
 export declare function runPlanSession(args: PlanSessionArgs): Promise<AgentResult>;

package/dist/plan/service.js

@@ -73,8 +73,11 @@ export async function runPlanSession(args) {
             ctx: args.ctx,
             git: args.git,
             projectInstructions: args.projectInstructions,
+            recalledMemory: args.recalledMemory,
             renderer: args.renderer,
             planMode: true,
+            router: args.router,
+            taskClass: "plan",
         }));
         if (!holder.plan) {
             throw planInvalid("the model ended its turn without calling submit_plan");
@@ -105,7 +108,10 @@ export async function runPlanSession(args) {
                     ctx: args.ctx,
                     git: args.git,
                     projectInstructions: args.projectInstructions,
+                    recalledMemory: args.recalledMemory,
                     renderer: args.renderer,
+                    router: args.router,
+                    taskClass: "main-turn",
                 }));
             };
             await executePlan(plan, {

package/dist/render/state.js

@@ -39,9 +39,12 @@ export function describePhase(phase, glyph = UNICODE_GLYPHS) {
         case "thinking": {
             const t = phase.tokens;
             // Honest numbers only: no usage yet → no figure at all.
-            return t && t.input + t.output > 0
+            const base = t && t.input + t.output > 0
                 ? `thinking${e} ${glyph.sep} tokens ${glyph.caretUp}${formatTokens(t.input)} ${glyph.caretDown}${formatTokens(t.output)}`
                 : `thinking${e}`;
+            // The real routing tier (C.30), appended honestly when present — same
+            // ` · ` joiner as the token counts.
+            return phase.tier ? `${base} ${glyph.sep} ${phase.tier}` : base;
         }
         case "calling-tool":
             return `${phase.label}${e}`;

package/dist/render/types.d.ts

@@ -53,10 +53,16 @@ export interface TokenUsage {
  * One phase is live at a time — it is a register, not a queue.
  */
 export type RenderPhase = 
-/** Waiting on the model. `tokens` = usage accumulated so far, omitted at 0. */
+/**
+ * Waiting on the model. `tokens` = usage accumulated so far, omitted at 0.
+ * `tier` = the routing tier this turn runs on (C.30), shown only when routing
+ * is active — an honest signal of the real tier, never a fabricated one, and
+ * always a tier name (never an upstream model id, U.8).
+ */
 {
     kind: "thinking";
     tokens?: TokenUsage;
+    tier?: string;
 }
 /** A tool call is executing; `label` is the human form ("read_file src/x.ts"). */
  | {

package/dist/routing/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export { ConfigRouter, DEFAULT_TIER, routerForConfig, resolveTaskModel, } from "./router.js";

package/dist/routing/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export { ConfigRouter, DEFAULT_TIER, routerForConfig, resolveTaskModel, } from "./router.js";
+// `resolve.ts` (tier → wire model-id) is deliberately NOT re-exported: the
+// mapping is internal to routing, so it can never be reached from a user-facing
+// render path (the internal-mapping-isolation guarantee, U.8).

package/dist/routing/resolve.d.ts

@@ -0,0 +1,17 @@
+import type { Tier } from "./types.js";
+/**
+ * Tier → gateway wire model-id. This is the SINGLE place the mapping lives, and
+ * it is INTERNAL to the routing package (deliberately not re-exported from the
+ * barrel) so it can never be called from a user-facing render path.
+ *
+ * For the Cruxy gateway a tier IS the wire model id — the gateway maps the tier
+ * to a concrete upstream model SERVER-SIDE. So this returns the tier name
+ * unchanged: the output is always a tier, and no upstream model name can
+ * originate here. That property is what keeps the U.8 gag structural rather than
+ * a filter — there is no upstream id in the process to leak (see the tier-gag
+ * test, which asserts this output is always a MODEL_TIERS member).
+ *
+ * The seam exists for a future provider whose tiers map to distinct wire ids;
+ * that mapping would live here and here only.
+ */
+export declare function resolveModelId(tier: Tier): string;

package/dist/routing/resolve.js

@@ -0,0 +1,18 @@
+/**
+ * Tier → gateway wire model-id. This is the SINGLE place the mapping lives, and
+ * it is INTERNAL to the routing package (deliberately not re-exported from the
+ * barrel) so it can never be called from a user-facing render path.
+ *
+ * For the Cruxy gateway a tier IS the wire model id — the gateway maps the tier
+ * to a concrete upstream model SERVER-SIDE. So this returns the tier name
+ * unchanged: the output is always a tier, and no upstream model name can
+ * originate here. That property is what keeps the U.8 gag structural rather than
+ * a filter — there is no upstream id in the process to leak (see the tier-gag
+ * test, which asserts this output is always a MODEL_TIERS member).
+ *
+ * The seam exists for a future provider whose tiers map to distinct wire ids;
+ * that mapping would live here and here only.
+ */
+export function resolveModelId(tier) {
+    return tier;
+}

package/dist/routing/router.d.ts

@@ -0,0 +1,47 @@
+import type { CruxyConfig } from "../config/index.js";
+import type { Router, RoutingConfig, TaskClass, Tier } from "./types.js";
+/**
+ * The tier a config resolves to when nothing else pins one down — mirrors the
+ * gateway's `auto` fallback (`AUTO_FALLBACK_TIER` in the SDK), so an unrouted
+ * cruxy session lands on exactly the tier it does today.
+ */
+export declare const DEFAULT_TIER: Tier;
+/**
+ * The config-driven {@link Router}: maps a declared task class to a tier from
+ * `{ default, map }`, and fails loud when the resolved tier is not offered. It
+ * NEVER inspects prompt content — selection is purely `map[taskClass] ?? default`.
+ */
+export declare class ConfigRouter implements Router {
+    private readonly cfg;
+    private readonly offered;
+    /**
+     * @param cfg      the resolved routing table (default tier + per-task map)
+     * @param offered  the tiers this gateway/plan actually provides; a resolved
+     *                 tier outside this set fails loud. Defaults to all tiers — the
+     *                 seam a future entitlement check narrows (never a silent
+     *                 downgrade).
+     */
+    constructor(cfg: RoutingConfig, offered?: Iterable<Tier>);
+    select(taskClass: TaskClass): Tier;
+}
+/**
+ * Build a router from resolved config, or `null` when routing should stay
+ * inert. Routing is:
+ *
+ * - a cruxy-gateway concept — tiers do not apply to BYO providers, so non-cruxy
+ *   providers get `null` (no override, their `model.model` is used unchanged);
+ * - opt-in — with no `routing.default` and an empty `routing.map`, this returns
+ *   `null` so behavior (and the wire body, and the state line) is byte-identical
+ *   to today. Multi-tier routing activates only once the user configures it.
+ */
+export declare function routerForConfig(config: CruxyConfig): Router | null;
+/**
+ * Resolve a declared task class to `{ tier, model }`: the tier for honest
+ * surfacing (the U.4 state line), the wire model id for the request. The model
+ * id comes from the internal {@link resolveModelId} — callers never touch that
+ * mapping directly, so it stays the single source of truth.
+ */
+export declare function resolveTaskModel(router: Router, taskClass: TaskClass): {
+    tier: Tier;
+    model: string;
+};