@piagent/platform 1.2.17 → 1.3.0-ie.8

package/packages/piagent-core/runtime/model/authenticated-catalog.ts

@@ -0,0 +1,127 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { RuntimeAvailability } from "./runtime-snapshot.ts";
+
+export const AUTHENTICATED_MODEL_CATALOG_SCHEMA_VERSION = 1 as const;
+
+export type AuthenticatedModelCatalogEntry = {
+  provider: string;
+  modelId: string;
+  contextWindow: number | null;
+  reasoning: boolean | null;
+  imageInput: boolean | null;
+  supportedThinkingLevels: string[] | null;
+};
+
+export type AuthenticatedModelCatalog = {
+  schemaVersion: typeof AUTHENTICATED_MODEL_CATALOG_SCHEMA_VERSION;
+  capturedAt: string;
+  source: "authenticated-catalog";
+  availability: RuntimeAvailability;
+  models: AuthenticatedModelCatalogEntry[];
+  warnings: string[];
+};
+
+type ModelLike = {
+  provider?: unknown;
+  id?: unknown;
+  name?: unknown;
+  contextWindow?: unknown;
+  reasoning?: unknown;
+  input?: unknown;
+  thinkingLevelMap?: unknown;
+};
+
+export type ModelRegistryView = {
+  getAvailable?: () => readonly ModelLike[] | Promise<readonly ModelLike[]>;
+  getAll?: () => readonly ModelLike[] | Promise<readonly ModelLike[]>;
+};
+
+export type CatalogCaptureOptions = {
+  capturedAt?: string;
+  offline?: boolean;
+};
+
+function text(value: unknown): string {
+  return String(value ?? "").trim().slice(0, 160);
+}
+
+function positiveInteger(value: unknown): number | null {
+  return Number.isInteger(value) && Number(value) > 0 && Number(value) <= 10_000_000 ? Number(value) : null;
+}
+
+function thinkingLevels(value: unknown): string[] | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const levels = Object.entries(value)
+    .filter(([, mapped]) => mapped !== null && mapped !== false)
+    .map(([level]) => text(level))
+    .filter(Boolean)
+    .sort();
+  return levels.length > 0 ? [...new Set(levels)].slice(0, 16) : [];
+}
+
+function boundedModel(value: ModelLike): AuthenticatedModelCatalogEntry | undefined {
+  const provider = text(value.provider);
+  const modelId = text(value.id ?? value.name);
+  if (!provider || !modelId) return undefined;
+  const input = Array.isArray(value.input) ? value.input.map(text) : undefined;
+  return {
+    provider,
+    modelId,
+    contextWindow: positiveInteger(value.contextWindow),
+    reasoning: typeof value.reasoning === "boolean" ? value.reasoning : null,
+    imageInput: input ? input.includes("image") : null,
+    supportedThinkingLevels: thinkingLevels(value.thinkingLevelMap)
+  };
+}
+
+function deterministicModels(values: readonly ModelLike[]): AuthenticatedModelCatalogEntry[] {
+  const models = new Map<string, AuthenticatedModelCatalogEntry>();
+  for (const value of values) {
+    const model = boundedModel(value);
+    if (!model) continue;
+    const key = `${model.provider}\u0000${model.modelId}`;
+    if (!models.has(key)) models.set(key, model);
+  }
+  return [...models.values()].sort((left, right) => (
+    `${left.provider}/${left.modelId}`.localeCompare(`${right.provider}/${right.modelId}`)
+  ));
+}
+
+export async function captureAuthenticatedModelCatalog(
+  registry: ModelRegistryView | undefined,
+  options: CatalogCaptureOptions = {}
+): Promise<AuthenticatedModelCatalog> {
+  const capturedAt = options.capturedAt ?? new Date().toISOString();
+  if (options.offline) {
+    return { schemaVersion: 1, capturedAt, source: "authenticated-catalog", availability: "offline", models: [], warnings: ["Authenticated model catalog was not queried in offline mode."] };
+  }
+  if (!registry?.getAvailable) {
+    return { schemaVersion: 1, capturedAt, source: "authenticated-catalog", availability: "unknown", models: [], warnings: ["Pi ModelRegistry is unavailable in this runtime."] };
+  }
+  try {
+    const available = deterministicModels(await registry.getAvailable());
+    const all = registry.getAll ? deterministicModels(await registry.getAll()) : [];
+    const availability: RuntimeAvailability = available.length > 0
+      ? "authenticated"
+      : all.length > 0
+        ? "logged-out"
+        : "unavailable";
+    const warnings = availability === "logged-out"
+      ? ["Models exist in the Pi catalog, but none are available through current authentication."]
+      : availability === "unavailable"
+        ? ["Pi returned no authenticated models."]
+        : [];
+    return { schemaVersion: 1, capturedAt, source: "authenticated-catalog", availability, models: available, warnings };
+  } catch {
+    return { schemaVersion: 1, capturedAt, source: "authenticated-catalog", availability: "unavailable", models: [], warnings: ["Authenticated model catalog capture failed; unrelated runtime behavior is unchanged."] };
+  }
+}
+
+export async function captureAuthenticatedModelCatalogFromContext(
+  ctx: ExtensionContext,
+  options: CatalogCaptureOptions = {}
+): Promise<AuthenticatedModelCatalog> {
+  const registry = (ctx as ExtensionContext & { modelRegistry?: ModelRegistryView }).modelRegistry;
+  return captureAuthenticatedModelCatalog(registry, options);
+}

