@kontextmind/kxm 0.6.0

package/plugins/kxm/src/memory.ts

@@ -0,0 +1,385 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { parse, stringify } from "yaml";
+import { redactSecrets } from "./redact.ts";
+
+export const MEMORY_SCHEMA = "kxm.memory.v1" as const;
+export const MEMORY_BRIEF_SCHEMA = "kxm.memory-brief.v1" as const;
+export const MEMORY_MARKER_START = "<!-- kxm:memory:start -->";
+export const MEMORY_MARKER_END = "<!-- kxm:memory:end -->";
+
+export type MemoryScope = "agent" | "project" | "run" | "operator";
+export type MemoryAuthority = "instruction" | "evidence" | "promoted";
+export type MemoryConfidence = "verified" | "probable" | "uncertain";
+export type MemoryLifecycle = "active" | "deprecated" | "superseded";
+
+const VALID_SCOPES = new Set<MemoryScope>(["agent", "project", "run", "operator"]);
+const VALID_AUTHORITIES = new Set<MemoryAuthority>(["instruction", "evidence", "promoted"]);
+const VALID_CONFIDENCES = new Set<MemoryConfidence>(["verified", "probable", "uncertain"]);
+const VALID_LIFECYCLES = new Set<MemoryLifecycle>(["active", "deprecated", "superseded"]);
+
+const BANNED_CONTROL_PLANE_FIELDS = new Set([
+  "permissions",
+  "tools",
+  "allow",
+  "deny",
+  "grants",
+  "approval",
+  "policy",
+  "scopes",
+  "credentials",
+  "secrets",
+  "token",
+  "apiKey",
+  "password",
+]);
+
+export interface MemoryProvenance {
+  sourceType: string;
+  sourceRef?: string;
+  runId?: string;
+  timestamp?: string;
+}
+
+export interface MemoryRecord {
+  schema: typeof MEMORY_SCHEMA;
+  id: string;
+  scope: MemoryScope;
+  kind: string;
+  summary: string;
+  provenance: MemoryProvenance;
+  authority: MemoryAuthority;
+  confidence: MemoryConfidence;
+  lifecycle: MemoryLifecycle;
+  evidenceRefs: string[];
+  body?: string;
+}
+
+export interface MemoryBrief {
+  schema: typeof MEMORY_BRIEF_SCHEMA;
+  generatedAt: string;
+  count: number;
+  facts: MemoryRecord[];
+}
+
+function parseFrontmatter(content: string): { frontmatter: string; body: string } {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!match) {
+    throw new Error("memory file must contain YAML frontmatter enclosed in '---'");
+  }
+  return { frontmatter: match[1] ?? "", body: match[2]?.trim() ?? "" };
+}
+
+export function parseMemoryRecord(raw: string, filename = "memory.md"): MemoryRecord {
+  const { frontmatter, body } = parseFrontmatter(raw);
+  const data = parse(frontmatter) as Record<string, unknown> | null;
+  if (!data || typeof data !== "object" || Array.isArray(data)) {
+    throw new Error(`invalid YAML frontmatter in ${filename}`);
+  }
+
+  // 1. Control-plane rejection
+  for (const field of BANNED_CONTROL_PLANE_FIELDS) {
+    if (field in data) {
+      throw new Error(`memory record ${filename} may not carry control-plane field '${field}'`);
+    }
+  }
+
+  // 2. Schema check
+  if (data.schema !== MEMORY_SCHEMA) {
+    throw new Error(`memory record ${filename} has unsupported schema: expected ${MEMORY_SCHEMA}, got ${String(data.schema)}`);
+  }
+
+  // 3. ID validation
+  const id = typeof data.id === "string" ? data.id.trim() : "";
+  if (!id || !/^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/i.test(id)) {
+    throw new Error(`memory record ${filename} has invalid id: ${String(data.id)}`);
+  }
+
+  // 4. Scope validation
+  const scope = data.scope as MemoryScope;
+  if (!VALID_SCOPES.has(scope)) {
+    throw new Error(`memory record ${filename} has invalid scope: must be one of agent, project, run, operator`);
+  }
+
+  // 5. Kind validation
+  const kind = typeof data.kind === "string" ? data.kind.trim() : "";
+  if (!kind) {
+    throw new Error(`memory record ${filename} is missing kind`);
+  }
+
+  // 6. Summary validation & secret redaction
+  const rawSummary = typeof data.summary === "string" ? data.summary.trim() : "";
+  if (!rawSummary) {
+    throw new Error(`memory record ${filename} is missing summary`);
+  }
+  const summary = redactSecrets(rawSummary);
+
+  // 7. Provenance validation & secret redaction
+  const rawProv = data.provenance as Record<string, unknown> | undefined;
+  if (!rawProv || typeof rawProv !== "object" || typeof rawProv.sourceType !== "string" || !rawProv.sourceType.trim()) {
+    throw new Error(`memory record ${filename} is missing provenance.sourceType`);
+  }
+  const provenance: MemoryProvenance = {
+    sourceType: rawProv.sourceType.trim(),
+    ...(typeof rawProv.sourceRef === "string" ? { sourceRef: redactSecrets(rawProv.sourceRef.trim()) } : {}),
+    ...(typeof rawProv.runId === "string" ? { runId: rawProv.runId.trim() } : {}),
+    ...(typeof rawProv.timestamp === "string" ? { timestamp: rawProv.timestamp.trim() } : {}),
+  };
+
+  // 8. Authority validation
+  const authority = data.authority as MemoryAuthority;
+  if (!VALID_AUTHORITIES.has(authority)) {
+    throw new Error(`memory record ${filename} has invalid authority: ${String(data.authority)}`);
+  }
+
+  // 9. Confidence validation
+  const confidence = data.confidence as MemoryConfidence;
+  if (!VALID_CONFIDENCES.has(confidence)) {
+    throw new Error(`memory record ${filename} has invalid confidence: ${String(data.confidence)}`);
+  }
+
+  // 10. Lifecycle validation
+  const lifecycle = data.lifecycle as MemoryLifecycle;
+  if (!VALID_LIFECYCLES.has(lifecycle)) {
+    throw new Error(`memory record ${filename} has invalid lifecycle: ${String(data.lifecycle)}`);
+  }
+
+  // 11. EvidenceRefs validation
+  const rawRefs = Array.isArray(data.evidenceRefs) ? data.evidenceRefs : [];
+  const evidenceRefs = rawRefs.map(String);
+
+  return {
+    schema: MEMORY_SCHEMA,
+    id,
+    scope,
+    kind,
+    summary,
+    provenance,
+    authority,
+    confidence,
+    lifecycle,
+    evidenceRefs,
+    ...(body ? { body } : {}),
+  };
+}
+
+export function formatMemoryRecord(record: MemoryRecord): string {
+  const frontmatter: Record<string, unknown> = {
+    schema: record.schema,
+    id: record.id,
+    scope: record.scope,
+    kind: record.kind,
+    summary: record.summary,
+    provenance: record.provenance,
+    authority: record.authority,
+    confidence: record.confidence,
+    lifecycle: record.lifecycle,
+    evidenceRefs: record.evidenceRefs,
+  };
+  const yamlText = stringify(frontmatter).trim();
+  const bodyText = record.body?.trim() ?? "";
+  return bodyText ? `---\n${yamlText}\n---\n\n${bodyText}\n` : `---\n${yamlText}\n---\n`;
+}
+
+export function memoryDirectories(repoRoot: string): { memoryDir: string; candidatesDir: string } {
+  const root = resolve(repoRoot);
+  const memoryDir = join(root, ".kxm", "memory");
+  const candidatesDir = join(memoryDir, "candidates");
+  return { memoryDir, candidatesDir };
+}
+
+export function loadAuthoredMemory(repoRoot: string): MemoryRecord[] {
+  const { memoryDir } = memoryDirectories(repoRoot);
+  if (!existsSync(memoryDir)) return [];
+
+  const records: MemoryRecord[] = [];
+  const entries = readdirSync(memoryDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isFile() && extname(entry.name) === ".md") {
+      const fullPath = join(memoryDir, entry.name);
+      try {
+        const text = readFileSync(fullPath, "utf8");
+        const record = parseMemoryRecord(text, entry.name);
+        if (record.lifecycle === "active") {
+          records.push(record);
+        }
+      } catch (error) {
+        // Log or rethrow depending on strictness
+        throw new Error(`failed to parse authored memory file ${entry.name}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+  }
+
+  return records.sort((left, right) => left.id.localeCompare(right.id));
+}
+
+export function loadCandidateMemory(repoRoot: string): MemoryRecord[] {
+  const { candidatesDir } = memoryDirectories(repoRoot);
+  if (!existsSync(candidatesDir)) return [];
+
+  const records: MemoryRecord[] = [];
+  const entries = readdirSync(candidatesDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isFile() && extname(entry.name) === ".md") {
+      const fullPath = join(candidatesDir, entry.name);
+      try {
+        const text = readFileSync(fullPath, "utf8");
+        const record = parseMemoryRecord(text, entry.name);
+        records.push(record);
+      } catch (error) {
+        throw new Error(`failed to parse candidate memory file ${entry.name}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+  }
+
+  return records.sort((left, right) => left.id.localeCompare(right.id));
+}
+
+export function createMemoryNote(
+  repoRoot: string,
+  summary: string,
+  options: {
+    scope?: MemoryScope | undefined;
+    kind?: string | undefined;
+    body?: string | undefined;
+    sourceRef?: string | undefined;
+    runId?: string | undefined;
+  } = {},
+): { record: MemoryRecord; path: string } {
+  const { candidatesDir } = memoryDirectories(repoRoot);
+  mkdirSync(candidatesDir, { recursive: true });
+
+  const scope: MemoryScope = options.scope ?? "project";
+  if (!VALID_SCOPES.has(scope)) {
+    throw new Error(`invalid memory note scope: ${scope}; must be one of agent, project, run, operator`);
+  }
+
+  const hex = randomUUID().replaceAll("-", "").slice(0, 12);
+  const id = `cand_${scope}_${hex}`;
+  const record: MemoryRecord = {
+    schema: MEMORY_SCHEMA,
+    id,
+    scope,
+    kind: options.kind ?? "learning",
+    summary: redactSecrets(summary.trim()),
+    provenance: {
+      sourceType: "command",
+      sourceRef: options.sourceRef ? redactSecrets(options.sourceRef) : "kxm memory note",
+      ...(options.runId ? { runId: options.runId } : {}),
+      timestamp: new Date().toISOString(),
+    },
+    authority: "evidence",
+    confidence: "probable",
+    lifecycle: "active",
+    evidenceRefs: [],
+    ...(options.body ? { body: options.body.trim() } : {}),
+  };
+
+  const targetPath = join(candidatesDir, `${id}.md`);
+  writeFileSync(targetPath, formatMemoryRecord(record), "utf8");
+  return { record, path: targetPath };
+}
+
+export function generateMemoryBrief(repoRoot: string): MemoryBrief {
+  const facts = loadAuthoredMemory(repoRoot);
+  return {
+    schema: MEMORY_BRIEF_SCHEMA,
+    generatedAt: new Date().toISOString(),
+    count: facts.length,
+    facts,
+  };
+}
+
+export function formatMemoryBriefText(brief: MemoryBrief): string {
+  if (brief.facts.length === 0) {
+    return "No active project memory facts.";
+  }
+
+  const lines: string[] = [`Project memory (${brief.facts.length} active fact${brief.facts.length === 1 ? "" : "s"}):`, ""];
+  for (const fact of brief.facts) {
+    lines.push(`• [${fact.scope}] [${fact.kind}] ${fact.summary} (${fact.id})`);
+  }
+  return lines.join("\n");
+}
+
+export function formatHarnessMemoryBlock(records: MemoryRecord[]): string {
+  const contentLines: string[] = [MEMORY_MARKER_START, "## Project memory (read-only projection)", ""];
+  if (records.length === 0) {
+    contentLines.push("*No active project memory.*");
+  } else {
+    for (const record of records) {
+      contentLines.push(`- **[${record.scope}]** [${record.kind}] ${record.summary} (\`${record.id}\`)`);
+    }
+  }
+  contentLines.push(MEMORY_MARKER_END);
+  return contentLines.join("\n");
+}
+
+export function updateHarnessDocument(filePath: string, block: string, defaultHeader: string): boolean {
+  let original = "";
+  if (existsSync(filePath)) {
+    original = readFileSync(filePath, "utf8");
+  }
+
+  let updated = "";
+  if (original.includes(MEMORY_MARKER_START) && original.includes(MEMORY_MARKER_END)) {
+    const startIdx = original.indexOf(MEMORY_MARKER_START);
+    const endIdx = original.indexOf(MEMORY_MARKER_END) + MEMORY_MARKER_END.length;
+    updated = original.slice(0, startIdx) + block + original.slice(endIdx);
+  } else if (original.length > 0) {
+    // If "## Do not" exists, insert before it; else append to end
+    const doNotIdx = original.indexOf("## Do not");
+    if (doNotIdx !== -1) {
+      updated = `${original.slice(0, doNotIdx).trimEnd()}\n\n${block}\n\n${original.slice(doNotIdx)}`;
+    } else {
+      updated = `${original.trimEnd()}\n\n${block}\n`;
+    }
+  } else {
+    updated = `${defaultHeader.trimEnd()}\n\n${block}\n`;
+  }
+
+  if (updated !== original) {
+    writeFileSync(filePath, updated, "utf8");
+    return true;
+  }
+  return false;
+}
+
+export function syncHarnessMemory(repoRoot: string): { updated: string[]; created: string[] } {
+  const root = resolve(repoRoot);
+  const records = loadAuthoredMemory(root);
+  const block = formatHarnessMemoryBlock(records);
+
+  const updated: string[] = [];
+  const created: string[] = [];
+
+  // 1. AGENTS.md
+  const agentsPath = join(root, "AGENTS.md");
+  const agentsHeader = "# AGENTS\n\nFollow project instructions.\n";
+  const agentsExisted = existsSync(agentsPath);
+  if (updateHarnessDocument(agentsPath, block, agentsHeader)) {
+    if (agentsExisted) updated.push("AGENTS.md");
+    else created.push("AGENTS.md");
+  }
+
+  // 2. CLAUDE.md
+  const claudePath = join(root, "CLAUDE.md");
+  const claudeHeader = `# KXM (Claude)\n\nFollow [\`AGENTS.md\`](AGENTS.md). Official phase tracking:\n[\`plans/implementation-plan.md\`](plans/implementation-plan.md#tracking-working-tree-not-a-release).\n\nYou are the **planner / architecture critic** unless the human explicitly asks\nyou to implement. Default writer is native Grok CLI (\`grok --model grok-4.6\`).\nIf \`grok\` is logged out, fail closed; do not fall back to Pi. Your reviews are\nartifacts, not hub \`peer-reply\` evidence.\n`;
+  const claudeExisted = existsSync(claudePath);
+  if (updateHarnessDocument(claudePath, block, claudeHeader)) {
+    if (claudeExisted) updated.push("CLAUDE.md");
+    else created.push("CLAUDE.md");
+  }
+
+  // 3. GEMINI.md
+  const geminiPath = join(root, "GEMINI.md");
+  const geminiHeader = `# KXM (Gemini / Antigravity)\n\nFollow [\`AGENTS.md\`](AGENTS.md). Official phase tracking:\n[\`plans/implementation-plan.md\`](plans/implementation-plan.md#tracking-working-tree-not-a-release).\n\nGoogle / Antigravity CLI (\`agy\`) is an admitted native writer and experiment edit route\nfor Gemini models. Starting rotation remains Grok.\n`;
+  const geminiExisted = existsSync(geminiPath);
+  if (updateHarnessDocument(geminiPath, block, geminiHeader)) {
+    if (geminiExisted) updated.push("GEMINI.md");
+    else created.push("GEMINI.md");
+  }
+
+  return { updated, created };
+}

package/plugins/kxm/src/nous-pi.ts

@@ -0,0 +1,287 @@
+/**
+ * Legacy Pi registerProvider glue for opt-in Nous routes.
+ * No @earendil-works/pi-ai import. Direct auth is NOUS_API_KEY only.
+ */
+
+import { readFile } from "node:fs/promises";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  NOUS_DIRECT_BASE_URL,
+  NOUS_DIRECT_ID,
+  NOUS_PROXY_DEFAULT_BASE_URL,
+  NOUS_PROXY_ID,
+  NOUS_PROXY_PLACEHOLDER_KEY,
+  buildModelConfigs,
+  fetchNousModels,
+  guidanceFor,
+  isLoopbackUrl,
+  modelsUrl,
+  parseCatalogPin,
+  parseNousEnv,
+  sanitizeNousText,
+  type BuiltModel,
+  type CatalogLoad,
+  type DiscoveryOutcome,
+  type DiscoveryProvenance,
+  type GuidanceMessage,
+  type NousCatalogPin,
+  type NousEnvParse,
+  type NousProviderKind,
+} from "./nous-provider.ts";
+
+export interface NousProviderRegistration {
+  id: string;
+  registered: number;
+  skipped: number;
+  error?: string;
+  reason?: string;
+  provenance?: DiscoveryProvenance;
+}
+
+export interface NousRegistrationReport {
+  optedIn: boolean;
+  direct: NousProviderRegistration;
+  proxy: NousProviderRegistration;
+  guidance: GuidanceMessage[];
+  registeredProviders: string[];
+}
+
+export interface NousRegisterDeps {
+  env?: NodeJS.Dict<string>;
+  fetch?: typeof fetch;
+  readFile?: (path: string) => Promise<string>;
+  nowMs?: number;
+}
+
+type LegacyPi = Pick<ExtensionAPI, "registerProvider">;
+
+const emptySide = (id: string): NousProviderRegistration => ({ id, registered: 0, skipped: 0 });
+
+export function emptyNousReport(): NousRegistrationReport {
+  return {
+    optedIn: false,
+    direct: emptySide(NOUS_DIRECT_ID),
+    proxy: emptySide(NOUS_PROXY_ID),
+    guidance: [],
+    registeredProviders: [],
+  };
+}
+
+/**
+ * Factory helper: unset stays synchronous; invalid tokens fail closed without
+ * fetch; opted-in routes discover then register before Pi lists models.
+ */
+export function nousFactoryWork(
+  pi: ExtensionAPI,
+  onReport: (report: NousRegistrationReport) => void,
+  deps: NousRegisterDeps = {},
+): void | Promise<void> {
+  const env = deps.env ?? process.env;
+  const parsed = parseNousEnv(env);
+  if (parsed.status === "unset") {
+    onReport(emptyNousReport());
+    return;
+  }
+  if (parsed.status === "invalid") {
+    onReport({
+      ...emptyNousReport(),
+      optedIn: true,
+      guidance: guidanceFor({ parsed }),
+    });
+    return;
+  }
+  return registerNousProviders(pi, deps).then(onReport);
+}
+
+export async function registerNousProviders(
+  pi: LegacyPi,
+  deps: NousRegisterDeps = {},
+): Promise<NousRegistrationReport> {
+  const env = deps.env ?? process.env;
+  const parsed = parseNousEnv(env);
+  if (parsed.status === "unset") return emptyNousReport();
+  if (parsed.status === "invalid") {
+    return { ...emptyNousReport(), optedIn: true, guidance: guidanceFor({ parsed }) };
+  }
+
+  const report = emptyNousReport();
+  report.optedIn = true;
+  let pin: NousCatalogPin | undefined;
+  let catalogError: string | undefined;
+  if (parsed.catalogFile) {
+    const loaded = await loadCatalog(parsed.catalogFile, deps);
+    if (loaded.ok) pin = loaded.pin;
+    else catalogError = loaded.reason;
+  }
+
+  const skipped: Array<{ id: string; reason: string }> = [];
+  let directDiscovery: DiscoveryOutcome | undefined;
+  let proxyDiscovery: DiscoveryOutcome | undefined;
+  let proxyUrlInvalid = false;
+  const directHasKey = hasDirectKey(env);
+
+  if (parsed.providers.includes("direct")) {
+    const result = await registerRoute({
+      pi,
+      route: "direct",
+      env,
+      parsed,
+      pin,
+      hasKey: directHasKey,
+      ...(deps.fetch ? { fetchImpl: deps.fetch } : {}),
+      ...(deps.nowMs !== undefined ? { nowMs: deps.nowMs } : {}),
+    });
+    report.direct = result.side;
+    directDiscovery = result.discovery;
+    skipped.push(...result.skipped);
+    if (result.registered) report.registeredProviders.push(NOUS_DIRECT_ID);
+  }
+
+  if (parsed.providers.includes("proxy")) {
+    if (!isLoopbackUrl(parsed.proxyUrl)) {
+      proxyUrlInvalid = true;
+      report.proxy = {
+        id: NOUS_PROXY_ID,
+        registered: 0,
+        skipped: 0,
+        error: "non-loopback",
+        reason: "proxy URL is not loopback http(s)",
+      };
+    } else {
+      const result = await registerRoute({
+        pi,
+        route: "proxy",
+        env,
+        parsed,
+        pin,
+        hasKey: true,
+        ...(deps.fetch ? { fetchImpl: deps.fetch } : {}),
+        ...(deps.nowMs !== undefined ? { nowMs: deps.nowMs } : {}),
+      });
+      report.proxy = result.side;
+      proxyDiscovery = result.discovery;
+      skipped.push(...result.skipped);
+      if (result.registered) report.registeredProviders.push(NOUS_PROXY_ID);
+    }
+  }
+
+  report.guidance = guidanceFor({
+    parsed,
+    directHasKey,
+    proxyUrlInvalid,
+    skipped,
+    ...(directDiscovery ? { directDiscovery } : {}),
+    ...(proxyDiscovery ? { proxyDiscovery } : {}),
+    ...(catalogError ? { catalogError } : {}),
+  });
+  return report;
+}
+
+async function registerRoute(input: {
+  pi: LegacyPi;
+  route: NousProviderKind;
+  env: NodeJS.Dict<string>;
+  parsed: Extract<NousEnvParse, { status: "ready" }>;
+  pin: NousCatalogPin | undefined;
+  fetchImpl?: typeof fetch;
+  hasKey: boolean;
+  nowMs?: number;
+}): Promise<{
+  side: NousProviderRegistration;
+  discovery?: DiscoveryOutcome;
+  skipped: Array<{ id: string; reason: string }>;
+  registered: boolean;
+}> {
+  const providerId = input.route === "direct" ? NOUS_DIRECT_ID : NOUS_PROXY_ID;
+  const baseUrl = input.route === "direct" ? NOUS_DIRECT_BASE_URL : input.parsed.proxyUrl;
+  const side: NousProviderRegistration = { id: providerId, registered: 0, skipped: 0 };
+
+  if (input.route === "direct" && !input.hasKey) {
+    registerLegacy(input.pi, providerId, baseUrl, "$NOUS_API_KEY", []);
+    return { side, skipped: [], registered: true };
+  }
+
+  const authorization = input.route === "direct"
+    ? input.env.NOUS_API_KEY
+    : NOUS_PROXY_PLACEHOLDER_KEY;
+
+  const discovery = await fetchNousModels({
+    url: modelsUrl(baseUrl),
+    timeoutMs: input.parsed.timeoutMs,
+    ...(authorization ? { authorization } : {}),
+    ...(input.fetchImpl ? { fetchImpl: input.fetchImpl } : {}),
+    ...(input.nowMs !== undefined ? { nowMs: input.nowMs } : {}),
+  });
+
+  if (!discovery.ok) {
+    side.error = discovery.error;
+    side.reason = discovery.reason;
+    registerLegacy(input.pi, providerId, baseUrl, apiKeyRef(input.route), []);
+    return { side, discovery, skipped: [], registered: true };
+  }
+
+  if (discovery.provenance) side.provenance = discovery.provenance;
+  const built = buildModelConfigs(discovery.models, input.pin, input.route);
+  side.registered = built.registered.length;
+  side.skipped = built.skipped.length;
+  registerLegacy(input.pi, providerId, baseUrl, apiKeyRef(input.route), built.registered);
+  return { side, discovery, skipped: built.skipped, registered: true };
+}
+
+function apiKeyRef(route: NousProviderKind): string {
+  return route === "direct" ? "$NOUS_API_KEY" : NOUS_PROXY_PLACEHOLDER_KEY;
+}
+
+function registerLegacy(
+  pi: LegacyPi,
+  id: string,
+  baseUrl: string,
+  apiKey: string,
+  models: BuiltModel[],
+): void {
+  if (typeof pi.registerProvider !== "function") {
+    throw new Error("Pi registerProvider is unavailable");
+  }
+  pi.registerProvider(id, {
+    name: id === NOUS_DIRECT_ID ? "Nous" : "Nous subscription proxy",
+    baseUrl,
+    apiKey,
+    api: "openai-completions",
+    authHeader: true,
+    models: models.map((model) => ({
+      id: model.id,
+      name: model.name,
+      reasoning: model.reasoning === true,
+      input: model.input && model.input.length > 0 ? model.input : ["text"],
+      // Upper-bound rates only: Pi cost.tiers uses strict > and can underquote.
+      cost: {
+        input: model.cost.input,
+        output: model.cost.output,
+        cacheRead: model.cost.cacheRead,
+        cacheWrite: model.cost.cacheWrite,
+      },
+      contextWindow: model.contextWindow,
+      maxTokens: model.maxTokens,
+    })),
+  });
+}
+
+function hasDirectKey(env: NodeJS.Dict<string>): boolean {
+  const key = env.NOUS_API_KEY;
+  return typeof key === "string" && key.trim().length > 0;
+}
+
+async function loadCatalog(path: string, deps: NousRegisterDeps): Promise<CatalogLoad> {
+  try {
+    const read = deps.readFile ?? ((filePath: string) => readFile(filePath, "utf8"));
+    const text = await read(path);
+    return parseCatalogPin(JSON.parse(text) as unknown, deps.nowMs ?? Date.now());
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      return { ok: false, reason: "catalog file is not valid JSON" };
+    }
+    return { ok: false, reason: sanitizeNousText(error instanceof Error ? error.message : "catalog file could not be read") };
+  }
+}
+
+export const NOUS_PROXY_DEFAULT = NOUS_PROXY_DEFAULT_BASE_URL;