@jwilger/pi-development-system 0.3.8 → 0.5.0

package/extensions/development-system.ts

@@ -9,6 +9,7 @@ import { createRecordDepartureTool } from "../src/gates/record-departure-tool.ts
 import { createRequestApprovalTool } from "../src/gates/request-approval-tool.ts";
 import { registerTestGuard } from "../src/gates/test-guard.ts";
 import { createJevHolder } from "../src/jev/holder.ts";
+import { createModelsTool, registerModelsCommand } from "../src/state/models-command.ts";
 import { createSessionState } from "../src/state/session-state.ts";
 
 const nonNegotiables = readFileSync(
@@ -60,6 +61,8 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
   registerTestGuard({ pi, state, approvals, jev: (ctx) => jevHolder.forContext(ctx) });
   pi.registerTool(createRecordDepartureTool({ pi, state }));
   pi.registerTool(createRequestApprovalTool({ pi, approvals }));
+  pi.registerTool(createModelsTool());
+  registerModelsCommand(pi);
 
   pi.registerCommand("devsys-status", {
     description: "Show development-system phase, sizing, slice, departures and Jev status",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilger/pi-development-system",
-  "version": "0.3.8",
+  "version": "0.5.0",
   "description": "A pi extension package representing a seasoned approach to software development using a full AI SDLC.",
   "keywords": [
     "pi-package"

package/src/core/models.ts

@@ -0,0 +1,221 @@
+import { err, ok, type Result } from "./result.ts";
+
+/** Capability tiers and roles the system asks models for (plan Appendix B `[models]`). */
+export const SLOTS = [
+  "frontier",
+  "strong",
+  "fast",
+  "planning",
+  "advisor",
+  "implementer",
+  "reviewer",
+  "lens",
+  "researcher",
+  "jev",
+] as const;
+
+export type Slot = (typeof SLOTS)[number];
+
+export const isSlot = (value: string): value is Slot => SLOTS.some((s) => s === value);
+
+/** `provider/id`; the id may contain `/` (gateway providers) and `*` (family pattern). */
+export type ModelRef = `${string}/${string}`;
+
+/** Ordered candidates per slot: `provider/id`, `provider/family-*`, or `@slot` indirection. */
+export type ModelMatrix = Readonly<Record<Slot, readonly string[]>>;
+
+export type Available = { readonly provider: string; readonly id: string };
+
+export type ModelError =
+  | { readonly kind: "unresolvable"; readonly slot: Slot }
+  | { readonly kind: "cycle"; readonly path: readonly Slot[] };
+
+export type Resolution = { readonly model: ModelRef; readonly via: string };
+
+type VersionKey = { readonly numbers: readonly number[]; readonly date: number | undefined };
+
+/** Date-like segments (YYYYMMDD) are snapshot suffixes, not versions. */
+const MIN_DATE_DIGITS = 6;
+
+function versionKey(id: string): VersionKey {
+  const numbers: number[] = [];
+  let date: number | undefined;
+  for (const run of id.match(/\d+/g) ?? []) {
+    if (run.length >= MIN_DATE_DIGITS) date = Number(run);
+    else numbers.push(Number(run));
+  }
+  return { numbers, date };
+}
+
+function compareNumbers(a: readonly number[], b: readonly number[]): number {
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const x = a[i];
+    const y = b[i];
+    if (x === undefined) return -1;
+    if (y === undefined) return 1;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * Natural version order over the numeric segments of two model ids. Dated snapshot suffixes rank
+ * below the undated alias with the same version, so `x-4-5` beats `x-4-5-20251001`.
+ */
+export function compareModelVersions(a: string, b: string): number {
+  const ka = versionKey(a);
+  const kb = versionKey(b);
+  const byNumbers = compareNumbers(ka.numbers, kb.numbers);
+  if (byNumbers !== 0) return byNumbers;
+  if (ka.date !== kb.date) {
+    if (ka.date === undefined) return 1;
+    if (kb.date === undefined) return -1;
+    return ka.date < kb.date ? -1 : 1;
+  }
+  if (a === b) return 0;
+  return a < b ? -1 : 1;
+}
+
+/** `*`-only glob over a model id (no regular expressions built from configuration). */
+function matchesPattern(pattern: string, id: string): boolean {
+  const parts = pattern.split("*");
+  if (parts.length === 1) return pattern === id;
+  const first = parts[0] ?? "";
+  const last = parts.at(-1) ?? "";
+  if (id.length < first.length + last.length || !id.startsWith(first) || !id.endsWith(last)) {
+    return false;
+  }
+  let at = first.length;
+  const limit = id.length - last.length;
+  for (const middle of parts.slice(1, -1)) {
+    const found = id.indexOf(middle, at);
+    if (found === -1 || found + middle.length > limit) return false;
+    at = found + middle.length;
+  }
+  return true;
+}
+
+function splitRef(candidate: string): { provider: string; id: string } | undefined {
+  const slash = candidate.indexOf("/");
+  if (slash <= 0 || slash === candidate.length - 1) return undefined;
+  return { provider: candidate.slice(0, slash), id: candidate.slice(slash + 1) };
+}
+
+/** The exact model, or the newest available id matching the family pattern; `@slot` is not handled here. */
+export function resolveCandidate(
+  candidate: string,
+  available: readonly Available[],
+): ModelRef | undefined {
+  const ref = splitRef(candidate);
+  if (ref === undefined) return undefined;
+  const matches = available
+    .flatMap((m) => (m.provider === ref.provider && matchesPattern(ref.id, m.id) ? [m.id] : []))
+    .sort(compareModelVersions);
+  const best = matches.at(-1);
+  return best === undefined ? undefined : `${ref.provider}/${best}`;
+}
+
+function resolveFrom(
+  matrix: ModelMatrix,
+  slot: Slot,
+  available: readonly Available[],
+  trail: readonly Slot[],
+): Result<Resolution, ModelError> {
+  if (trail.includes(slot)) return err({ kind: "cycle", path: [...trail, slot] });
+  for (const candidate of matrix[slot]) {
+    if (candidate.startsWith("@")) {
+      const target = candidate.slice(1);
+      if (!isSlot(target)) continue;
+      const inner = resolveFrom(matrix, target, available, [...trail, slot]);
+      if (inner.ok || inner.error.kind === "cycle") return inner;
+      continue;
+    }
+    const model = resolveCandidate(candidate, available);
+    if (model !== undefined) return ok({ model, via: candidate });
+  }
+  return err({ kind: "unresolvable", slot });
+}
+
+/** First candidate of the slot that resolves against what this machine can use; `via` is the matching candidate. */
+export function resolveSlot(
+  matrix: ModelMatrix,
+  slot: Slot,
+  available: readonly Available[],
+): Result<Resolution, ModelError> {
+  return resolveFrom(matrix, slot, available, []);
+}
+
+/** Shipped defaults: model families only (no dated ids), so they roll forward as providers ship. */
+export function defaultMatrix(): ModelMatrix {
+  return {
+    frontier: [
+      "openai-codex/gpt-*-astra",
+      "openai/gpt-*-astra",
+      "anthropic/claude-fable-*",
+      "anthropic/claude-opus-*",
+      "openai-codex/gpt-*-sol",
+      "openai/gpt-*-sol",
+    ],
+    strong: [
+      "openai-codex/gpt-*-sol",
+      "openai/gpt-*-sol",
+      "anthropic/claude-sonnet-*",
+      "anthropic/claude-opus-*",
+      "openai-codex/gpt-*-terra",
+      "openai/gpt-*-terra",
+    ],
+    fast: [
+      "openai-codex/gpt-*-luna",
+      "openai/gpt-*-luna",
+      "anthropic/claude-haiku-*",
+      "openai-codex/gpt-*-terra",
+      "openai/gpt-*-terra",
+      "@strong",
+    ],
+    planning: ["@frontier"],
+    advisor: ["@frontier"],
+    implementer: ["@strong"],
+    reviewer: [
+      "anthropic/claude-opus-*",
+      "anthropic/claude-sonnet-*",
+      "openai-codex/gpt-*-sol",
+      "openai/gpt-*-sol",
+      "@strong",
+    ],
+    lens: ["@strong"],
+    researcher: ["@fast"],
+    jev: [
+      "typesafe/jev-latest",
+      "openrouter/typesafe/jev-latest",
+      "opencode/jev-1.13",
+      "cloudflare-workers-ai/typesafe/jev",
+      "vercel-ai-gateway/typesafe-ai/jev",
+    ],
+  };
+}
+
+const WIDTH = Math.max(...SLOTS.map((s) => s.length));
+
+/** The `[models]` TOML table for a matrix, one slot per line in declaration order. */
+export function renderMatrixToml(matrix: ModelMatrix): string {
+  const lines = SLOTS.map(
+    (slot) => `${slot.padEnd(WIDTH)} = [${matrix[slot].map((c) => JSON.stringify(c)).join(", ")}]`,
+  );
+  return `[models]\n${lines.join("\n")}\n`;
+}
+
+/** `text` with its `[models]` table replaced by `matrix` (appended when absent); other tables untouched. */
+export function upsertModelsTable(text: string, matrix: ModelMatrix): string {
+  const table = renderMatrixToml(matrix);
+  const lines = text.split("\n");
+  const start = lines.findIndex((l) => l.trim() === "[models]");
+  if (start === -1) {
+    const body = text.trimEnd();
+    return body === "" ? table : `${body}\n\n${table}`;
+  }
+  const nextHeader = lines.findIndex((l, i) => i > start && l.startsWith("["));
+  const head = lines.slice(0, start).join("\n");
+  const tail = nextHeader === -1 ? "" : lines.slice(nextHeader).join("\n");
+  const before = head === "" ? "" : `${head}\n`;
+  return tail === "" ? `${before}${table}` : `${before}${table}\n${tail}`;
+}

package/src/state/config.ts

@@ -0,0 +1,313 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseToml } from "smol-toml";
+import { defaultMatrix, isSlot, type ModelMatrix, SLOTS, type Slot } from "../core/models.ts";
+import { err, ok, type Result } from "../core/result.ts";
+
+export const CONFIG_FILE = ".development-system.toml";
+
+const DELIVERY_MODES = ["trunk", "pull-request", "local-only"] as const;
+const TRACKER_KINDS = ["repo-files", "github", "jira", "linear"] as const;
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+
+export type DeliveryMode = (typeof DELIVERY_MODES)[number];
+export type TrackerKind = (typeof TRACKER_KINDS)[number];
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+
+export type ConfigError = {
+  readonly kind: "config-error";
+  readonly message: string;
+  readonly key?: string;
+};
+
+export type Route = { readonly slot: Slot; readonly thinkingLevel: ThinkingLevel };
+
+export type DevsysConfig = {
+  readonly delivery: {
+    readonly mode: DeliveryMode;
+    readonly trunk: string;
+    readonly remote: string;
+  };
+  readonly review: { readonly requiredCleanRounds: number; readonly minRounds: number };
+  readonly tracker: { readonly kind: TrackerKind; readonly repo?: string };
+  readonly profiles: { readonly override: readonly string[] };
+  readonly models: ModelMatrix;
+  readonly routing: Readonly<Record<string, Route>>;
+  readonly jev: { readonly timeoutMs: number; readonly confidenceFloor: number };
+  readonly verifier: { readonly maxPerSession: number };
+  readonly cadence: { readonly pushMinutes: number };
+  readonly eventModel: { readonly provider: string };
+};
+
+const DEFAULT_ROUTING: Readonly<Record<string, Route>> = {
+  "trivial/low": { slot: "fast", thinkingLevel: "low" },
+  "trivial/*": { slot: "implementer", thinkingLevel: "medium" },
+  "routine/low": { slot: "implementer", thinkingLevel: "medium" },
+  "routine/*": { slot: "strong", thinkingLevel: "high" },
+  "complex/*": { slot: "strong", thinkingLevel: "high" },
+  "expert/*": { slot: "frontier", thinkingLevel: "high" },
+};
+
+const fail = (message: string, key?: string): Result<never, ConfigError> =>
+  err(
+    key === undefined ? { kind: "config-error", message } : { kind: "config-error", message, key },
+  );
+
+type Table = Readonly<Record<string, unknown>>;
+
+const isTable = (value: unknown): value is Table =>
+  typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date);
+
+const qualified = (path: string, key: string): string => (path === "" ? key : `${path}.${key}`);
+
+/** The `[path]` table (or defaults when absent), rejecting any key outside `allowed`. */
+function section(
+  root: Table,
+  name: string,
+  allowed: readonly string[],
+): Result<Table, ConfigError> {
+  const raw = root[name];
+  if (raw === undefined) return ok({});
+  if (!isTable(raw)) return fail(`${name} must be a table`, name);
+  const unknown = Object.keys(raw).find((k) => !allowed.includes(k));
+  return unknown === undefined
+    ? ok(raw)
+    : fail(`unknown key ${qualified(name, unknown)}`, qualified(name, unknown));
+}
+
+function text(t: Table, path: string, key: string, fallback: string): Result<string, ConfigError> {
+  const v = t[key];
+  if (v === undefined) return ok(fallback);
+  return typeof v === "string" && v !== ""
+    ? ok(v)
+    : fail(`${qualified(path, key)} must be a non-empty string`, qualified(path, key));
+}
+
+function choice<T extends string>(
+  t: Table,
+  path: string,
+  key: string,
+  options: readonly T[],
+  fallback: T,
+): Result<T, ConfigError> {
+  const v = t[key];
+  if (v === undefined) return ok(fallback);
+  const found = options.find((o) => o === v);
+  return found !== undefined
+    ? ok(found)
+    : fail(`${qualified(path, key)} must be one of ${options.join(" | ")}`, qualified(path, key));
+}
+
+function number(
+  t: Table,
+  path: string,
+  key: string,
+  fallback: number,
+  bounds: { min: number; max: number; integer: boolean },
+): Result<number, ConfigError> {
+  const v = t[key];
+  if (v === undefined) return ok(fallback);
+  const valid =
+    typeof v === "number" &&
+    v >= bounds.min &&
+    v <= bounds.max &&
+    (!bounds.integer || Number.isInteger(v));
+  if (valid) return ok(v);
+  const kind = bounds.integer ? "an integer" : "a number";
+  return fail(
+    `${qualified(path, key)} must be ${kind} between ${bounds.min} and ${bounds.max}`,
+    qualified(path, key),
+  );
+}
+
+const POSITIVE = { min: 1, max: 1_000_000, integer: true };
+
+const MODEL_CANDIDATE = /^(@[a-z]+|[^/\s]+\/\S+)$/;
+
+function candidates(raw: unknown, key: string): Result<readonly string[], ConfigError> {
+  const valid =
+    Array.isArray(raw) &&
+    raw.length > 0 &&
+    raw.every((c) => typeof c === "string" && MODEL_CANDIDATE.test(c));
+  return valid
+    ? ok(raw.map(String))
+    : fail(
+        `${key} must be a non-empty array of "provider/id", "provider/family-*" or "@slot" strings`,
+        key,
+      );
+}
+
+function models(root: Table): Result<ModelMatrix, ConfigError> {
+  const table = section(root, "models", SLOTS);
+  if (!table.ok) return table;
+  const merged: Record<Slot, readonly string[]> = { ...defaultMatrix() };
+  for (const [slot, raw] of Object.entries(table.value)) {
+    if (!isSlot(slot)) continue;
+    const parsed = candidates(raw, `models.${slot}`);
+    if (!parsed.ok) return parsed;
+    merged[slot] = parsed.value;
+  }
+  return ok(merged);
+}
+
+function route(raw: unknown, key: string): Result<Route, ConfigError> {
+  const [slot, level] = Array.isArray(raw) ? raw : [];
+  const valid =
+    Array.isArray(raw) &&
+    raw.length === 2 &&
+    typeof slot === "string" &&
+    isSlot(slot) &&
+    THINKING_LEVELS.some((l) => l === level);
+  if (!valid || typeof slot !== "string" || !isSlot(slot)) {
+    return fail(
+      `${key} must be [slot, thinkingLevel] (levels: ${THINKING_LEVELS.join(", ")})`,
+      key,
+    );
+  }
+  const thinkingLevel = THINKING_LEVELS.find((l) => l === level);
+  return thinkingLevel === undefined
+    ? fail(`${key} has an unknown thinking level`, key)
+    : ok({ slot, thinkingLevel });
+}
+
+function routing(root: Table): Result<Readonly<Record<string, Route>>, ConfigError> {
+  const raw = root.routing;
+  if (raw === undefined) return ok(DEFAULT_ROUTING);
+  if (!isTable(raw)) return fail("routing must be a table", "routing");
+  const result: Record<string, Route> = {};
+  for (const [pattern, value] of Object.entries(raw)) {
+    const parsed = route(value, `routing.${pattern}`);
+    if (!parsed.ok) return parsed;
+    result[pattern] = parsed.value;
+  }
+  return ok(result);
+}
+
+function profiles(root: Table): Result<readonly string[], ConfigError> {
+  const table = section(root, "profiles", ["override"]);
+  if (!table.ok) return table;
+  const raw = table.value.override;
+  if (raw === undefined) return ok([]);
+  return Array.isArray(raw) && raw.every((p) => typeof p === "string")
+    ? ok(raw.map(String))
+    : fail("profiles.override must be an array of strings", "profiles.override");
+}
+
+const TOP_LEVEL = [
+  "version",
+  "delivery",
+  "review",
+  "tracker",
+  "profiles",
+  "models",
+  "routing",
+  "jev",
+  "verifier",
+  "cadence",
+  "event_model",
+];
+
+function deliveryAndReview(
+  root: Table,
+): Result<Pick<DevsysConfig, "delivery" | "review" | "tracker">, ConfigError> {
+  const d = section(root, "delivery", ["mode", "trunk", "remote"]);
+  const r = section(root, "review", ["required_clean_rounds", "min_rounds"]);
+  const t = section(root, "tracker", ["kind", "repo"]);
+  if (!d.ok) return d;
+  if (!r.ok) return r;
+  if (!t.ok) return t;
+  const mode = choice(d.value, "delivery", "mode", DELIVERY_MODES, "trunk");
+  const trunk = text(d.value, "delivery", "trunk", "main");
+  const remote = text(d.value, "delivery", "remote", "origin");
+  const required = number(r.value, "review", "required_clean_rounds", 3, POSITIVE);
+  const min = number(r.value, "review", "min_rounds", 1, POSITIVE);
+  const kind = choice(t.value, "tracker", "kind", TRACKER_KINDS, "repo-files");
+  const repo = t.value.repo === undefined ? ok(undefined) : text(t.value, "tracker", "repo", "");
+  for (const field of [mode, trunk, remote, required, min, kind, repo]) if (!field.ok) return field;
+  if (!(mode.ok && trunk.ok && remote.ok && required.ok && min.ok && kind.ok && repo.ok)) {
+    return fail("unreachable");
+  }
+  return ok({
+    delivery: { mode: mode.value, trunk: trunk.value, remote: remote.value },
+    review: { requiredCleanRounds: required.value, minRounds: min.value },
+    tracker:
+      repo.value === undefined ? { kind: kind.value } : { kind: kind.value, repo: repo.value },
+  });
+}
+
+function limits(
+  root: Table,
+): Result<Pick<DevsysConfig, "jev" | "verifier" | "cadence" | "eventModel">, ConfigError> {
+  const j = section(root, "jev", ["timeout_ms", "confidence_floor"]);
+  const v = section(root, "verifier", ["max_per_session"]);
+  const c = section(root, "cadence", ["push_minutes"]);
+  const e = section(root, "event_model", ["provider"]);
+  if (!j.ok) return j;
+  if (!v.ok) return v;
+  if (!c.ok) return c;
+  if (!e.ok) return e;
+  const timeout = number(j.value, "jev", "timeout_ms", 4000, POSITIVE);
+  const floor = number(j.value, "jev", "confidence_floor", 0.6, { min: 0, max: 1, integer: false });
+  const max = number(v.value, "verifier", "max_per_session", 6, POSITIVE);
+  const push = number(c.value, "cadence", "push_minutes", 60, POSITIVE);
+  const provider = text(e.value, "event_model", "provider", "builtin");
+  if (!timeout.ok) return timeout;
+  if (!floor.ok) return floor;
+  if (!max.ok) return max;
+  if (!push.ok) return push;
+  if (!provider.ok) return provider;
+  return ok({
+    jev: { timeoutMs: timeout.value, confidenceFloor: floor.value },
+    verifier: { maxPerSession: max.value },
+    cadence: { pushMinutes: push.value },
+    eventModel: { provider: provider.value },
+  });
+}
+
+/** Parses the text of `.development-system.toml` (plan Appendix B); absent keys take defaults. */
+export function parseConfig(source: string): Result<DevsysConfig, ConfigError> {
+  let root: Table;
+  try {
+    root = parseToml(source);
+  } catch (cause) {
+    return fail(`invalid TOML: ${cause instanceof Error ? cause.message : String(cause)}`);
+  }
+  const unknown = Object.keys(root).find((k) => !TOP_LEVEL.includes(k));
+  if (unknown !== undefined) return fail(`unknown key ${unknown}`, unknown);
+  if (root.version !== undefined && root.version !== 1) {
+    return fail("version must be 1", "version");
+  }
+  const delivery = deliveryAndReview(root);
+  const lim = limits(root);
+  const matrix = models(root);
+  const route = routing(root);
+  const prof = profiles(root);
+  if (!delivery.ok) return delivery;
+  if (!lim.ok) return lim;
+  if (!matrix.ok) return matrix;
+  if (!route.ok) return route;
+  if (!prof.ok) return prof;
+  return ok({
+    ...delivery.value,
+    ...lim.value,
+    profiles: { override: prof.value },
+    models: matrix.value,
+    routing: route.value,
+  });
+}
+
+/** Reads `<repoRoot>/.development-system.toml`; a missing file means all defaults. */
+export async function loadConfig(repoRoot: string): Promise<Result<DevsysConfig, ConfigError>> {
+  let source: string;
+  try {
+    source = await readFile(join(repoRoot, CONFIG_FILE), "utf8");
+  } catch (cause) {
+    if (typeof cause === "object" && cause !== null && "code" in cause && cause.code === "ENOENT") {
+      return parseConfig("");
+    }
+    return fail(
+      `cannot read ${CONFIG_FILE}: ${cause instanceof Error ? cause.message : String(cause)}`,
+    );
+  }
+  return parseConfig(source);
+}

package/src/state/models-command.ts

@@ -0,0 +1,234 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionContext,
+  ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import {
+  type Available,
+  isSlot,
+  type ModelMatrix,
+  type Resolution,
+  resolveSlot,
+  SLOTS,
+  type Slot,
+  upsertModelsTable,
+} from "../core/models.ts";
+import { CONFIG_FILE, loadConfig } from "./config.ts";
+
+export const CONFIG_ENTRY_TYPE = "devsys-config";
+
+export type CatalogModel = Available & {
+  readonly cost?: { readonly input: number; readonly output: number };
+};
+
+/** The slice of pi's `ctx.modelRegistry` this command needs; tests pass a fake. */
+export interface ModelCatalog {
+  getAvailable(): readonly CatalogModel[];
+  getModelsOfType(type: "classifier"): readonly CatalogModel[];
+  hasConfiguredAuth(model: CatalogModel): boolean;
+}
+
+export type SlotRow = {
+  readonly slot: Slot;
+  readonly resolution: Resolution | undefined;
+};
+
+/** Chat models with credentials plus classifier models with credentials: everything a slot may name. */
+export function availableModels(catalog: ModelCatalog): CatalogModel[] {
+  const classifiers = catalog
+    .getModelsOfType("classifier")
+    .filter((m) => catalog.hasConfiguredAuth(m));
+  return [...catalog.getAvailable(), ...classifiers];
+}
+
+export function resolveRows(matrix: ModelMatrix, available: readonly Available[]): SlotRow[] {
+  return SLOTS.map((slot) => {
+    const r = resolveSlot(matrix, slot, available);
+    return { slot, resolution: r.ok ? r.value : undefined };
+  });
+}
+
+const perMillion = (n: number): string => `$${Number(n.toFixed(2))}`;
+
+function priceOf(model: string, available: readonly CatalogModel[]): string {
+  const hit = available.find((m) => `${m.provider}/${m.id}` === model);
+  return hit?.cost === undefined
+    ? ""
+    : ` · ${perMillion(hit.cost.input)}/${perMillion(hit.cost.output)} per M`;
+}
+
+/** One line per slot: `slot → provider/id (via candidate) · $in/$out per M`, or `UNRESOLVED`. */
+export function renderModelsTable(
+  rows: readonly SlotRow[],
+  available: readonly CatalogModel[],
+): string {
+  const width = Math.max(...SLOTS.map((s) => s.length));
+  return rows
+    .map(({ slot, resolution }) =>
+      resolution === undefined
+        ? `${slot.padEnd(width)}  → UNRESOLVED (no candidate matches a model with credentials)`
+        : `${slot.padEnd(width)}  → ${resolution.model} (via ${resolution.via})${priceOf(resolution.model, available)}`,
+    )
+    .join("\n");
+}
+
+const DEFAULT_FILE = 'version = 1\n\n[delivery]\nmode = "trunk"\n';
+
+export type ModelsOutcome = {
+  readonly ok: boolean;
+  readonly written: boolean;
+  readonly table: string;
+};
+
+type Choice = "accept" | "accept-rest" | "pick" | "pin";
+
+const CHOICE_LABELS: Record<Choice, string> = {
+  accept: "accept",
+  "accept-rest": "accept this and all remaining slots",
+  pick: "pick another available model",
+  pin: "pin the current exact id (no auto-roll)",
+};
+
+async function chooseSlot(
+  ctx: ExtensionCommandContext,
+  slot: Slot,
+  row: SlotRow,
+  available: readonly CatalogModel[],
+  matrix: ModelMatrix,
+): Promise<{ matrix: ModelMatrix; acceptRest: boolean }> {
+  const current = row.resolution?.model;
+  const labels = current === undefined ? [CHOICE_LABELS.pick] : Object.values(CHOICE_LABELS);
+  const picked = await ctx.ui.select(`${slot}: ${current ?? "unresolved"}`, labels);
+  const choice = (Object.keys(CHOICE_LABELS) as Choice[]).find((k) => CHOICE_LABELS[k] === picked);
+  if (choice === "accept-rest") return { matrix, acceptRest: true };
+  if (choice === "pin" && current !== undefined) {
+    return { matrix: { ...matrix, [slot]: [current, ...matrix[slot]] }, acceptRest: false };
+  }
+  if (choice === "pick") {
+    const refs = available.map((m) => `${m.provider}/${m.id}`);
+    const model = await ctx.ui.select(`${slot}: choose a model`, refs);
+    if (model !== undefined) {
+      return { matrix: { ...matrix, [slot]: [model, ...matrix[slot]] }, acceptRest: false };
+    }
+  }
+  return { matrix, acceptRest: false };
+}
+
+async function readConfigText(repoRoot: string): Promise<string> {
+  try {
+    return await readFile(join(repoRoot, CONFIG_FILE), "utf8");
+  } catch {
+    return DEFAULT_FILE;
+  }
+}
+
+/** Core of `/devsys-models`: resolve, optionally adjust interactively, and write the `[models]` table. */
+export async function runModelsCommand(
+  pi: Pick<ExtensionAPI, "appendEntry">,
+  ctx: ExtensionCommandContext,
+  args: string,
+  catalog: ModelCatalog,
+): Promise<ModelsOutcome> {
+  const config = await loadConfig(ctx.cwd);
+  if (!config.ok) {
+    ctx.ui.notify(`${CONFIG_FILE}: ${config.error.message}`, "error");
+    return { ok: false, written: false, table: "" };
+  }
+  const available = availableModels(catalog);
+  let matrix = config.value.models;
+  let rows = resolveRows(matrix, available);
+  const check = args.split(/\s+/).includes("--check");
+  if (!check && ctx.hasUI) {
+    let acceptRest = false;
+    for (const slot of SLOTS) {
+      if (acceptRest) break;
+      const row = rows.find((r) => r.slot === slot);
+      if (row === undefined) continue;
+      const next = await chooseSlot(ctx, slot, row, available, matrix);
+      matrix = next.matrix;
+      acceptRest = next.acceptRest;
+      rows = resolveRows(matrix, available);
+    }
+  }
+  const table = renderModelsTable(rows, available);
+  const unresolved = rows.flatMap((r) => (r.resolution === undefined ? [r.slot] : []));
+  if (check || unresolved.length > 0) {
+    const ok = unresolved.length === 0;
+    ctx.ui.notify(
+      ok ? table : `${table}\n\nUnresolvable slots: ${unresolved.join(", ")}. Nothing written.`,
+      ok ? "info" : "error",
+    );
+    return { ok, written: false, table };
+  }
+  const text = upsertModelsTable(await readConfigText(ctx.cwd), matrix);
+  await writeFile(join(ctx.cwd, CONFIG_FILE), text);
+  pi.appendEntry(CONFIG_ENTRY_TYPE, { models: matrix });
+  ctx.ui.notify(`${table}\n\nWrote [models] to ${CONFIG_FILE}.`, "info");
+  return { ok: true, written: true, table };
+}
+
+export function registerModelsCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("devsys-models", {
+    description:
+      "Resolve the per-project model matrix against the models you can use and write it to .development-system.toml (--check: report only)",
+    handler: async (args, ctx) => {
+      await runModelsCommand(pi, ctx, args, ctx.modelRegistry);
+    },
+  });
+}
+
+const Parameters = Type.Object({
+  slot: Type.Optional(
+    Type.String({ description: `One of: ${SLOTS.join(", ")}. Omit for every slot.` }),
+  ),
+});
+
+const text = (t: string, isError = false) => ({
+  content: [{ type: "text" as const, text: t }],
+  details: undefined,
+  isError,
+});
+
+/** `devsys_models`: the resolved model for a slot (or all slots), from the project's matrix. */
+export function createModelsTool(): ToolDefinition<typeof Parameters> {
+  return {
+    name: "devsys_models",
+    label: "Resolve models",
+    description:
+      "Return the model this project's matrix resolves each slot to (frontier, strong, fast, planning, advisor, implementer, reviewer, lens, researcher, jev) given the credentials on this machine.",
+    promptSnippet: "Look up which model a development-system slot resolves to",
+    parameters: Parameters,
+    exposure: "direct",
+    async execute(
+      _id,
+      params: Static<typeof Parameters>,
+      _signal,
+      _onUpdate,
+      ctx: ExtensionContext,
+    ) {
+      if (params.slot !== undefined && !isSlot(params.slot)) {
+        return text(`unknown slot "${params.slot}". Slots: ${SLOTS.join(", ")}`, true);
+      }
+      const config = await loadConfig(ctx.cwd);
+      if (!config.ok) return text(`${CONFIG_FILE}: ${config.error.message}`, true);
+      const available = availableModels(ctx.modelRegistry);
+      const rows = resolveRows(config.value.models, available).filter(
+        (r) => params.slot === undefined || r.slot === params.slot,
+      );
+      return text(
+        rows
+          .map((r) =>
+            r.resolution === undefined
+              ? `${r.slot}: unresolved`
+              : `${r.slot}: ${r.resolution.model} (via ${r.resolution.via})`,
+          )
+          .join("\n"),
+        rows.some((r) => r.resolution === undefined),
+      );
+    },
+  };
+}