package/packages/piagent-core/runtime/model/capabilities.ts

@@ -0,0 +1,64 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export type RuntimeModelCapability = {
+  provider: string;
+  model: string;
+  family: "codex" | "claude" | "generic";
+  thinkingLevel: string;
+  contextWindow?: number;
+  phaseBudgetScale: number;
+  supportsLargeContext: boolean;
+  source: "pi-runtime";
+};
+
+function normalize(value: unknown): string {
+  return String(value ?? "").trim();
+}
+
+function modelString(ctx: ExtensionContext): { provider: string; model: string } {
+  const model = (ctx as unknown as { model?: { provider?: unknown; id?: unknown; name?: unknown } }).model;
+  const provider = normalize(model?.provider);
+  const id = normalize(model?.id ?? model?.name);
+  const joined = [provider, id].filter(Boolean).join("/");
+  return {
+    provider: provider || "unknown",
+    model: joined || id || "unknown"
+  };
+}
+
+function familyForModel(value: string): RuntimeModelCapability["family"] {
+  const lower = value.toLowerCase();
+  if (lower.includes("codex") || lower.includes("gpt-5")) return "codex";
+  if (lower.includes("claude") || lower.includes("anthropic")) return "claude";
+  return "generic";
+}
+
+function thinkingScale(thinkingLevel: string): number {
+  const normalized = thinkingLevel.toLowerCase();
+  if (["xhigh", "extra-high", "max"].includes(normalized)) return 0.82;
+  if (["high"].includes(normalized)) return 0.9;
+  if (["medium", "med"].includes(normalized)) return 1;
+  if (["low", "minimal", "none"].includes(normalized)) return 1.08;
+  return 1;
+}
+
+export function modelCapabilityFromContext(
+  ctx: ExtensionContext,
+  thinkingLevel: string
+): RuntimeModelCapability {
+  const model = modelString(ctx);
+  const contextUsage = typeof ctx.getContextUsage === "function" ? ctx.getContextUsage() : undefined;
+  const contextWindow = typeof contextUsage?.contextWindow === "number" ? contextUsage.contextWindow : undefined;
+  const family = familyForModel(`${model.provider}/${model.model}`);
+  const supportsLargeContext = typeof contextWindow === "number" ? contextWindow >= 120_000 : family === "codex";
+  return {
+    provider: model.provider,
+    model: model.model,
+    family,
+    thinkingLevel: normalize(thinkingLevel) || "unknown",
+    contextWindow,
+    phaseBudgetScale: thinkingScale(thinkingLevel) * (supportsLargeContext ? 1 : 0.86),
+    supportsLargeContext,
+    source: "pi-runtime"
+  };
+}

package/packages/piagent-core/runtime/model/model-route-policy.ts

