@pi-archimedes/subagent 1.8.2 → 1.9.0

package/src/local-config.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import {
+  mkdirSync,
+  rmSync,
+  existsSync,
+  readdirSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  readLocalConfig,
+  writeLocalModel,
+  deleteLocalModel,
+} from "./local-config.js";
+
+// Redirect getAgentDir() to a temp directory via PI_CODING_AGENT_DIR.
+// This must happen before any function calls so getLocalConfigPath()
+// resolves to our sandbox directory.
+const testDir = join(tmpdir(), "pi-test-local-config");
+process.env.PI_CODING_AGENT_DIR = testDir;
+
+describe("local-config", () => {
+  beforeEach(() => {
+    mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  describe("readLocalConfig", () => {
+    it("returns {} when file does not exist", () => {
+      expect(readLocalConfig()).toEqual({});
+    });
+
+    it("returns {} when file is corrupt JSON", () => {
+      const path = join(testDir, "agents.local.json");
+      writeFileSync(path, "{ broken json", "utf-8");
+      expect(readLocalConfig()).toEqual({});
+    });
+
+    it("parses valid JSON correctly", () => {
+      const path = join(testDir, "agents.local.json");
+      writeFileSync(
+        path,
+        JSON.stringify({ codex: { model: "o1" } }),
+        "utf-8",
+      );
+      expect(readLocalConfig()).toEqual({ codex: { model: "o1" } });
+    });
+  });
+
+  describe("writeLocalModel", () => {
+    it("creates file and writes model entry", () => {
+      writeLocalModel("codex", "o1");
+      expect(readLocalConfig()).toEqual({ codex: { model: "o1" } });
+    });
+
+    it("preserves other agent entries when updating one", () => {
+      writeLocalModel("codex", "o1");
+      writeLocalModel("claude", "claude-3.7");
+      expect(readLocalConfig()).toEqual({
+        codex: { model: "o1" },
+        claude: { model: "claude-3.7" },
+      });
+    });
+
+    it("handles model values with special characters", () => {
+      writeLocalModel("openai", "openai/gpt-4.1");
+      expect(readLocalConfig()).toEqual({
+        openai: { model: "openai/gpt-4.1" },
+      });
+    });
+  });
+
+  describe("deleteLocalModel", () => {
+    it("removes the specified agent entry", () => {
+      writeLocalModel("codex", "o1");
+      deleteLocalModel("codex");
+      expect(readLocalConfig()).toEqual({});
+    });
+
+    it("is a no-op when agent does not exist", () => {
+      writeLocalModel("codex", "o1");
+      deleteLocalModel("nonexistent");
+      expect(readLocalConfig()).toEqual({ codex: { model: "o1" } });
+    });
+
+    it("preserves other entries", () => {
+      writeLocalModel("codex", "o1");
+      writeLocalModel("claude", "claude-3.7");
+      deleteLocalModel("codex");
+      expect(readLocalConfig()).toEqual({ claude: { model: "claude-3.7" } });
+    });
+
+    it("does not create file when deleting absent agent on clean install", () => {
+      // No agents.local.json exists yet. Deleting an absent agent should
+      // be a true no-op — it must NOT materialise an empty file on disk.
+      deleteLocalModel("nonexistent");
+      expect(existsSync(join(testDir, "agents.local.json"))).toBe(false);
+    });
+  });
+
+  it("leaves no .tmp file behind after successful write", () => {
+    writeLocalModel("codex", "o1");
+    const files = readdirSync(testDir);
+    expect(files).not.toContain("agents.local.json.tmp");
+    expect(existsSync(join(testDir, "agents.local.json"))).toBe(true);
+  });
+});

package/src/local-config.ts

@@ -0,0 +1,74 @@
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  renameSync,
+  unlinkSync,
+} from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+/** Per-agent local overrides stored in agents.local.json */
+export type LocalConfig = Record<string, { model?: string }>;
+
+/** Returns the path to agents.local.json inside the agent directory. */
+export function getLocalConfigPath(): string {
+  return join(getAgentDir(), "agents.local.json");
+}
+
+/** Read the full agents.local.json, returning {} if missing or corrupt. */
+function readLocalConfigRaw(): LocalConfig {
+  const path = getLocalConfigPath();
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+/** Read agents.local.json, returning {} if missing or corrupt. */
+export function readLocalConfig(): LocalConfig {
+  return readLocalConfigRaw();
+}
+
+/**
+ * Write the full config atomically: write to .tmp then rename.
+ * Falls back to a direct write if rename fails; cleans up .tmp on failure.
+ * Follows the pattern in packages/core/src/settings-io.ts.
+ */
+function writeConfigAtomic(config: LocalConfig): void {
+  const path = getLocalConfigPath();
+  const tmpPath = path + ".tmp";
+  writeFileSync(tmpPath, JSON.stringify(config, null, 2), "utf-8");
+  try {
+    renameSync(tmpPath, path);
+  } catch {
+    try {
+      unlinkSync(tmpPath);
+    } catch {
+      // ignore — tmp file may not exist
+    }
+    writeFileSync(path, JSON.stringify(config, null, 2), "utf-8");
+  }
+}
+
+/** Set the local model override for a given agent, preserving existing entries. */
+export function writeLocalModel(agentName: string, model: string): void {
+  const config = readLocalConfig();
+  config[agentName] = { ...config[agentName], model };
+  writeConfigAtomic(config);
+}
+
+/** Delete the local model override for a given agent (no-op if absent). */
+export function deleteLocalModel(agentName: string): void {
+  const config = readLocalConfig();
+  if (!(agentName in config)) return;
+  delete config[agentName];
+  writeConfigAtomic(config);
+}
+
+/** Write the full local config atomically (backup+restore safe). */
+export function setLocalConfig(config: LocalConfig): void {
+  writeConfigAtomic(config);
+}

package/src/model-validation.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from "vitest";
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { validateModel, firstError } from "./model-validation.js";
+
+function mockRegistry(models: Array<{ provider: string; id: string }>): ModelRegistry {
+  return { getAll: () => models } as unknown as ModelRegistry;
+}
+
+const REGISTRY = mockRegistry([
+  { provider: "anthropic", id: "claude-sonnet-4-5" },
+  { provider: "openai", id: "gpt-5" },
+  { provider: "openrouter", id: "claude-sonnet-4-5" }, // ambiguous bare id across providers
+]);
+
+describe("validateModel", () => {
+  it("accepts a valid canonical provider/id", () => {
+    expect(validateModel("anthropic/claude-sonnet-4-5", REGISTRY)).toEqual({ ok: true });
+  });
+
+  it("accepts case-insensitive provider/id", () => {
+    expect(validateModel("Anthropic/Claude-Sonnet-4-5", REGISTRY)).toEqual({ ok: true });
+  });
+
+  it("accepts a valid unique bare id", () => {
+    expect(validateModel("gpt-5", REGISTRY)).toEqual({ ok: true });
+  });
+
+  it("rejects an ambiguous bare id (>=2 providers)", () => {
+    const r = validateModel("claude-sonnet-4-5", REGISTRY);
+    expect(r.ok).toBe(false);
+  });
+
+  it("rejects an unknown string", () => {
+    const r = validateModel("general", REGISTRY);
+    expect(r.ok).toBe(false);
+    expect((r as { error: string }).error).toContain("not found");
+  });
+
+  it("accepts a thinking suffix by matching the prefix", () => {
+    expect(validateModel("gpt-5:high", REGISTRY)).toEqual({ ok: true });
+  });
+
+  it("accepts provider/id with a thinking suffix", () => {
+    expect(validateModel("anthropic/claude-sonnet-4-5:high", REGISTRY)).toEqual({ ok: true });
+  });
+
+  it("returns ok for empty/undefined model", () => {
+    expect(validateModel(undefined, REGISTRY)).toEqual({ ok: true });
+    expect(validateModel("", REGISTRY)).toEqual({ ok: true });
+    expect(validateModel("   ", REGISTRY)).toEqual({ ok: true });
+  });
+
+  it("returns ok when the registry is empty (defer to child)", () => {
+    expect(validateModel("anything", mockRegistry([]))).toEqual({ ok: true });
+  });
+
+  it("emits the agent-name hint when model equals agentName", () => {
+    const r = validateModel("general", REGISTRY, { agentName: "general" });
+    expect(r.ok).toBe(false);
+    expect((r as { error: string }).error).toContain("looks like an agent name");
+  });
+
+  it("emits the config-pointing message when agentFilePath is set", () => {
+    const r = validateModel("bogus", REGISTRY, {
+      agentName: "reviewer",
+      agentFilePath: "/home/u/.agents/agents/reviewer.md",
+    });
+    expect(r.ok).toBe(false);
+    const err = (r as { error: string }).error;
+    expect(err).toContain("/home/u/.agents/agents/reviewer.md");
+    expect(err).toContain("Fix the model field");
+  });
+});
+
+describe("firstError", () => {
+  it("returns undefined when all ok", () => {
+    expect(firstError({ ok: true }, { ok: true })).toBeUndefined();
+  });
+  it("returns the first error string", () => {
+    expect(firstError({ ok: true }, { ok: false, error: "boom" }, { ok: false, error: "later" })).toBe("boom");
+  });
+});

package/src/model-validation.ts

@@ -0,0 +1,93 @@
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+
+export interface ValidateModelContext {
+  /** Agent name the caller passed (used to detect the agent→model mirror footgun). */
+  agentName?: string | undefined;
+  /** File path of the agent config whose `model:` field is being validated. */
+  agentFilePath?: string | undefined;
+}
+
+export type ValidateModelResult = { ok: true } | { ok: false; error: string };
+
+/**
+ * Find a model by reference, mirroring pi core's `findExactModelReferenceMatch`
+ * rules (that function is not exported; rules read from pi core source):
+ *   - canonical "provider/id" (case-insensitive), OR
+ *   - bare "id" (case-insensitive); ambiguous (>=2 providers share the id) → no match.
+ */
+function findMatch<T extends { provider: string; id: string }>(
+  ref: string,
+  models: readonly T[],
+): T | undefined {
+  const lower = ref.toLowerCase();
+  if (!lower) return undefined;
+  // canonical provider/id
+  const canonical = models.find((m) => `${m.provider}/${m.id}`.toLowerCase() === lower);
+  if (canonical) return canonical;
+  // bare id — must be unique across providers
+  const idMatches = models.filter((m) => m.id.toLowerCase() === lower);
+  return idMatches.length === 1 ? idMatches[0] : undefined;
+}
+
+/**
+ * Validate that a model reference string resolves to a known model.
+ *
+ * Pure gate: returns `{ ok: true }` when valid (no resolved model object —
+ * callers forward the ORIGINAL string to spawn.ts unchanged, preserving any
+ * `:high` thinking suffix for the child's own resolver).
+ *
+ * Matching is against `registry.getAll()` (all known models — a pure
+ * name-existence check; auth is deferred to the child, matching how the
+ * child's `resolveCliModel` resolves against all models). Exact-match only;
+ * fuzzy/alias patterns the child might accept are rejected here (acceptable —
+ * `model` override is discouraged, so legitimate fuzzy usage is ~0).
+ */
+export function validateModel(
+  model: string | undefined,
+  registry: ModelRegistry,
+  context: ValidateModelContext = {},
+): ValidateModelResult {
+  if (!model || !model.trim()) return { ok: true };
+  const all = registry.getAll();
+  if (all.length === 0) return { ok: true }; // unconfigured registry — defer to child
+
+  const ref = model.trim();
+  let matched = findMatch(ref, all);
+  // Thinking-suffix tolerant: if the full string failed but it has a colon,
+  // retry with the prefix before the last colon (handles "claude-sonnet-4-5:high").
+  if (!matched && ref.includes(":")) {
+    const prefix = ref.slice(0, ref.lastIndexOf(":"));
+    if (prefix) matched = findMatch(prefix, all);
+  }
+  if (matched) return { ok: true };
+
+  const sample = all.slice(0, 5).map((m) => `${m.provider}/${m.id}`).join(", ");
+  const more = all.length > 5 ? `, … (${all.length} total)` : "";
+
+  // Prioritize file-path message when both agentName and agentFilePath are set
+  // (more actionable than the generic agent-name hint)
+  if (context.agentFilePath) {
+    return {
+      ok: false,
+      error: `Agent "${context.agentName ?? "unknown"}" is configured with an invalid model "${model}" (in ${context.agentFilePath}). Fix the model field or agents.local.json. Available: ${sample}${more}.`,
+    };
+  }
+  if (context.agentName && ref === context.agentName.trim()) {
+    return {
+      ok: false,
+      error: `Model "${model}" not found — it looks like an agent name, not a model. Omit the model parameter; the agent's configured model or the parent's current model will be used. Available models include: ${sample}${more}.`,
+    };
+  }
+  return {
+    ok: false,
+    error: `Model "${model}" not found. Available models include: ${sample}${more}.`,
+  };
+}
+
+/** Return the first error message from the given results, or undefined if all ok. */
+export function firstError(...results: ValidateModelResult[]): string | undefined {
+  for (const r of results) {
+    if (!r.ok) return r.error;
+  }
+  return undefined;
+}