@gonrocca/nodd 0.1.0

package/src/manifest.ts

@@ -0,0 +1,61 @@
+// The single source of truth for NODD's numeric thresholds and its visible
+// protocol. The values are copied from gentle's capability manifest
+// (`internal/agents/capabilitymanifest/manifest.go:203-216`) and from the
+// long-session backstop, which lives in gentle only as prose
+// (`internal/components/agentguidance/routing.go:82`).
+//
+// The difference from gentle is the consumer: there these numbers feed
+// `fmt.Fprintf`, here they feed a comparator (`src/gates/delegate.ts`). No gate
+// module may restate a threshold literal.
+
+export const THRESHOLDS = Object.freeze({
+  /** Direct inline: decide or verify from 1–3 files. */
+  minUnderstandingFiles: 1,
+  maxUnderstandingFiles: 3,
+  /** One mechanical, already-understood file change stays inline. */
+  maxMechanicalWriteFiles: 1,
+  /** Mapping trigger: 4+ distinct understanding files. */
+  mappingMinUnderstandingFiles: 4,
+  /** Writer trigger: 2+ non-trivial writer files. */
+  writerMinNonTrivialFiles: 2,
+  /** Long-session backstop: about 20 tool calls without a delegation. */
+  longSessionToolCalls: 20,
+});
+
+/** The seven ODD steps, in protocol order. This is NODD's visible contract. */
+export const CANONICAL_STEPS = Object.freeze([
+  "authorize",
+  "explore",
+  "resolve-uncertainty",
+  "classify",
+  "track",
+  "implement",
+  "close",
+] as const);
+
+export type CanonicalStep = (typeof CANONICAL_STEPS)[number];
+
+/**
+ * The four steps NODD implements as mechanism — gates, comparators and file
+ * writers. They stay visible so the protocol is legible, but they run no model,
+ * so giving them a slot would be decoration.
+ */
+export const MECHANISM_STEPS = Object.freeze([
+  "authorize",
+  "classify",
+  "track",
+  "close",
+] as const);
+
+export type MechanismStep = (typeof MECHANISM_STEPS)[number];
+
+/** The five slots `/nodd-models` can assign: two global, three model-backed steps. */
+export const CONFIGURABLE_SLOTS = Object.freeze([
+  "default",
+  "orchestrator",
+  "explore",
+  "resolve-uncertainty",
+  "implement",
+] as const);
+
+export type ConfigurableSlot = (typeof CONFIGURABLE_SLOTS)[number];

package/src/models/assign.test.ts