@@ -0,0 +1,179 @@
+import type { AuthenticatedModelCatalog, AuthenticatedModelCatalogEntry } from "./authenticated-catalog.ts";
+import type { TaskFeatures } from "../solver/solver-types.ts";
+import {
+  authenticatedCatalogDigest,
+  CAPABILITY_BANDS,
+  createModelRouteDecision,
+  type CapabilityBand,
+  type ModelRouteDecision,
+  type ModelSelectionSource,
+  type ParentRoutingMode,
+  type RoutingObjective
+} from "./model-route-types.ts";
+
+export type ModelRouteHostBoundary = "unavailable" | "prelaunch";
+
+export type ModelRoutePolicyInput = {
+  features: TaskFeatures;
+  catalog: AuthenticatedModelCatalog;
+  mode: ParentRoutingMode;
+  objective: RoutingObjective;
+  selectionSource: ModelSelectionSource;
+  current: { provider: string | null; modelId: string | null; effort: string | null };
+  freshTaskBoundary: boolean;
+  hostBoundary: ModelRouteHostBoundary;
+};
+
+type Candidate = { provider: "openai-codex"; modelId: string; effort: string };
+
+const BAND_CANDIDATES: Record<CapabilityBand, Candidate[]> = {
+  low: [{ provider: "openai-codex", modelId: "gpt-5.6-luna", effort: "medium" }],
+  medium: [{ provider: "openai-codex", modelId: "gpt-5.6-terra", effort: "medium" }],
+  high: [{ provider: "openai-codex", modelId: "gpt-5.6-sol", effort: "high" }],
+  ultra: [{ provider: "openai-codex", modelId: "gpt-5.6-sol", effort: "xhigh" }]
+};
+const BAND_INDEX = new Map(CAPABILITY_BANDS.map((band, index) => [band, index]));
+
+function exactCandidate(catalog: AuthenticatedModelCatalog, band: CapabilityBand): { model: AuthenticatedModelCatalogEntry; effort: string } | undefined {
+  for (const candidate of BAND_CANDIDATES[band]) {
+    const model = catalog.models.find((entry) => entry.provider === candidate.provider
+      && entry.modelId === candidate.modelId
+      && (entry.supportedThinkingLevels === null || entry.supportedThinkingLevels.includes(candidate.effort)));
+    if (model) return { model, effort: candidate.effort };
+  }
+  return undefined;
+}
+
+function currentBand(modelId: string | null): CapabilityBand | undefined {
+  return modelId === "gpt-5.6-luna" ? "low"
+    : modelId === "gpt-5.6-terra" ? "medium"
+      : modelId === "gpt-5.6-sol" ? "high"
+        : undefined;
+}
+
+function maxBand(left: CapabilityBand, right: CapabilityBand): CapabilityBand {
+  return (BAND_INDEX.get(left) ?? 0) >= (BAND_INDEX.get(right) ?? 0) ? left : right;
+}
+
+function safetyFloor(features: TaskFeatures): { band: CapabilityBand; reasons: string[]; blocked: boolean } {
+  const reasons: string[] = [];
+  const authorization = features.protectedTarget || features.externalAction || features.destructiveAction || features.permissionExpansion;
+  if (features.destructiveAction || features.permissionExpansion) return { band: "ultra", reasons: ["authorization-critical", "safety-floor-ultra"], blocked: true };
+  if (features.changeMode === "source-change" && (features.gitReady === false || features.verifierReady === false)) {
+    return { band: "high", reasons: [features.gitReady === false ? "git-not-ready" : "verifier-missing", "preflight-blocked"], blocked: true };
+  }
+  if (authorization) return { band: "high", reasons: ["authorization-required", "safety-floor-high"], blocked: true };
+  if (features.scopeEstimate === "broad" && (features.riskLane === "high-risk" || features.ambiguity === "high")) {
+    return { band: "ultra", reasons: ["broad-open-ended", "safety-floor-ultra"], blocked: false };
+  }
+  if (features.riskLane === "high-risk" || features.ambiguity === "high" || features.scopeEstimate === "broad") {
+    return { band: "high", reasons: [features.riskLane === "high-risk" ? "high-risk-task" : features.ambiguity === "high" ? "high-ambiguity" : "broad-scope", "safety-floor-high"], blocked: false };
+  }
+  const lowEligible = features.workflowIntent !== "unknown"
+    && features.changeMode !== "unknown"
+    && features.ambiguity === "low"
+    && (features.scopeEstimate === "tiny" || features.scopeEstimate === "bounded")
+    && features.explicitPathCount > 0
+    && features.riskLane !== "unknown"
+    && features.runtimeCapabilitiesKnown
+    && features.gitReady !== null
+    && features.verifierReady !== null
+    && (features.changeMode !== "source-change" || (features.gitReady === true && features.verifierReady === true))
+    && (features.contextPressure === null || features.contextPressure < 0.72);
+  if (lowEligible) return { band: "low", reasons: ["bounded-explicit-task", "cheap-verifier-ready", "safety-floor-low"], blocked: false };
+  const mediumEligible = features.workflowIntent !== "unknown"
+    && features.changeMode !== "unknown"
+    && features.riskLane === "normal"
+    && (features.scopeEstimate === "tiny" || features.scopeEstimate === "bounded")
+    && features.runtimeCapabilitiesKnown;
+  if (mediumEligible) return { band: "medium", reasons: ["normal-bounded-task", "safety-floor-medium"], blocked: false };
+  reasons.push(!features.runtimeCapabilitiesKnown ? "runtime-capabilities-unknown" : "task-facts-incomplete", "safety-floor-high");
+  return { band: "high", reasons, blocked: false };
+}
+
+function objectiveBand(floor: CapabilityBand, objective: RoutingObjective): CapabilityBand {
+  if (objective === "intelligence" && floor === "low") return "medium";
+  return floor;
+}
+
+function downgradeSteps(current: CapabilityBand | undefined, target: CapabilityBand): number {
+  if (!current) return 0;
+  return Math.max(0, (BAND_INDEX.get(current) ?? 0) - (BAND_INDEX.get(target) ?? 0));
+}
+
+export function routeParentModel(input: ModelRoutePolicyInput): ModelRouteDecision {
+  const floor = safetyFloor(input.features);
+  const desired = objectiveBand(floor.band, input.objective);
+  const catalogDigest = authenticatedCatalogDigest(input.catalog);
+  const common = {
+    featureHash: input.features.featureHash,
+    mode: input.mode,
+    objective: input.objective,
+    safetyFloor: floor.band,
+    currentProvider: input.current.provider,
+    currentModelId: input.current.modelId,
+    currentEffort: input.current.effort,
+    selectionSource: input.selectionSource,
+    catalogDigest
+  } as const;
+  if (input.mode === "off") return createModelRouteDecision({
+    ...common, capabilityBand: "abstain", fallbackBand: desired, provider: input.current.provider,
+    modelId: input.current.modelId, effort: input.current.effort, confidence: "high", disposition: "preserved",
+    reasonCodes: ["parent-routing-off"], downgradeSteps: 0, enforced: false
+  });
+  if (input.selectionSource === "explicit-user-pin") return createModelRouteDecision({
+    ...common, capabilityBand: "abstain", fallbackBand: desired, provider: input.current.provider,
+    modelId: input.current.modelId, effort: input.current.effort, confidence: "high", disposition: "preserved",
+    reasonCodes: ["explicit-user-pin-preserved", ...floor.reasons], downgradeSteps: 0, enforced: false
+  });
+  if (floor.blocked) return createModelRouteDecision({
+    ...common, capabilityBand: "abstain", fallbackBand: desired, provider: input.current.provider,
+    modelId: input.current.modelId, effort: input.current.effort, confidence: "high", disposition: "abstained",
+    reasonCodes: [...floor.reasons, "model-routing-cannot-bypass-preflight"], downgradeSteps: 0, enforced: false
+  });
+  if (input.catalog.availability !== "authenticated") return createModelRouteDecision({
+    ...common, capabilityBand: "abstain", fallbackBand: desired, provider: null, modelId: null, effort: null,
+    confidence: "low", disposition: "unavailable", reasonCodes: ["authenticated-catalog-unavailable", ...floor.reasons],
+    downgradeSteps: 0, enforced: false
+  });
+  const candidate = exactCandidate(input.catalog, desired);
+  if (!candidate) return createModelRouteDecision({
+    ...common, capabilityBand: "abstain", fallbackBand: desired, provider: null, modelId: null, effort: null,
+    confidence: "low", disposition: "unavailable", reasonCodes: ["preferred-model-or-effort-unavailable", "no-silent-substitution", ...floor.reasons],
+    downgradeSteps: 0, enforced: false
+  });
+  const reasons = [...floor.reasons, `objective-${input.objective}`, `candidate-${desired}`, "runtime-catalog-match"];
+  const steps = downgradeSteps(currentBand(input.current.modelId), desired);
+  if (input.mode === "shadow") return createModelRouteDecision({
+    ...common, capabilityBand: desired, fallbackBand: null, provider: candidate.model.provider, modelId: candidate.model.modelId,
+    effort: candidate.effort, confidence: floor.band === "low" || floor.band === "ultra" ? "high" : "medium",
+    disposition: "shadowed", reasonCodes: reasons, downgradeSteps: steps, enforced: false
+  });
+  const autoAuthorized = input.mode === "auto"
+    && input.selectionSource !== "unknown"
+    && input.freshTaskBoundary
+    && input.hostBoundary === "prelaunch";
+  if (autoAuthorized) return createModelRouteDecision({
+    ...common, capabilityBand: desired, fallbackBand: null, provider: candidate.model.provider, modelId: candidate.model.modelId,
+    effort: candidate.effort, confidence: floor.band === "low" || floor.band === "ultra" ? "high" : "medium",
+    disposition: "selected", reasonCodes: [...reasons, "prelaunch-task-boundary"], downgradeSteps: steps, enforced: true
+  });
+  const failClosed = input.mode === "auto"
+    ? [input.selectionSource === "unknown" ? "selection-provenance-unknown" : "", !input.freshTaskBoundary ? "not-fresh-task-boundary" : "", input.hostBoundary !== "prelaunch" ? "safe-host-adapter-unavailable" : ""].filter(Boolean)
+    : [];
+  return createModelRouteDecision({
+    ...common, capabilityBand: desired, fallbackBand: null, provider: candidate.model.provider, modelId: candidate.model.modelId,
+    effort: candidate.effort, confidence: floor.band === "low" || floor.band === "ultra" ? "high" : "medium",
+    disposition: "recommended", reasonCodes: [...reasons, ...failClosed], downgradeSteps: steps, enforced: false
+  });
+}
+
+export function parentRoutingModeFromEnvironment(value: unknown): ParentRoutingMode {
+  const normalized = String(value ?? "off").trim().toLowerCase();
+  return ["shadow", "recommend", "auto"].includes(normalized) ? normalized as ParentRoutingMode : "off";
+}
+
+export function routingObjectiveFromEnvironment(value: unknown): RoutingObjective {
+  const normalized = String(value ?? "balance").trim().toLowerCase();
+  return ["intelligence", "cost"].includes(normalized) ? normalized as RoutingObjective : "balance";
+}

