pi-custom-provider-model 0.1.1

package/src/probes.ts

@@ -0,0 +1,150 @@
+import { randomBytes, randomInt } from "node:crypto";
+import { deflateSync } from "node:zlib";
+import { Type, validateToolCall, type Api, type AssistantMessage, type Context, type Model, type Tool } from "@earendil-works/pi-ai";
+import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import { endpointUrls } from "./discovery.ts";
+import { APIS, AppError, type Protocol } from "./types.ts";
+
+export const CAPABILITIES = ["chat", "tools", "reasoning", "vision"] as const;
+export type Capability = typeof CAPABILITIES[number];
+export interface ProbeResult {
+  capability: Capability;
+  outcome: "supported" | "inconclusive" | "failed";
+  code: string;
+  ok: boolean;
+  url: string;
+  status?: number;
+  durationMs: number;
+  requests: number;
+  inputTokens: number;
+  outputTokens: number;
+  reasoningTokens?: number;
+  stopReason?: string;
+}
+
+// Generate a fresh, lossless image locally. The answer is never supplied in text.
+function visionChallenge() {
+  const palette: [string, number[]][] = [
+    ["red", [255, 0, 0]], ["green", [0, 180, 0]], ["blue", [0, 0, 255]],
+    ["yellow", [255, 255, 0]], ["black", [0, 0, 0]], ["white", [255, 255, 255]],
+  ];
+  const colors = Array.from({ length: 4 }, () => palette.splice(randomInt(palette.length), 1)[0]);
+  const pixels = Buffer.alloc(128 * (128 * 3 + 1));
+  for (let y = 0; y < 128; y++) for (let x = 0; x < 128; x++) {
+    const rgb = colors[(y >= 64 ? 2 : 0) + (x >= 64 ? 1 : 0)][1];
+    for (let c = 0; c < 3; c++) pixels[y * 385 + 1 + x * 3 + c] = rgb[c];
+  }
+  const chunk = (type: string, data: Buffer) => {
+    const content = Buffer.concat([Buffer.from(type), data]);
+    let crc = 0xffffffff;
+    for (const byte of content) {
+      crc ^= byte;
+      for (let bit = 0; bit < 8; bit++) crc = (crc >>> 1) ^ ((crc & 1) ? 0xedb88320 : 0);
+    }
+    const size = Buffer.alloc(4); size.writeUInt32BE(data.length);
+    const checksum = Buffer.alloc(4); checksum.writeUInt32BE((crc ^ 0xffffffff) >>> 0);
+    return Buffer.concat([size, content, checksum]);
+  };
+  const header = Buffer.alloc(13); header.writeUInt32BE(128, 0); header.writeUInt32BE(128, 4); header[8] = 8; header[9] = 2;
+  const image = Buffer.concat([Buffer.from("89504e470d0a1a0a", "hex"), chunk("IHDR", header), chunk("IDAT", deflateSync(pixels)), chunk("IEND", Buffer.alloc(0))]);
+  return { image: image.toString("base64"), answer: colors.map(([name]) => name) };
+}
+
+const textOf = (message: AssistantMessage) => message.content.filter((c) => c.type === "text").map((c) => c.text).join("").trim();
+const displayUrl = (url: string) => { const parsed = new URL(url); return `${parsed.origin}${parsed.pathname}`; };
+
+export async function probeModel(runtime: ModelRuntime, original: Model<Api>, apiKey: string | undefined, capability: Capability, signal?: AbortSignal): Promise<ProbeResult> {
+  if (!APIS.includes(original.api as Protocol)) throw new AppError("This model's API override cannot be tested here.");
+  const started = Date.now();
+  const timeout = AbortSignal.any([AbortSignal.timeout(capability === "chat" ? 30000 : 60000), ...(signal ? [signal] : [])]);
+  const model = { ...original, maxTokens: Math.min(original.maxTokens, capability === "reasoning" ? 2048 : 256) };
+  // Enable only in this transient runtime so Pi actually sends the capability probe.
+  if (capability === "reasoning") model.reasoning = true;
+  if (capability === "vision") model.input = ["text", "image"];
+  let status: number | undefined;
+  let url = displayUrl(endpointUrls(model.baseUrl, model.api as Protocol).chat);
+  let requests = 0, inputTokens = 0, outputTokens = 0;
+  let reasoningTokens: number | undefined, stopReason: string | undefined;
+  let developerRoleRejected = false;
+  const report = (outcome: ProbeResult["outcome"], code: string): ProbeResult => ({
+    capability, outcome, code, ok: outcome === "supported", url, status, durationMs: Date.now() - started,
+    requests, inputTokens, outputTokens, reasoningTokens, stopReason,
+  });
+  const complete = async (context: Context) => {
+    // Exercise Pi's system/developer-role serialization, not just a bare user message.
+    const result = await runtime.completeSimple(model, { ...context, systemPrompt: "Follow the user's instructions for this synthetic capability check." }, {
+      apiKey, signal: timeout, maxTokens: model.maxTokens, maxRetries: 0, timeoutMs: 60000,
+      transport: "sse", cacheRetention: "none",
+      ...(capability === "reasoning" ? { reasoning: "low" as const, thinkingBudgets: { low: 1024 } } : {}),
+      fetch: async (request, init) => {
+        const target = new URL(request instanceof Request ? request.url : String(request));
+        // Never expose credentials in model-override query strings or URL userinfo.
+        url = displayUrl(target.toString());
+        status = undefined; requests++;
+        const response = await fetch(request, { ...init, redirect: "manual" });
+        status = response.status;
+        return response;
+      },
+    });
+    inputTokens += result.usage.input; outputTokens += result.usage.output;
+    if (result.usage.reasoning !== undefined) reasoningTokens = (reasoningTokens ?? 0) + result.usage.reasoning;
+    stopReason = result.stopReason;
+    if ((status === 400 || status === 422) && result.errorMessage) {
+      // Inspect only for a known compatibility error; never return upstream text.
+      developerRoleRejected = /unknown variant\s+[`'"]developer[`'"]/i.test(result.errorMessage)
+        || /(?:unsupported|invalid)\s+(?:message\s+)?role\s*:?\s*[`'"]?developer\b/i.test(result.errorMessage)
+        || /(?:role\s*:?\s*)?[`'"]?developer[`'"]?\s+(?:role\s+)?(?:is\s+)?not supported/i.test(result.errorMessage);
+    }
+    if (result.stopReason === "error" || result.stopReason === "aborted" || (status !== undefined && status >= 300)) throw new Error("probe failed");
+    return result;
+  };
+  const user = (text: string): Context => ({ messages: [{ role: "user", content: text, timestamp: Date.now() }] });
+  try {
+    if (capability === "chat") {
+      const result = await complete(user("Reply with the single word OK."));
+      return textOf(result) ? report("supported", "chat_reply") : report("inconclusive", "no_text");
+    }
+    if (capability === "tools") {
+      const nonce = randomBytes(8).toString("hex");
+      const tool: Tool = { name: "provider_probe", description: "A harmless local capability check. Returns a receipt to repeat verbatim.",
+        parameters: Type.Object({ nonce: Type.Literal(nonce) }, { additionalProperties: false }) };
+      const context = user(`Call provider_probe once with nonce "${nonce}". After receiving its result, reply with only the receipt value.`);
+      context.tools = [tool];
+      const first = await complete(context);
+      const calls = first.content.filter((c) => c.type === "toolCall");
+      if (!calls.length) return report("inconclusive", "no_tool_call");
+      if (first.stopReason !== "toolUse" || calls.length !== 1) return report("inconclusive", "invalid_tool_call");
+      try { validateToolCall([tool], calls[0]); } catch { return report("inconclusive", "invalid_tool_call"); }
+      const receipt = randomBytes(12).toString("hex");
+      context.messages.push(first, { role: "toolResult", toolCallId: calls[0].id, toolName: tool.name,
+        content: [{ type: "text", text: JSON.stringify({ receipt }) }], isError: false, timestamp: Date.now() });
+      const second = await complete(context);
+      return second.stopReason === "stop" && textOf(second) === receipt ? report("supported", "tool_roundtrip") : report("inconclusive", "tool_result_unconfirmed");
+    }
+    if (capability === "reasoning") {
+      if (model.maxTokens < 2048) return report("inconclusive", "reasoning_budget");
+      const result = await complete(user("Solve this carefully: a box has 17 red and 23 blue balls. How many must be drawn without looking to guarantee 3 of each color? Give a concise answer."));
+      const observed = result.content.some((c) => c.type === "thinking" && (!!c.thinking.trim() || !!c.thinkingSignature || c.redacted));
+      return observed || (result.usage.reasoning ?? 0) > 0 ? report("supported", "reasoning_observed") : report("inconclusive", "no_reasoning_evidence");
+    }
+    const challenge = visionChallenge();
+    const result = await complete({ messages: [{ role: "user", timestamp: Date.now(), content: [
+      { type: "text", text: 'Identify the four solid quadrant colors in the image: top-left, top-right, bottom-left, bottom-right. Reply only with a JSON array of four lowercase color names. Use red, green, blue, yellow, black or white.' },
+      { type: "image", mimeType: "image/png", data: challenge.image },
+    ] }] });
+    let answer: unknown;
+    try { answer = JSON.parse(textOf(result).replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "")); } catch { /* inconclusive */ }
+    return Array.isArray(answer) && answer.length === 4 && answer.every((c, i) => c === challenge.answer[i])
+      ? report("supported", "vision_matched") : report("inconclusive", "vision_unconfirmed");
+  } catch {
+    // Fixed codes only: upstream text, thinking, tool arguments and errors stay private.
+    const code = timeout.aborted ? (signal?.aborted ? "cancelled" : "timeout")
+      : status === 401 || status === 403 ? "auth_failed"
+      : status === 429 ? "rate_limited"
+      : status && status >= 300 && status < 400 ? "redirect"
+      : developerRoleRejected ? "developer_role_unsupported"
+      : status && status >= 500 ? "gateway_error"
+      : status && status >= 400 ? "request_rejected" : status ? "invalid_stream" : "connection_failed";
+    return report("failed", code);
+  }
+}

package/src/server.ts

@@ -0,0 +1,109 @@
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { ProviderService } from "./service.ts";
+import { AppError, object } from "./types.ts";
+
+async function body(request: IncomingMessage) {
+  if (!request.headers["content-type"]?.startsWith("application/json")) throw new AppError("JSON content type required.", 415);
+  let size = 0;
+  const chunks: Buffer[] = [];
+  for await (const chunk of request) {
+    size += chunk.length;
+    if (size > 2_000_000) throw new AppError("Request too large.", 413);
+    chunks.push(chunk);
+  }
+  try { const value = JSON.parse(Buffer.concat(chunks).toString("utf8")); if (object(value)) return value; }
+  catch { /* handled below */ }
+  throw new AppError("Invalid JSON body.");
+}
+
+function json(response: ServerResponse, status: number, value: unknown) {
+  response.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
+  response.end(JSON.stringify(value));
+}
+
+export async function startManager(dir: string, onSaved?: () => Promise<void>) {
+  const token = randomBytes(32).toString("hex");
+  const service = new ProviderService(dir, onSaved);
+  await service.initialize();
+  const lifecycle = new AbortController();
+  let origin = "";
+  let mutationPending = false;
+  const server = createServer(async (request, response) => {
+    response.setHeader("Cache-Control", "no-store");
+    response.setHeader("X-Content-Type-Options", "nosniff");
+    response.setHeader("Referrer-Policy", "no-referrer");
+    response.setHeader("Content-Security-Policy", "default-src 'self'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'self'");
+    try {
+      if (request.headers.host !== new URL(origin).host || (request.headers.origin && request.headers.origin !== origin)) {
+        throw new AppError("Origin not allowed.", 403);
+      }
+      const path = new URL(request.url ?? "/", origin).pathname;
+      if (!path.startsWith("/api/")) {
+        if (request.method !== "GET") throw new AppError("Method not allowed.", 405);
+        const assets: Record<string, [string, string]> = {
+          "/": ["index.html", "text/html"], "/app.js": ["app.js", "text/javascript"], "/style.css": ["style.css", "text/css"],
+        };
+        const asset = assets[path];
+        if (!asset) throw new AppError("Not found.", 404);
+        const content = await readFile(fileURLToPath(new URL(`../web/${asset[0]}`, import.meta.url)));
+        response.writeHead(200, { "Content-Type": `${asset[1]}; charset=utf-8` });
+        response.end(content);
+        return;
+      }
+      const candidate = request.headers["x-manager-token"];
+      if (typeof candidate !== "string" || !/^[a-f0-9]{64}$/.test(candidate) || !timingSafeEqual(Buffer.from(candidate), Buffer.from(token))) {
+        throw new AppError("Open the manager using the link printed by Pi.", 401);
+      }
+      if (path === "/api/state" && request.method === "GET") { json(response, 200, await service.state()); return; }
+      if (request.method !== "POST") throw new AppError("Method not allowed.", 405);
+      const input = await body(request);
+      const controller = new AbortController();
+      response.on("close", () => { if (!response.writableEnded) controller.abort(); });
+      const signal = AbortSignal.any([controller.signal, lifecycle.signal]);
+      const writes = ["/api/save", "/api/delete", "/api/remove-key", "/api/default"];
+      const isWrite = writes.includes(path);
+      if (isWrite && mutationPending) throw new AppError("Another save is in progress. Try again.", 409);
+      if (isWrite) mutationPending = true;
+      try {
+        let result: unknown;
+        switch (path) {
+          case "/api/preview": result = await service.preview(input); break;
+          case "/api/model-limits": result = service.modelLimits(input.modelId); break;
+          case "/api/connection": result = await service.fetchModels(input, false, signal); break;
+          case "/api/discover": result = await service.fetchModels(input, true, signal); break;
+          case "/api/test-model": result = await service.testModel(input.provider, input.modelId, signal, input.capability); break;
+          case "/api/save": result = await service.save(input); break;
+          case "/api/delete": result = await service.remove(input.id, input.revision); break;
+          case "/api/remove-key": result = await service.removeKey(input.id); break;
+          case "/api/default": result = await service.setDefault(input.id, input.modelId); break;
+          default: throw new AppError("Not found.", 404);
+        }
+        json(response, 200, result);
+      } finally { if (isWrite) mutationPending = false; }
+    } catch (error) {
+      if (!response.destroyed && !response.headersSent) {
+        json(response, error instanceof AppError ? error.status : 500,
+          { error: error instanceof AppError ? error.message : "Operation failed. Check the configuration and filesystem permissions." });
+      }
+    }
+  });
+  await new Promise<void>((resolve, reject) => { server.once("error", reject); server.listen(0, "127.0.0.1", resolve); });
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("Could not start manager.");
+  origin = `http://127.0.0.1:${address.port}`;
+  server.unref();
+  let closing: Promise<void> | undefined;
+  return {
+    url: `${origin}/#token=${token}`, origin, token,
+    close() {
+      if (!closing) {
+        lifecycle.abort();
+        closing = new Promise<void>((resolve) => { server.close(() => resolve()); server.closeAllConnections(); });
+      }
+      return closing;
+    },
+  };
+}

package/src/service.ts

@@ -0,0 +1,205 @@
+import { join } from "node:path";
+import { ModelRuntime, readStoredCredential, SettingsManager, VERSION } from "@earendil-works/pi-coding-agent";
+import { ConfigStore, parseDocument, patch, readText } from "./storage.ts";
+import { discover, endpointUrls, requestHeaders } from "./discovery.ts";
+import { CAPABILITIES, probeModel, type Capability } from "./probes.ts";
+import { LimitCatalog, LIMIT_FIELDS } from "./limits.ts";
+import { APIS, AppError, mergeCompat, validateDraft, validateId, type JsonObject, type ModelInput, type ProviderDraft } from "./types.ts";
+
+function visibleCompat(entry: JsonObject): ModelInput["compat"] {
+  return typeof entry.compat?.supportsDeveloperRole === "boolean" ? { supportsDeveloperRole: entry.compat.supportsDeveloperRole } : undefined;
+}
+
+function visibleModel(model: JsonObject): ModelInput {
+  const visible = Object.fromEntries(["id", "name", "input", "reasoning", "contextWindow", "maxTokens"]
+    .filter((key) => model[key] !== undefined).map((key) => [key, model[key]])) as unknown as ModelInput;
+  const compat = visibleCompat(model);
+  if (compat) visible.compat = compat;
+  return visible;
+}
+
+export class ProviderService {
+  readonly store: ConfigStore;
+  private reserved: Set<string> = new Set();
+  private limitCatalog = new LimitCatalog();
+  constructor(readonly dir: string, private onSaved?: () => Promise<void>) { this.store = new ConfigStore(dir); }
+
+  private async runtime() {
+    return ModelRuntime.create({ authPath: join(this.dir, "auth.json"), modelsPath: this.store.path, refreshOnCreate: false });
+  }
+
+  async initialize() {
+    const baseline = await ModelRuntime.create({ authPath: join(this.dir, "auth.json"), modelsPath: null, refreshOnCreate: false });
+    this.reserved = new Set(baseline.getProviders().map((p) => p.id));
+  }
+
+  async state() {
+    const current = await this.store.read();
+    const settings = parseDocument(await readText(join(this.dir, "settings.json")));
+    const providers = Object.entries(current.data.providers).map(([id, entry]) => {
+      const p = entry as JsonObject;
+      const credential = readStoredCredential(id, join(this.dir, "auth.json"));
+      return {
+        id, baseUrl: p.baseUrl ?? "", api: p.api ?? "", authHeader: p.authHeader ?? false,
+        compat: visibleCompat(p),
+        models: (p.models ?? []).map((model: JsonObject) => ({ ...visibleModel(model), limitHints: this.limitCatalog.lookup(model.id) })),
+        readOnly: this.reserved.has(id) || !APIS.includes(p.api) || !!p.oauth,
+        credentialType: credential?.type ?? null,
+        authSource: credential ? `auth.json (${credential.type})` : p.apiKey ? "models.json" : "not configured",
+        hasHiddenSettings: !!(p.headers || p.compat || p.modelOverrides || p.models?.some((m: JsonObject) => m.headers || m.api || m.baseUrl || m.compat)),
+      };
+    });
+    return {
+      dir: this.dir, piVersion: VERSION, revision: current.revision, providers,
+      defaultProvider: settings.defaultProvider ?? "", defaultModel: settings.defaultModel ?? "",
+      reservedIds: [...this.reserved],
+    };
+  }
+
+  private assertEditable(id: string, entry?: JsonObject) {
+    if (this.reserved.has(id) || entry?.oauth || (entry && !APIS.includes(entry.api))) {
+      throw new AppError("This provider is managed by Pi or another integration. Use a new custom provider ID.");
+    }
+  }
+
+  private async prepare(input: unknown, signal?: AbortSignal) {
+    const draft = validateDraft(input);
+    const current = await this.store.read();
+    const existing = current.data.providers[draft.id];
+    this.assertEditable(draft.id, existing);
+    const credential = readStoredCredential(draft.id, join(this.dir, "auth.json"));
+    if (credential?.type === "oauth") throw new AppError("Manage this provider's OAuth credentials using Pi /login.");
+    const runtime = await this.runtime();
+    const providerCompat = mergeCompat(existing?.compat, draft.compat);
+    try {
+      runtime.registerProvider(draft.id, {
+        ...existing, baseUrl: draft.baseUrl, api: draft.api,
+        compat: providerCompat,
+        ...(draft.authHeader === undefined ? {} : { authHeader: draft.authHeader }),
+        models: draft.models.map((model) => {
+          const old = { ...(existing?.models?.find((m: JsonObject) => m.id === model.id) ?? {}) };
+          for (const key of ["name", "input", "reasoning", "contextWindow", "maxTokens"]) delete old[key];
+          const merged = { ...old, ...model };
+          // registerProvider requires complete model metadata, unlike models.json.
+          // These documented Pi defaults are only materialized for the test runtime.
+          return {
+            ...merged, name: model.name ?? model.id, input: model.input ?? ["text"],
+            reasoning: model.reasoning ?? false, contextWindow: model.contextWindow ?? 128000,
+            maxTokens: model.maxTokens ?? 16384,
+            cost: merged.cost ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            compat: { ...providerCompat, ...mergeCompat(old.compat, model.compat) },
+          };
+        }),
+      });
+      await runtime.refresh({ allowNetwork: false, providers: [draft.id], signal });
+      if (!runtime.getProvider(draft.id)) throw new Error("Provider unavailable");
+    } catch {
+      throw new AppError("Pi rejected the provider configuration. Check model fields and any existing advanced settings.");
+    }
+    return { draft, runtime, existing, credential };
+  }
+
+  async preview(input: unknown) {
+    const draft = validateDraft(input);
+    return endpointUrls(draft.baseUrl, draft.api);
+  }
+
+  modelLimits(input: unknown) {
+    if (typeof input !== "string" || !input.trim() || input.length > 300 || /[\x00-\x1f]/.test(input)) throw new AppError("Enter a valid model ID.");
+    return this.limitCatalog.lookup(input.trim());
+  }
+
+  private async resolveAuth(runtime: ModelRuntime, draft: ProviderDraft, signal?: AbortSignal) {
+    try {
+      const auth = await runtime.getAuth(draft.id, { apiKey: draft.apiKey, signal });
+      if (!auth) throw new Error("Missing auth");
+      return auth;
+    } catch {
+      throw new AppError("No usable API key. Enter a key or check the provider's existing Pi credentials/environment variables.", 401);
+    }
+  }
+
+  async fetchModels(input: unknown, allPages: boolean, signal?: AbortSignal) {
+    const { draft, runtime, existing } = await this.prepare(input, signal);
+    const auth = await this.resolveAuth(runtime, draft, signal);
+    const result = await discover({ api: draft.api, baseUrl: draft.baseUrl,
+      headers: requestHeaders(draft.api, auth.auth.apiKey, auth.auth.headers), allPages, signal });
+    for (const model of result.models) {
+      const override = existing?.models?.find((m: JsonObject) => m.id === model.id);
+      const differentEndpoint = (override?.baseUrl && override.baseUrl !== draft.baseUrl) || (override?.api && override.api !== draft.api);
+      model.limitHints = this.limitCatalog.lookup(model.id, differentEndpoint ? {} : model.limitHints);
+      for (const field of LIMIT_FIELDS) {
+        if (model.limitHints[field]) model[field] = model.limitHints[field]!.value;
+        else delete model[field];
+      }
+    }
+    return result;
+  }
+
+  async testModel(input: unknown, modelId: string, signal?: AbortSignal, capability: unknown = "chat") {
+    if (!CAPABILITIES.includes(capability as Capability)) throw new AppError("Choose a supported capability test.");
+    const { draft, runtime } = await this.prepare(input, signal);
+    const model = runtime.getModel(draft.id, modelId);
+    if (!model) throw new AppError("Choose a model first.");
+    await this.resolveAuth(runtime, draft, signal);
+    return probeModel(runtime, model, draft.apiKey, capability as Capability, signal);
+  }
+
+  async save(input: unknown) {
+    const { draft, runtime, credential } = await this.prepare(input);
+    if (!draft.models.length) throw new AppError("Select or add at least one model before saving.");
+    const settings = parseDocument(await readText(join(this.dir, "settings.json")));
+    if (settings.defaultProvider === draft.id && !draft.models.some((m) => m.id === settings.defaultModel)) {
+      throw new AppError("Choose another default model before removing the current default from this provider.");
+    }
+    if (draft.apiKey && credential?.type === "api_key" && credential.env && Object.keys(credential.env).length) {
+      throw new AppError("This credential has provider-scoped environment settings. Update its key with Pi's native auth configuration to preserve those settings.");
+    }
+    await this.store.save(draft);
+    let warning: string | undefined;
+    if (draft.apiKey) {
+      try {
+        // Let Pi own auth.json format, interpolation, locking and login semantics.
+        // The form accepts a literal key. Escape Pi's template/command syntax on storage.
+        const key = draft.apiKey.replace(/\$/g, "$$$$").replace(/^!/, "$!");
+        await runtime.login(draft.id, "api_key", { prompt: async () => key, notify: () => {} });
+      } catch { warning = "Models saved, but key storage did not finish successfully. Use Pi /login before using this provider."; }
+    }
+    try { await this.onSaved?.(); }
+    catch { warning = [warning, "Configuration saved. Reopen Pi /model to refresh the active runtime."].filter(Boolean).join(" "); }
+    return { ok: true, warning, state: await this.state() };
+  }
+
+  async remove(idInput: unknown, expected: string) {
+    const id = validateId(idInput);
+    const current = await this.store.read();
+    this.assertEditable(id, current.data.providers[id]);
+    const settings = parseDocument(await readText(join(this.dir, "settings.json")));
+    if (settings.defaultProvider === id) throw new AppError("Choose another default provider before deleting this one.");
+    await this.store.update(expected, (text) => patch(text, ["providers", id], undefined));
+    await this.onSaved?.();
+    return { ok: true, message: "Provider removed. Its credentials remain in auth.json; remove them separately if needed.", state: await this.state() };
+  }
+
+  async removeKey(idInput: unknown) {
+    const id = validateId(idInput);
+    const credential = readStoredCredential(id, join(this.dir, "auth.json"));
+    if (credential?.type === "oauth") throw new AppError("Use Pi /logout to manage OAuth credentials.");
+    const runtime = await this.runtime();
+    await runtime.logout(id);
+    await this.onSaved?.();
+    return { ok: true, state: await this.state() };
+  }
+
+  async setDefault(idInput: unknown, modelId: unknown) {
+    const id = validateId(idInput);
+    const runtime = await this.runtime();
+    if (typeof modelId !== "string" || !runtime.getModel(id, modelId)) throw new AppError("Save the provider and model before setting a default.");
+    const settings = SettingsManager.create(this.dir, this.dir, { projectTrusted: false });
+    if (settings.drainErrors().length) throw new AppError("Fix settings.json before setting a default.", 409);
+    settings.setDefaultModelAndProvider(id, modelId);
+    await settings.flush();
+    if (settings.drainErrors().length) throw new AppError("Could not save default settings.", 500);
+    return { ok: true, state: await this.state() };
+  }
+}

package/src/standalone.ts

@@ -0,0 +1,15 @@
+import { resolve } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { startManager } from "./server.ts";
+
+const argument = process.argv.indexOf("--agent-dir");
+if (argument >= 0 && !process.argv[argument + 1]) throw new Error("--agent-dir needs a directory.");
+// Development mode defaults to an isolated sandbox. --real-config is explicit.
+const dir = argument >= 0 ? resolve(process.argv[argument + 1])
+  : process.argv.includes("--real-config") ? getAgentDir() : resolve(".sandbox", "agent");
+const manager = await startManager(dir);
+console.log(`Pi Provider Manager\nConfig: ${dir}\nOpen: ${manager.url}\nCtrl+C to stop.`);
+const keepAlive = setInterval(() => {}, 60000);
+const stop = async () => { clearInterval(keepAlive); await manager.close(); };
+process.once("SIGINT", stop);
+process.once("SIGTERM", stop);

package/src/storage.ts

@@ -0,0 +1,117 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, writeFile, rename, unlink, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { applyEdits, modify, parse, type ParseError } from "jsonc-parser";
+import lockfile from "proper-lockfile";
+import { AppError, mergeCompat, object, type JsonObject, type ModelInput, type ProviderDraft } from "./types.ts";
+
+function storedModel(model: ModelInput) {
+  const { compat: edits, ...fields } = model;
+  const compat = mergeCompat(undefined, edits);
+  return { ...fields, ...(Object.keys(compat).length ? { compat } : {}) };
+}
+
+export function parseDocument(text: string): JsonObject {
+  const errors: ParseError[] = [];
+  const value = parse(text.replace(/^\uFEFF/, ""), errors, { allowTrailingComma: false });
+  if (errors.length || !object(value)) throw new AppError("Configuration contains invalid JSON. Fix it before saving.", 409);
+  return value;
+}
+
+export function patch(text: string, path: (string | number)[], value: unknown): string {
+  return applyEdits(text, modify(text, path, value, {
+    formattingOptions: { insertSpaces: true, tabSize: 2, eol: text.includes("\r\n") ? "\r\n" : "\n" },
+  }));
+}
+
+export function revision(text: string): string {
+  return createHash("sha256").update(text).digest("hex");
+}
+
+export async function readText(path: string, fallback = "{}\n"): Promise<string> {
+  try { return await readFile(path, "utf8"); }
+  catch (error: any) { if (error.code === "ENOENT") return fallback; throw error; }
+}
+
+async function atomicWrite(path: string, content: string): Promise<void> {
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, content, { encoding: "utf8", mode: 0o600 });
+    await rename(temporary, path);
+  } finally { await unlink(temporary).catch(() => {}); }
+}
+
+export class ConfigStore {
+  readonly path: string;
+  constructor(readonly dir: string) { this.path = join(dir, "models.json"); }
+
+  async read() {
+    const text = await readText(this.path, '{"providers":{}}\n');
+    const data = parseDocument(text);
+    if (!object(data.providers)) throw new AppError("models.json must contain a providers object.", 409);
+    return { text, data, revision: revision(text) };
+  }
+
+  async update(expected: string, transform: (text: string, data: JsonObject) => string) {
+    await mkdir(this.dir, { recursive: true });
+    const release = await lockfile.lock(this.path, { realpath: false, retries: { retries: 20, minTimeout: 20, maxTimeout: 100 } });
+    try {
+      const current = await this.read();
+      if (current.revision !== expected) throw new AppError("Configuration changed in another window. Reload before saving.", 409);
+      const next = transform(current.text, current.data);
+      parseDocument(next);
+      if (next === current.text) return current.revision;
+      const backupDir = join(this.dir, "provider-manager-backups");
+      await mkdir(backupDir, { recursive: true, mode: 0o700 });
+      await writeFile(join(backupDir, `${Date.now()}-${randomUUID()}.json`), current.text, { mode: 0o600 });
+      // Catch edits made by a non-cooperating editor during backup creation.
+      if ((await this.read()).revision !== current.revision) throw new AppError("Configuration changed while saving. Reload and retry.", 409);
+      await atomicWrite(this.path, next);
+      const backups = (await readdir(backupDir)).filter((f) => /^\d+-[\da-f-]+\.json$/.test(f)).sort().reverse();
+      await Promise.all(backups.slice(10).map((f) => unlink(join(backupDir, f)).catch(() => {})));
+      return revision(next);
+    } finally { await release(); }
+  }
+
+  async save(draft: ProviderDraft) {
+    if (!draft.revision) throw new AppError("Reload configuration before saving.", 409);
+    return this.update(draft.revision, (text, data) => {
+      const path = ["providers", draft.id];
+      const existing = data.providers[draft.id];
+      const compat = mergeCompat(undefined, draft.compat);
+      if (!existing) return patch(text, path, {
+        baseUrl: draft.baseUrl, api: draft.api,
+        ...(Object.keys(compat).length ? { compat } : {}),
+        ...(draft.authHeader === undefined ? {} : { authHeader: draft.authHeader }), models: draft.models.map(storedModel),
+      });
+      let next = patch(patch(text, [...path, "baseUrl"], draft.baseUrl), [...path, "api"], draft.api);
+      if (draft.authHeader !== undefined) next = patch(next, [...path, "authHeader"], draft.authHeader);
+      if (draft.compat?.supportsDeveloperRole !== undefined && (draft.compat.supportsDeveloperRole !== null || existing.compat?.supportsDeveloperRole !== undefined)) {
+        next = patch(next, [...path, "compat", "supportsDeveloperRole"], draft.compat.supportsDeveloperRole ?? undefined);
+      }
+      // Update by ID, preserving hidden fields and comments on surviving models.
+      let oldModels = existing.models ?? [];
+      const keep = new Set(draft.models.map((m) => m.id));
+      for (let i = oldModels.length - 1; i >= 0; i--) {
+        if (!keep.has(oldModels[i].id)) next = patch(next, [...path, "models", i], undefined);
+      }
+      oldModels = parseDocument(next).providers[draft.id].models ?? [];
+      if (!existing.models) next = patch(next, [...path, "models"], []);
+      for (const model of draft.models) {
+        const index = oldModels.findIndex((m: JsonObject) => m.id === model.id);
+        if (index < 0) {
+          next = patch(next, [...path, "models", -1], storedModel(model));
+          oldModels.push(model);
+        } else {
+          for (const field of ["name", "contextWindow", "maxTokens", "reasoning", "input"] as const) {
+            next = patch(next, [...path, "models", index, field], model[field]);
+          }
+          if (model.compat?.supportsDeveloperRole !== undefined && (model.compat.supportsDeveloperRole !== null || oldModels[index].compat?.supportsDeveloperRole !== undefined)) {
+            next = patch(next, [...path, "models", index, "compat", "supportsDeveloperRole"], model.compat.supportsDeveloperRole ?? undefined);
+          }
+        }
+      }
+      return next;
+    });
+  }
+}