@@ -0,0 +1,125 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { CANONICAL_STEPS, MECHANISM_STEPS } from "../manifest.ts";
+import { SLOT_ROWS, isConfigurableSlot, slotRow } from "./slots.ts";
+import { assignmentPatch, groupByProvider, parseAssignment, validateAssignment } from "./assign.ts";
+
+const registry = groupByProvider([
+  { provider: "anthropic", id: "claude-sonnet-4-5" },
+  { provider: "anthropic", id: "claude-opus-4-1" },
+  { provider: "openai-codex", id: "gpt-5-codex" },
+  { provider: "opencode-go", id: "claude-sonnet-4-5" },
+]);
+
+// ---------------------------------------------------------------------------
+// Slots: all seven steps visible, only five assignable.
+// ---------------------------------------------------------------------------
+test("the slot table displays all seven canonical steps in order", () => {
+  const stepRows = SLOT_ROWS.filter((row) => row.kind !== "global");
+  assert.deepEqual(stepRows.map((row) => row.id), [...CANONICAL_STEPS]);
+});
+
+test("the four mechanism steps are present and not assignable", () => {
+  for (const step of MECHANISM_STEPS) {
+    const row = slotRow(step);
+    assert.ok(row, `${step} must be displayed`);
+    assert.equal(row!.kind, "mechanism");
+    assert.equal(isConfigurableSlot(step), false, `${step} must not be assignable`);
+  }
+});
+
+test("the two global slots are assignable and are not canonical steps", () => {
+  for (const slot of ["default", "orchestrator"]) {
+    assert.equal(isConfigurableSlot(slot), true);
+    assert.equal(slotRow(slot)!.kind, "global");
+    assert.ok(!(CANONICAL_STEPS as readonly string[]).includes(slot));
+  }
+});
+
+// ---------------------------------------------------------------------------
+// A mechanism step rejects assignment, saying it is a mechanism.
+// ---------------------------------------------------------------------------
+test("classify=x/y is rejected as a mechanism step, not as an unknown model", () => {
+  const result = validateAssignment(parseAssignment("classify=anthropic/claude-sonnet-4-5")!, registry);
+  assert.equal(result.ok, false);
+  assert.ok(result.ok === false && /mecanismo/.test(result.message), result.ok === false ? result.message : "");
+  assert.ok(result.ok === false && result.message.includes("classify"));
+});
+
+test("every mechanism step rejects assignment", () => {
+  for (const step of MECHANISM_STEPS) {
+    const result = validateAssignment({ slot: step, provider: "anthropic", model: "claude-opus-4-1" }, registry);
+    assert.equal(result.ok, false, `${step} must reject assignment`);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Model validation against the registry.
+// ---------------------------------------------------------------------------
+test("implement=unknown/model is rejected against the registry", () => {
+  const unknownProvider = validateAssignment(parseAssignment("implement=nope/some-model")!, registry);
+  assert.equal(unknownProvider.ok, false);
+  assert.ok(unknownProvider.ok === false && unknownProvider.message.includes("nope"));
+  assert.ok(unknownProvider.ok === false && unknownProvider.message.includes("anthropic"), "valid providers are listed");
+
+  const unknownModel = validateAssignment(parseAssignment("implement=anthropic/gpt-9")!, registry);
+  assert.equal(unknownModel.ok, false);
+  assert.ok(unknownModel.ok === false && unknownModel.message.includes("gpt-9"));
+});
+
+test("an ambiguous bare model id is rejected with qualified suggestions", () => {
+  const result = validateAssignment(parseAssignment("implement=claude-sonnet-4-5")!, registry);
+  assert.equal(result.ok, false);
+  if (result.ok !== false) return;
+  assert.ok(/ambiguo/.test(result.message), result.message);
+  assert.ok(result.message.includes("anthropic/claude-sonnet-4-5"));
+  assert.ok(result.message.includes("opencode-go/claude-sonnet-4-5"));
+});
+
+test("an unambiguous bare model id resolves to its only provider", () => {
+  const result = validateAssignment(parseAssignment("implement=gpt-5-codex")!, registry);
+  assert.equal(result.ok, true);
+  assert.equal(result.ok === true && result.provider, "openai-codex");
+});
+
+test("a qualified valid assignment is accepted", () => {
+  const result = validateAssignment(parseAssignment("implement=anthropic/claude-opus-4-1")!, registry);
+  assert.equal(result.ok, true);
+  assert.equal(result.ok === true && result.provider, "anthropic");
+});
+
+test("an empty registry is permissive: a headless context must not be unusable", () => {
+  const result = validateAssignment(parseAssignment("implement=whatever/model")!, new Map());
+  assert.equal(result.ok, true);
+});
+
+// ---------------------------------------------------------------------------
+// Parsing and the config patch.
+// ---------------------------------------------------------------------------
+test("parseAssignment reads slot=provider/model and slot=model", () => {
+  assert.deepEqual(parseAssignment("implement=anthropic/claude-opus-4-1"), {
+    slot: "implement", provider: "anthropic", model: "claude-opus-4-1",
+  });
+  assert.deepEqual(parseAssignment("default=gpt-5-codex"), {
+    slot: "default", provider: null, model: "gpt-5-codex",
+  });
+  assert.equal(parseAssignment("implement"), null, "no `=` is not an assignment");
+  assert.equal(parseAssignment("=x/y"), null, "an empty slot is not an assignment");
+  assert.equal(parseAssignment("implement="), null, "an empty model is not an assignment");
+});
+
+test("a valid assignment produces a patch touching only models.<slot>", () => {
+  const patch = assignmentPatch({ models: { explore: "anthropic/claude-opus-4-1" }, unrelated: 42 } as never, {
+    slot: "implement", provider: "anthropic", model: "claude-opus-4-1",
+  });
+
+  assert.deepEqual(patch, {
+    models: { explore: "anthropic/claude-opus-4-1", implement: "anthropic/claude-opus-4-1" },
+  });
+  assert.ok(!("unrelated" in patch), "the patch names only what it changes; the merge preserves the rest");
+});
+
+test("a bare model resolved to one provider is written qualified", () => {
+  const patch = assignmentPatch({}, { slot: "implement", provider: "openai-codex", model: "gpt-5-codex" });
+  assert.deepEqual(patch, { models: { implement: "openai-codex/gpt-5-codex" } });
+});

package/src/models/assign.ts

@@ -0,0 +1,138 @@
+// Validating a model assignment against pi's live registry.
+//
+// Adapted from `zero-models.ts:411-460,505-525` — adapted, never imported: NODD
+// is a standalone package and a shared import would couple two products that
+// only share a home directory.
+//
+// The rule that matters: the names written to `~/.pi/nodd.json` must be names pi
+// can actually resolve, so a configured slot never fails at the moment it is
+// needed. That means the registry is the authority, not a hardcoded catalog. An
+// ambiguous bare id is refused with the qualified forms rather than guessed —
+// picking a provider on the user's behalf is how a config silently points at the
+// wrong model.
+//
+// A mechanism step refuses assignment saying *why*: "unknown model" would be a
+// misleading error for `classify=x/y`, where the model is fine and the slot does
+// not exist.
+
+import { isConfigurableSlot, slotRow } from "./slots.ts";
+import type { ConfigurableSlot } from "../manifest.ts";
+
+export type RegistryModel = { provider: string; id: string };
+
+export type Assignment = {
+  slot: string;
+  /** null when the user gave a bare model id. */
+  provider: string | null;
+  model: string;
+};
+
+export type Validation =
+  | { ok: true; provider: string | null }
+  | { ok: false; message: string };
+
+export function groupByProvider(models: RegistryModel[]): Map<string, string[]> {
+  const groups = new Map<string, string[]>();
+  for (const model of models) {
+    const existing = groups.get(model.provider);
+    if (existing) existing.push(model.id);
+    else groups.set(model.provider, [model.id]);
+  }
+  return groups;
+}
+
+/** `slot=provider/model` or `slot=model`. */
+export function parseAssignment(text: string): Assignment | null {
+  const match = /^([^=\s]+)=(\S+)$/.exec(text.trim());
+  if (!match) return null;
+
+  const [, slot, value] = match;
+  const slash = value.indexOf("/");
+  if (slash < 0) return { slot, provider: null, model: value };
+
+  const provider = value.slice(0, slash);
+  const model = value.slice(slash + 1);
+  if (!provider || !model) return null;
+  return { slot, provider, model };
+}
+
+function providersOwning(groups: Map<string, string[]>, model: string): string[] {
+  return [...groups.entries()].filter(([, ids]) => ids.includes(model)).map(([provider]) => provider);
+}
+
+function suggest(groups: Map<string, string[]>, model: string): string[] {
+  const needle = model.toLowerCase();
+  const out: string[] = [];
+  for (const [provider, ids] of groups) {
+    for (const id of ids) {
+      const hay = id.toLowerCase();
+      if (hay.includes(needle) || needle.includes(hay)) out.push(`${provider}/${id}`);
+    }
+  }
+  return out.slice(0, 5);
+}
+
+export function validateAssignment(assignment: Assignment, groups: Map<string, string[]>): Validation {
+  const row = slotRow(assignment.slot);
+  if (!row) {
+    return { ok: false, message: `slot desconocido: ${assignment.slot}` };
+  }
+  if (!isConfigurableSlot(assignment.slot)) {
+    return {
+      ok: false,
+      message: `${assignment.slot} es un mecanismo, no un paso con modelo: es código determinista y no admite asignación`,
+    };
+  }
+
+  // An empty registry means we cannot check; refusing everything would make a
+  // headless context unusable, so the permissive fallback is deliberate.
+  if (groups.size === 0) return { ok: true, provider: assignment.provider };
+
+  if (assignment.provider) {
+    const ids = groups.get(assignment.provider);
+    if (!ids) {
+      return {
+        ok: false,
+        message: `provider desconocido: ${assignment.provider}. Usá uno de: ${[...groups.keys()].sort().join(", ")}`,
+      };
+    }
+    if (!ids.includes(assignment.model)) {
+      const hints = suggest(groups, assignment.model);
+      return {
+        ok: false,
+        message: `modelo desconocido para ${assignment.provider}: ${assignment.model}${hints.length > 0 ? `. Quizás: ${hints.join(", ")}` : ""}`,
+      };
+    }
+    return { ok: true, provider: assignment.provider };
+  }
+
+  const owners = providersOwning(groups, assignment.model);
+  if (owners.length === 1) return { ok: true, provider: owners[0] };
+  if (owners.length > 1) {
+    return {
+      ok: false,
+      message: `modelo ambiguo: ${assignment.model}. Usá provider/model: ${owners.map((p) => `${p}/${assignment.model}`).join(", ")}`,
+    };
+  }
+
+  const hints = suggest(groups, assignment.model);
+  return {
+    ok: false,
+    message: `modelo desconocido: ${assignment.model}${hints.length > 0 ? `. Quizás: ${hints.join(", ")}` : ""}`,
+  };
+}
+
+/**
+ * The config patch for a validated assignment: only `models`, and inside it only
+ * the one slot. The merge in `src/config.ts` preserves everything else, so an
+ * unrelated key the user put in the file survives.
+ */
+export function assignmentPatch(
+  existing: { models?: Record<string, string> },
+  assignment: Assignment & { provider: string | null },
+): { models: Record<string, string> } {
+  const qualified = assignment.provider ? `${assignment.provider}/${assignment.model}` : assignment.model;
+  return {
+    models: { ...(existing.models ?? {}), [assignment.slot as ConfigurableSlot]: qualified },
+  };
+}

package/src/models/picker.test.ts

@@ -0,0 +1,141 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { CANONICAL_STEPS } from "../manifest.ts";
+import { MECHANISM_PLACEHOLDER } from "./slots.ts";
+import { createPickerState, enter, moveCursor, renderRows, type PickerState } from "./picker.ts";
+
+const groups = new Map([
+  ["anthropic", ["claude-sonnet-4-5", "claude-opus-4-1"]],
+  ["openai-codex", ["gpt-5-codex"]],
+]);
+
+function open(models: Record<string, string> = {}): PickerState {
+  return createPickerState({ models, groups });
+}
+
+// ---------------------------------------------------------------------------
+// Display: seven steps, four of them mechanisms.
+// ---------------------------------------------------------------------------
+test("all seven canonical steps are displayed in protocol order", () => {
+  const rows = renderRows(open());
+  const stepRows = rows.filter((row) => row.kind === "step" || row.kind === "mechanism");
+  assert.deepEqual(stepRows.map((row) => row.id), [...CANONICAL_STEPS]);
+  assert.equal(stepRows.length, 7);
+});
+
+test("the four mechanism rows say mecanismo · sin modelo and are not selectable", () => {
+  const mechanisms = renderRows(open()).filter((row) => row.kind === "mechanism");
+  assert.deepEqual(mechanisms.map((row) => row.id), ["authorize", "classify", "track", "close"]);
+  for (const row of mechanisms) {
+    assert.equal(row.value, MECHANISM_PLACEHOLDER);
+    assert.equal(row.selectable, false, `${row.id} must not be selectable`);
+  }
+});
+
+test("an assigned slot displays its model, an unassigned one its placeholder", () => {
+  const rows = renderRows(open({ implement: "anthropic/claude-opus-4-1" }));
+  assert.equal(rows.find((row) => row.id === "implement")!.value, "anthropic/claude-opus-4-1");
+  assert.equal(rows.find((row) => row.id === "explore")!.value, "sin asignar");
+});
+
+test("there is a save row and a quit row, and they are selectable", () => {
+  const rows = renderRows(open());
+  const actions = rows.filter((row) => row.kind === "action");
+  assert.deepEqual(actions.map((row) => row.id), ["save", "quit"]);
+  for (const row of actions) assert.equal(row.selectable, true);
+});
+
+// ---------------------------------------------------------------------------
+// Navigation skips the non-selectable rows.
+// ---------------------------------------------------------------------------
+test("the cursor starts on the first selectable row", () => {
+  const rows = renderRows(open());
+  assert.equal(rows[open().cursor].selectable, true);
+  assert.equal(rows[open().cursor].id, "default");
+});
+
+test("navigation skips mechanism rows entirely", () => {
+  let state = open();
+  const visited: string[] = [];
+  for (let i = 0; i < 12; i++) {
+    visited.push(renderRows(state)[state.cursor].id);
+    state = moveCursor(state, 1);
+  }
+  for (const mechanism of ["authorize", "classify", "track", "close"]) {
+    assert.ok(!visited.includes(mechanism), `the cursor must never land on ${mechanism}`);
+  }
+  assert.deepEqual([...new Set(visited)], ["default", "orchestrator", "explore", "resolve-uncertainty", "implement", "save", "quit"]);
+});
+
+test("the cursor wraps at both ends and never leaves a selectable row", () => {
+  let state = open();
+  const up = moveCursor(state, -1);
+  assert.equal(renderRows(up)[up.cursor].id, "quit", "moving up from the top wraps to the last row");
+
+  for (let i = 0; i < 30; i++) {
+    state = moveCursor(state, i % 2 === 0 ? 1 : -1);
+    assert.equal(renderRows(state)[state.cursor].selectable, true);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Outcomes: quit writes nothing, save returns the assignment set.
+// ---------------------------------------------------------------------------
+test("quit returns no changes", () => {
+  let state = open({ implement: "anthropic/claude-opus-4-1" });
+  state = { ...state, staged: { ...state.staged, explore: "openai-codex/gpt-5-codex" } };
+
+  const rows = renderRows(state);
+  state = { ...state, cursor: rows.findIndex((row) => row.id === "quit") };
+
+  assert.deepEqual(enter(state), { type: "quit" });
+});
+
+test("save returns the staged assignment set", () => {
+  let state = open({ implement: "anthropic/claude-opus-4-1" });
+  state = { ...state, staged: { ...state.staged, explore: "openai-codex/gpt-5-codex" } };
+
+  const rows = renderRows(state);
+  state = { ...state, cursor: rows.findIndex((row) => row.id === "save") };
+
+  assert.deepEqual(enter(state), {
+    type: "save",
+    models: { implement: "anthropic/claude-opus-4-1", explore: "openai-codex/gpt-5-codex" },
+  });
+});
+
+test("entering a slot row opens that slot's model list", () => {
+  const state = open();
+  const result = enter(state);
+  assert.equal(result.type, "choose");
+  if (result.type !== "choose") return;
+  assert.equal(result.slot, "default");
+  assert.deepEqual(result.options, ["anthropic/claude-sonnet-4-5", "anthropic/claude-opus-4-1", "openai-codex/gpt-5-codex"]);
+});
+
+test("staging a choice does not write and is visible in the rows", () => {
+  let state = open();
+  state = { ...state, staged: { ...state.staged, default: "anthropic/claude-opus-4-1" } };
+  assert.equal(renderRows(state).find((row) => row.id === "default")!.value, "anthropic/claude-opus-4-1");
+  assert.deepEqual(open().staged, {}, "the initial state stages nothing");
+});
+
+// ---------------------------------------------------------------------------
+// The module boundary is the point: no fs, no pi, no TUI.
+// ---------------------------------------------------------------------------
+test("the picker imports no node:fs, no pi and no TUI package", () => {
+  // Comments are free to name what the module refuses to import; executable
+  // lines are not.
+  const source = readFileSync(new URL("./picker.ts", import.meta.url), "utf8")
+    .split("\n")
+    .filter((line) => !/^\s*(\/\/|\*|\/\*)/.test(line))
+    .join("\n");
+  assert.ok(!source.includes("node:fs"), "the picker must not touch the filesystem");
+  assert.ok(!source.includes("@earendil-works/"), "the picker must not import pi or its TUI package");
+  const imports = [...source.matchAll(/from "([^"]+)";/g)].map((m) => m[1]);
+  assert.ok(imports.length > 0, "the scan must actually find the imports");
+  for (const specifier of imports) {
+    assert.ok(specifier.startsWith("."), `unexpected external import: ${specifier}`);
+  }
+});

package/src/models/picker.ts

@@ -0,0 +1,98 @@
+// The picker's decisions, as a pure state machine.
+//
+// Dependency-free by design, after `zero-models-picker.ts:5-11`: no `node:fs`,
+// no pi, and above all no TUI package — not even as a type. The host in
+// `extensions/nodd-models.ts` owns rendering and keystrokes and holds one
+// `PickerState`; every navigation and staging decision is here, where
+// `node --test` can reach it without a terminal.
+//
+// Two properties the tests pin down, because both are easy to lose in a
+// refactor: the four mechanism rows are displayed but never selectable (a cursor
+// that can land on `classify` implies a slot that does not exist), and this
+// module writes nothing. It returns outcomes; the command decides.
+
+import { SLOT_ROWS, type SlotRow } from "./slots.ts";
+
+export type Row = SlotRow & {
+  /** `action` rows are save/quit; the rest come from the slot table. */
+  kind: SlotRow["kind"] | "action";
+  /** The model to show, or the row's placeholder. */
+  value: string;
+  selectable: boolean;
+};
+
+export type PickerState = {
+  cursor: number;
+  /** slot -> `provider/model`, as read from config. */
+  models: Record<string, string>;
+  /** Edits not yet saved. Empty until the user chooses something. */
+  staged: Record<string, string>;
+  groups: Map<string, string[]>;
+};
+
+export type EnterResult =
+  | { type: "choose"; slot: string; options: string[] }
+  | { type: "save"; models: Record<string, string> }
+  | { type: "quit" };
+
+const ACTION_ROWS: Row[] = [
+  { id: "save", kind: "action", placeholder: "", value: "— guardar y salir —", selectable: true },
+  { id: "quit", kind: "action", placeholder: "", value: "— salir sin guardar —", selectable: true },
+];
+
+export function createPickerState(input: {
+  models: Record<string, string>;
+  groups: Map<string, string[]>;
+}): PickerState {
+  const state: PickerState = { cursor: 0, models: { ...input.models }, staged: {}, groups: input.groups };
+  // Start on a row the user can actually act on, whatever the table's shape.
+  return { ...state, cursor: nextSelectable(state, 0, 1) };
+}
+
+/** The full display, in order: globals, the seven steps, then the actions. */
+export function renderRows(state: PickerState): Row[] {
+  const assigned = { ...state.models, ...state.staged };
+  const slots = SLOT_ROWS.map((row): Row => ({
+    ...row,
+    value: row.kind === "mechanism" ? row.placeholder : assigned[row.id] ?? row.placeholder,
+    selectable: row.kind !== "mechanism",
+  }));
+  return [...slots, ...ACTION_ROWS];
+}
+
+/** Every `provider/model` pi can resolve, qualified, in registry order. */
+export function modelOptions(groups: Map<string, string[]>): string[] {
+  const out: string[] = [];
+  for (const [provider, ids] of groups) {
+    for (const id of ids) out.push(`${provider}/${id}`);
+  }
+  return out;
+}
+
+function nextSelectable(state: PickerState, from: number, step: number): number {
+  const rows = renderRows(state);
+  for (let i = 0; i < rows.length; i++) {
+    const index = (((from + i * step) % rows.length) + rows.length) % rows.length;
+    if (rows[index].selectable) return index;
+  }
+  return from;
+}
+
+/** Move the cursor, wrapping at both ends and skipping mechanism rows. */
+export function moveCursor(state: PickerState, step: number): PickerState {
+  const rows = renderRows(state);
+  const start = (((state.cursor + step) % rows.length) + rows.length) % rows.length;
+  return { ...state, cursor: nextSelectable(state, start, step >= 0 ? 1 : -1) };
+}
+
+export function enter(state: PickerState): EnterResult {
+  const row = renderRows(state)[state.cursor];
+  if (row.id === "quit") return { type: "quit" };
+  if (row.id === "save") return { type: "save", models: { ...state.models, ...state.staged } };
+  return { type: "choose", slot: row.id, options: modelOptions(state.groups) };
+}
+
+/** Stage a choice. Nothing is written until the user picks the save row. */
+export function stage(state: PickerState, slot: string, model: string): PickerState {
+  return { ...state, staged: { ...state.staged, [slot]: model } };
+}