package/packages/piagent-core/runtime/model/model-route-runtime.ts

@@ -0,0 +1,102 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+
+import { resolveLocalStatePath } from "../../extensions/local-state-path.js";
+import { appendJsonlBounded } from "../../extensions/state-retention.js";
+import type { ModelRoutePolicyInput } from "./model-route-policy.ts";
+import { routeParentModel } from "./model-route-policy.ts";
+import type { ModelRouteDecision, ParentRoutingMode, RoutingObjective } from "./model-route-types.ts";
+import { validateModelRouteDecision } from "./model-route-types.ts";
+
+export const MODEL_ROUTE_EVENT_SCHEMA_VERSION = 1 as const;
+const MAX_EVENT_BYTES = 512 * 1024;
+
+export type ModelRouteEvaluation =
+  | { status: "off"; durationMs: 0 }
+  | { status: "error"; durationMs: number; warnings: string[] }
+  | { status: "ok"; durationMs: number; reused: boolean; persisted: boolean; warnings: string[]; decision: ModelRouteDecision };
+
+export type ModelRouteEvent = {
+  schemaVersion: typeof MODEL_ROUTE_EVENT_SCHEMA_VERSION;
+  recordedAt: string;
+  sessionHash: string;
+  decision: ModelRouteDecision;
+};
+
+export function modelRouteEventPath(cwd: string): string {
+  return path.join(cwd, ".pi", "piagent-state", "model-routing", "decisions.jsonl");
+}
+
+function readText(file: string): string {
+  try { return fs.readFileSync(file, "utf8"); }
+  catch (error) { if ((error as { code?: string }).code === "ENOENT") return ""; throw error; }
+}
+
+function validateEvent(input: unknown): ModelRouteEvent {
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("model route event must be an object");
+  const value = input as Record<string, unknown>;
+  const fields = new Set(["schemaVersion", "recordedAt", "sessionHash", "decision"]);
+  if (Object.keys(value).some((field) => !fields.has(field)) || [...fields].some((field) => !(field in value))) throw new Error("model route event fields are invalid");
+  if (value.schemaVersion !== 1 || typeof value.recordedAt !== "string" || !Number.isFinite(Date.parse(value.recordedAt))) throw new Error("model route event metadata is invalid");
+  if (typeof value.sessionHash !== "string" || !/^[a-f0-9]{64}$/.test(value.sessionHash)) throw new Error("model route session hash is invalid");
+  validateModelRouteDecision(value.decision, "persisted model route decision");
+  return value as ModelRouteEvent;
+}
+
+export function readModelRouteEvents(cwd: string): { records: ModelRouteEvent[]; corruptions: string[]; latest?: ModelRouteEvent } {
+  try {
+    const current = resolveLocalStatePath(cwd, modelRouteEventPath(cwd), { label: "Model route events" });
+    const rotated = resolveLocalStatePath(cwd, `${modelRouteEventPath(cwd)}.1`, { label: "Rotated model route events" });
+    const records: ModelRouteEvent[] = [], corruptions: string[] = [];
+    for (const [index, line] of [readText(rotated), readText(current)].join("").split(/\r?\n/).filter(Boolean).entries()) {
+      try { records.push(validateEvent(JSON.parse(line))); }
+      catch (error) { corruptions.push(`line ${index + 1}: ${error instanceof Error ? error.message : String(error)}`); }
+    }
+    return { records, corruptions, latest: records.at(-1) };
+  } catch {
+    return { records: [], corruptions: ["model route event path is unsafe"] };
+  }
+}
+
+export function recordModelRouteEvent(cwd: string, sessionId: string, decisionInput: ModelRouteDecision, recordedAt = new Date().toISOString()): { written: boolean; warnings: string[] } {
+  const decision = validateModelRouteDecision(structuredClone(decisionInput));
+  const existing = readModelRouteEvents(cwd);
+  if (existing.corruptions.length > 0) return { written: false, warnings: existing.corruptions };
+  const sessionHash = crypto.createHash("sha256").update(String(sessionId || "unknown-session")).digest("hex");
+  if (existing.latest?.sessionHash === sessionHash && existing.latest.decision.decisionDigest === decision.decisionDigest) return { written: false, warnings: [] };
+  appendJsonlBounded(modelRouteEventPath(cwd), { schemaVersion: MODEL_ROUTE_EVENT_SCHEMA_VERSION, recordedAt, sessionHash, decision } satisfies ModelRouteEvent, { maxBytes: MAX_EVENT_BYTES, mode: 0o600, projectRoot: cwd });
+  return { written: true, warnings: [] };
+}
+
+export class ModelRouteRuntime {
+  readonly #mode: ParentRoutingMode;
+  readonly #objective: RoutingObjective;
+  readonly #cache = new Map<string, ModelRouteDecision>();
+
+  constructor(mode: ParentRoutingMode, objective: RoutingObjective) {
+    this.#mode = mode;
+    this.#objective = objective;
+  }
+
+  get mode(): ParentRoutingMode { return this.#mode; }
+  get objective(): RoutingObjective { return this.#objective; }
+
+  evaluate(cwd: string, sessionId: string, input: Omit<ModelRoutePolicyInput, "mode" | "objective">): ModelRouteEvaluation {
+    if (this.#mode === "off") return { status: "off", durationMs: 0 };
+    const started = performance.now();
+    try {
+      const decision = routeParentModel({ ...input, mode: this.#mode, objective: this.#objective });
+      const key = `${cwd}\u0000${sessionId}`;
+      const cached = this.#cache.get(key);
+      if (cached?.decisionDigest === decision.decisionDigest) return { status: "ok", durationMs: performance.now() - started, reused: true, persisted: false, warnings: [], decision: cached };
+      const persisted = recordModelRouteEvent(cwd, sessionId, decision);
+      this.#cache.set(key, decision);
+      while (this.#cache.size > 100) this.#cache.delete(this.#cache.keys().next().value as string);
+      return { status: "ok", durationMs: performance.now() - started, reused: false, persisted: persisted.written, warnings: persisted.warnings, decision };
+    } catch (error) {
+      return { status: "error", durationMs: performance.now() - started, warnings: [error instanceof Error ? error.message : String(error)] };
+    }
+  }
+}

package/packages/piagent-core/runtime/model/model-route-types.ts

@@ -0,0 +1,148 @@
+import crypto from "node:crypto";
+
+import type { AuthenticatedModelCatalog } from "./authenticated-catalog.ts";
+
+export const MODEL_ROUTE_DECISION_SCHEMA_VERSION = 1 as const;
+export const MODEL_ROUTE_POLICY_VERSION = "model-route-v1" as const;
+export const OPENAI_CODEX_MODEL_ROUTE_MAPPING_VERSION = "openai-codex-model-route-map-v1" as const;
+
+export const PARENT_ROUTING_MODES = Object.freeze(["off", "shadow", "recommend", "auto"] as const);
+export const ROUTING_OBJECTIVES = Object.freeze(["intelligence", "balance", "cost"] as const);
+export const CAPABILITY_BANDS = Object.freeze(["low", "medium", "high", "ultra"] as const);
+export const MODEL_SELECTION_SOURCES = Object.freeze([
+  "explicit-user-pin",
+  "workspace-default",
+  "global-default",
+  "router-selected",
+  "unknown"
+] as const);
+
+export type ParentRoutingMode = typeof PARENT_ROUTING_MODES[number];
+export type RoutingObjective = typeof ROUTING_OBJECTIVES[number];
+export type CapabilityBand = typeof CAPABILITY_BANDS[number];
+export type ModelSelectionSource = typeof MODEL_SELECTION_SOURCES[number];
+export type ModelRouteDisposition = "preserved" | "shadowed" | "recommended" | "selected" | "unavailable" | "abstained";
+
+export type ModelRouteDecision = {
+  schemaVersion: typeof MODEL_ROUTE_DECISION_SCHEMA_VERSION;
+  policyVersion: typeof MODEL_ROUTE_POLICY_VERSION;
+  mappingVersion: typeof OPENAI_CODEX_MODEL_ROUTE_MAPPING_VERSION;
+  featureHash: string;
+  mode: ParentRoutingMode;
+  objective: RoutingObjective;
+  capabilityBand: CapabilityBand | "abstain";
+  safetyFloor: CapabilityBand;
+  fallbackBand: CapabilityBand | null;
+  provider: string | null;
+  modelId: string | null;
+  effort: string | null;
+  currentProvider: string | null;
+  currentModelId: string | null;
+  currentEffort: string | null;
+  selectionSource: ModelSelectionSource;
+  confidence: "low" | "medium" | "high";
+  disposition: ModelRouteDisposition;
+  reasonCodes: string[];
+  downgradeSteps: number;
+  catalogDigest: string;
+  decisionDigest: string;
+  enforced: boolean;
+};
+
+const HASH = /^[a-f0-9]{64}$/;
+const NAME = /^[a-z0-9][a-z0-9._:/-]{0,159}$/i;
+const DECISION_FIELDS = new Set([
+  "schemaVersion", "policyVersion", "mappingVersion", "featureHash", "mode", "objective",
+  "capabilityBand", "safetyFloor", "fallbackBand", "provider", "modelId", "effort",
+  "currentProvider", "currentModelId", "currentEffort", "selectionSource", "confidence",
+  "disposition", "reasonCodes", "downgradeSteps", "catalogDigest", "decisionDigest", "enforced"
+]);
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+
+function nullableName(value: unknown): boolean {
+  return value === null || (typeof value === "string" && NAME.test(value));
+}
+
+function digestPayload(input: Omit<ModelRouteDecision, "decisionDigest">): string {
+  return crypto.createHash("sha256").update(JSON.stringify(input)).digest("hex");
+}
+
+export function authenticatedCatalogDigest(catalog: AuthenticatedModelCatalog): string {
+  const stable = {
+    schemaVersion: catalog.schemaVersion,
+    source: catalog.source,
+    availability: catalog.availability,
+    models: catalog.models.map((model) => ({
+      provider: model.provider,
+      modelId: model.modelId,
+      contextWindow: model.contextWindow,
+      reasoning: model.reasoning,
+      imageInput: model.imageInput,
+      supportedThinkingLevels: model.supportedThinkingLevels === null ? null : [...model.supportedThinkingLevels].sort()
+    })).sort((left, right) => `${left.provider}/${left.modelId}`.localeCompare(`${right.provider}/${right.modelId}`))
+  };
+  return crypto.createHash("sha256").update(JSON.stringify(stable)).digest("hex");
+}
+
+export function createModelRouteDecision(
+  input: Omit<ModelRouteDecision, "schemaVersion" | "policyVersion" | "mappingVersion" | "decisionDigest">
+): ModelRouteDecision {
+  const payload = {
+    schemaVersion: MODEL_ROUTE_DECISION_SCHEMA_VERSION,
+    policyVersion: MODEL_ROUTE_POLICY_VERSION,
+    mappingVersion: OPENAI_CODEX_MODEL_ROUTE_MAPPING_VERSION,
+    ...structuredClone(input)
+  } satisfies Omit<ModelRouteDecision, "decisionDigest">;
+  return validateModelRouteDecision({ ...payload, decisionDigest: digestPayload(payload) });
+}
+
+export function modelRouteDecisionValidationErrors(input: unknown): string[] {
+  const value = record(input);
+  if (!value) return ["model route decision must be an object"];
+  const errors = [
+    ...Object.keys(value).filter((field) => !DECISION_FIELDS.has(field)).map((field) => `model route decision has unknown field: ${field}`),
+    ...[...DECISION_FIELDS].filter((field) => !(field in value)).map((field) => `model route decision missing field: ${field}`)
+  ];
+  if (value.schemaVersion !== MODEL_ROUTE_DECISION_SCHEMA_VERSION
+    || value.policyVersion !== MODEL_ROUTE_POLICY_VERSION
+    || value.mappingVersion !== OPENAI_CODEX_MODEL_ROUTE_MAPPING_VERSION) errors.push("model route schema/policy/mapping version is invalid");
+  if (typeof value.featureHash !== "string" || !HASH.test(value.featureHash)) errors.push("featureHash must be sha256 hex");
+  if (!PARENT_ROUTING_MODES.includes(value.mode as ParentRoutingMode)) errors.push("mode is invalid");
+  if (!ROUTING_OBJECTIVES.includes(value.objective as RoutingObjective)) errors.push("objective is invalid");
+  if (![...CAPABILITY_BANDS, "abstain"].includes(value.capabilityBand as never)) errors.push("capabilityBand is invalid");
+  if (!CAPABILITY_BANDS.includes(value.safetyFloor as CapabilityBand)) errors.push("safetyFloor is invalid");
+  if (value.fallbackBand !== null && !CAPABILITY_BANDS.includes(value.fallbackBand as CapabilityBand)) errors.push("fallbackBand is invalid");
+  for (const field of ["provider", "modelId", "effort", "currentProvider", "currentModelId", "currentEffort"] as const) {
+    if (!nullableName(value[field])) errors.push(`${field} is invalid`);
+  }
+  if (!MODEL_SELECTION_SOURCES.includes(value.selectionSource as ModelSelectionSource)) errors.push("selectionSource is invalid");
+  if (!["low", "medium", "high"].includes(String(value.confidence))) errors.push("confidence is invalid");
+  if (!["preserved", "shadowed", "recommended", "selected", "unavailable", "abstained"].includes(String(value.disposition))) errors.push("disposition is invalid");
+  if (!Array.isArray(value.reasonCodes) || value.reasonCodes.length < 1 || value.reasonCodes.length > 32
+    || value.reasonCodes.some((reason) => typeof reason !== "string" || !NAME.test(reason))
+    || new Set(value.reasonCodes).size !== value.reasonCodes.length) errors.push("reasonCodes are invalid");
+  if (!Number.isInteger(value.downgradeSteps) || Number(value.downgradeSteps) < 0 || Number(value.downgradeSteps) > 3) errors.push("downgradeSteps is invalid");
+  for (const field of ["catalogDigest", "decisionDigest"] as const) {
+    if (typeof value[field] !== "string" || !HASH.test(value[field] as string)) errors.push(`${field} must be sha256 hex`);
+  }
+  if (typeof value.enforced !== "boolean") errors.push("enforced must be boolean");
+  if (value.enforced && (value.mode !== "auto" || value.disposition !== "selected")) errors.push("only an auto selected decision may be enforced");
+  if (value.selectionSource === "explicit-user-pin" && value.enforced) errors.push("an explicit user pin cannot be overridden");
+  if (value.selectionSource === "unknown" && value.enforced) errors.push("unknown selection provenance cannot authorize routing");
+  if (value.capabilityBand === "abstain" && value.enforced) errors.push("an abstention cannot be enforced");
+  if (value.disposition === "unavailable" && (value.provider !== null || value.modelId !== null || value.effort !== null)) errors.push("an unavailable decision cannot name a substitute");
+  if (errors.length === 0) {
+    const { decisionDigest, ...payload } = value as unknown as ModelRouteDecision;
+    if (digestPayload(payload) !== decisionDigest) errors.push("decisionDigest does not match decision payload");
+  }
+  return errors;
+}
+
+export function validateModelRouteDecision(input: unknown, source = "model route decision"): ModelRouteDecision {
+  const errors = modelRouteDecisionValidationErrors(input);
+  if (errors.length > 0) throw new Error(`${source}: ${errors.join("; ")}`);
+  return input as ModelRouteDecision;
+}