@evandu/super-pi 0.1.104 → 0.1.106

package/dist/server/providers.d.ts

@@ -0,0 +1,160 @@
+import type { PublicProvider } from "./types.js";
+/**
+ * THE PROVIDERS A PERSON ADDED, and the two files that make Pi know about them.
+ *
+ * WHAT THIS REPLACES. Pi's own answer to "I want to use a model that is not in your list" is a
+ * hand-written `~/.pi/agent/models.json` (the provider and model definitions) plus a key in
+ * `~/.pi/agent/auth.json`. There is no command for it and no UI for it - the files are the interface.
+ * This module is that interface, in a form: the settings window collects the same fields and writes
+ * the same files.
+ *
+ * WHY THE FILES AND NOT A RUNTIME REGISTRATION. Pi's SDK can register a provider in memory
+ * (`ModelRuntime.registerProvider`) and hold a key in memory (`setRuntimeApiKey`), and both are
+ * tempting - they touch nothing of the user's. They do not work here, for two reasons that are
+ * facts about this codebase rather than opinions:
+ *
+ *   1. `ModelRuntime` is created PER SESSION here (`pi-session.ts:498`), so a provider registered on
+ *      one instance is invisible to the next conversation.
+ *   2. A spawned Pi (`pi --mode rpc`, the one-shot mode) has no provider-registration command at all
+ *      - its RPC surface is `set_model` and `get_available_models` and nothing that defines a
+ *      provider. A provider that exists only in this process's memory cannot reach it.
+ *
+ * The files, by contrast, are read by BOTH paths: the SDK's `ModelRuntime.create()` loads
+ * `models.json` and `auth.json` from Pi's agent dir, and a spawned Pi does the same. So writing them
+ * is the only way one setting works everywhere - including in the terminal, where `pi` sees the same
+ * provider the person just added here.
+ *
+ * THE TRUTH SOURCE IS OURS, THE FILES ARE DERIVED. `<dataDir>/providers.json` (0600, holds the key)
+ * says which providers Super Pi manages. Pi's two files are rewritten from it after every change, by
+ * MERGING: only the provider ids we manage are touched, everything else in those files is left alone.
+ * That is what makes "delete the provider I added" safe, and it is why a person who hand-wrote their
+ * own provider keeps it.
+ *
+ * THE KEY NEVER REACHES THE BROWSER. It lives in two files with restrictive permissions - ours and
+ * Pi's `auth.json` - and in neither the state snapshot nor any event. What the browser gets is
+ * `hasKey: true`.
+ */
+/** One model of a provider, as the settings window collects it. */
+export type ProviderModelDefinition = {
+    id: string;
+    name?: string;
+    reasoning?: boolean;
+    imageInput?: boolean;
+    contextWindow?: number;
+    maxTokens?: number;
+    /**
+     * The two compatibility switches an OpenAI-compatible server sometimes needs.
+     *
+     * `supportsDeveloperRole: false` makes Pi send the system prompt as a `system` message instead of
+     * a `developer` one, which is what relays and local servers that predate the `developer` role need.
+     * `supportsReasoningEffort: false` stops Pi from sending `reasoning_effort` to a server that does
+     * not know the field. Both are per-provider in Pi's schema and per-model here, because a server can
+     * be one and not the other.
+     */
+    supportsDeveloperRole?: boolean;
+    supportsReasoningEffort?: boolean;
+};
+/** One provider, as the settings window collects it. */
+export type ProviderDefinition = {
+    id: string;
+    name?: string;
+    baseUrl: string;
+    api: string;
+    /** The API key. Stored, never broadcast. */
+    apiKey?: string;
+    models: ProviderModelDefinition[];
+};
+/** One model, as the browser sees it. No key, no nothing secret - there is nothing secret here. */
+export type { PublicProvider, PublicProviderModel } from "./types.js";
+/**
+ * The API adapters Pi ships, as the ids a provider may name.
+ *
+ * Taken from Pi's own `KnownApi` union (`pi-ai/dist/types.d.ts`) rather than invented: the id ends
+ * up in `models.json` and Pi looks the adapter up by exactly this string, and an unknown one fails
+ * at REQUEST time ("No API provider registered for api: ...") rather than at load time. Offering the
+ * list in the form is the difference between a person finding the right value and guessing.
+ */
+export declare const KNOWN_APIS: readonly ["openai-completions", "anthropic-messages", "openai-responses", "azure-openai-responses", "openai-codex-responses", "mistral-conversations", "google-generative-ai", "google-vertex", "bedrock-converse-stream", "pi-messages"];
+/**
+ * Pi's global configuration directory - where `models.json` and `auth.json` live.
+ *
+ * `PI_CODING_AGENT_DIR` wins, because that is Pi's own rule (`core/config.js:getAgentDir`) and a
+ * person who set it expects Pi to read its config from there. The fallback is Pi's own default,
+ * `~/.pi/agent`, with the home directory taken from the environment rather than from `os.homedir()`
+ * - on Windows the two disagree often enough to matter.
+ */
+export declare function piAgentDir(): string;
+/** Pi's provider and model definitions. */
+export declare function piModelsPath(agentDir?: string): string;
+/** Pi's credential store. */
+export declare function piAuthPath(agentDir?: string): string;
+/**
+ * Strips JSONC comments, the way Pi's own parser does.
+ *
+ * Pi reads `models.json` with comments allowed, so a person may well have written comments in it -
+ * and Super Pi has to be able to READ that file to merge into it. A naive strip would corrupt a
+ * string that contains `//` (a base URL with a path, an api key with a slash), so this walks the
+ * text and tracks whether it is inside a string.
+ */
+export declare function stripJsonComments(text: string): string;
+/**
+ * The providers Super Pi manages, and the writes that make Pi know about them.
+ *
+ * The class owns three files: its own registry, Pi's `models.json` and Pi's `auth.json`. Only the
+ * first is a truth source; the other two are rewritten from it.
+ */
+export declare class ProviderRegistry {
+    private readonly dataDir;
+    private readonly piDir;
+    /**
+     * `piDir` is Pi's own configuration directory, and it is a PARAMETER rather than a lookup at
+     * write time for one reason: a test that forgets to set `PI_CODING_AGENT_DIR` would then write to
+     * the developer's real `~/.pi/agent`. With the directory in hand, a test cannot reach it by
+     * accident - it has to be given one.
+     */
+    constructor(dataDir: string, piDir?: string);
+    /** Super Pi's own registry: the providers it manages, with their keys. */
+    private get registryPath();
+    /**
+     * Reads the registry.
+     *
+     * A missing file is an empty registry, not an error: nobody has added a provider yet. A file that
+     * cannot be parsed IS an error, because reading it as empty would let the next write replace
+     * somebody's keys with nothing.
+     */
+    load(): Promise<ProviderDefinition[]>;
+    /** Writes the registry. The key lives here, so the file is 0600. */
+    save(providers: ProviderDefinition[]): Promise<void>;
+    /**
+     * Makes Pi's files match the registry.
+     *
+     * `previousIds` are the providers Super Pi managed before this change: they are the only ones
+     * whose entries may be REMOVED. An id that is in Pi's `models.json` and not in `previousIds` belongs
+     * to the person who wrote that file, and touching it would be Super Pi editing a provider it does
+     * not own - so the write is refused with a message naming the id.
+     */
+    applyToPi(previous: ProviderDefinition[], next: ProviderDefinition[]): Promise<void>;
+    /**
+     * Writes the keys into Pi's `auth.json`.
+     *
+     * A credential is REMOVED only when it is the one Super Pi wrote: the same provider id and the
+     * same key. A person who replaced our key with their own - or who ran Pi's `/login` and put an
+     * OAuth token there - keeps it. Deleting somebody else's credential because they removed our
+     * provider would be the worst version of this feature.
+     *
+     * TWO CASES, and the second is the one that is easy to miss: the provider can be gone ENTIRELY
+     * (it was removed), or it can still be there with its key GONE (the person asked for the key to be
+     * cleared). Both have to take the credential with them, or "clear the key" would leave a working
+     * key sitting in Pi's auth file.
+     */
+    private applyKeysToPi;
+}
+/** The provider list as the browser sees it: the key becomes a fact. */
+export declare function publicProviders(providers: ProviderDefinition[]): PublicProvider[];
+/**
+ * Checks what the form collected and returns it in the shape the registry stores.
+ *
+ * EVERY RULE HERE SAYS WHY, because a message a person reads is the only validation they get: the
+ * server cannot ask a follow-up question, so a refusal has to name the field and the reason.
+ */
+export declare function validateProvider(input: unknown): ProviderDefinition;

package/dist/server/providers.js

@@ -0,0 +1,396 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+/**
+ * The API adapters Pi ships, as the ids a provider may name.
+ *
+ * Taken from Pi's own `KnownApi` union (`pi-ai/dist/types.d.ts`) rather than invented: the id ends
+ * up in `models.json` and Pi looks the adapter up by exactly this string, and an unknown one fails
+ * at REQUEST time ("No API provider registered for api: ...") rather than at load time. Offering the
+ * list in the form is the difference between a person finding the right value and guessing.
+ */
+export const KNOWN_APIS = [
+    "openai-completions",
+    "anthropic-messages",
+    "openai-responses",
+    "azure-openai-responses",
+    "openai-codex-responses",
+    "mistral-conversations",
+    "google-generative-ai",
+    "google-vertex",
+    "bedrock-converse-stream",
+    "pi-messages",
+];
+/** The context window a model gets when the form does not say. Pi's own default. */
+const DEFAULT_CONTEXT_WINDOW = 128000;
+/** The output budget a model gets when the form does not say. Pi's own default. */
+const DEFAULT_MAX_TOKENS = 16384;
+/**
+ * Pi's global configuration directory - where `models.json` and `auth.json` live.
+ *
+ * `PI_CODING_AGENT_DIR` wins, because that is Pi's own rule (`core/config.js:getAgentDir`) and a
+ * person who set it expects Pi to read its config from there. The fallback is Pi's own default,
+ * `~/.pi/agent`, with the home directory taken from the environment rather than from `os.homedir()`
+ * - on Windows the two disagree often enough to matter.
+ */
+export function piAgentDir() {
+    const configured = process.env.PI_CODING_AGENT_DIR?.trim();
+    if (configured)
+        return configured;
+    const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+    return home ? join(home, ".pi", "agent") : join(".pi", "agent");
+}
+/** Pi's provider and model definitions. */
+export function piModelsPath(agentDir = piAgentDir()) {
+    return join(agentDir, "models.json");
+}
+/** Pi's credential store. */
+export function piAuthPath(agentDir = piAgentDir()) {
+    return join(agentDir, "auth.json");
+}
+/**
+ * Strips JSONC comments, the way Pi's own parser does.
+ *
+ * Pi reads `models.json` with comments allowed, so a person may well have written comments in it -
+ * and Super Pi has to be able to READ that file to merge into it. A naive strip would corrupt a
+ * string that contains `//` (a base URL with a path, an api key with a slash), so this walks the
+ * text and tracks whether it is inside a string.
+ */
+export function stripJsonComments(text) {
+    let out = "";
+    let inString = false;
+    let inLineComment = false;
+    let inBlockComment = false;
+    for (let index = 0; index < text.length; index++) {
+        const char = text[index];
+        const next = text[index + 1];
+        if (inLineComment) {
+            if (char === "\n") {
+                inLineComment = false;
+                out += char;
+            }
+            else
+                out += " ";
+            continue;
+        }
+        if (inBlockComment) {
+            if (char === "*" && next === "/") {
+                inBlockComment = false;
+                out += "  ";
+                index++;
+            }
+            else
+                out += char === "\n" ? "\n" : " ";
+            continue;
+        }
+        if (inString) {
+            out += char;
+            if (char === "\\" && next !== undefined) {
+                out += next;
+                index++;
+            }
+            else if (char === "\"")
+                inString = false;
+            continue;
+        }
+        if (char === "\"") {
+            inString = true;
+            out += char;
+            continue;
+        }
+        if (char === "/" && next === "/") {
+            inLineComment = true;
+            out += "  ";
+            index++;
+            continue;
+        }
+        if (char === "/" && next === "*") {
+            inBlockComment = true;
+            out += "  ";
+            index++;
+            continue;
+        }
+        out += char;
+    }
+    return out;
+}
+/** Reads a JSON file, returning undefined when it does not exist. */
+async function readJsonFile(path) {
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    if (!text.trim())
+        return undefined;
+    try {
+        return JSON.parse(stripJsonComments(text));
+    }
+    catch (error) {
+        // A file Super Pi cannot parse is a file Super Pi must NOT overwrite: the person who wrote it
+        // put something in there this server does not understand, and replacing it with a parse of
+        // nothing would destroy their work.
+        throw new Error(`${path} 解析失败，为避免覆盖你的文件已停止写入：${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** The permissions a file already has, or 0600 when it is new. */
+async function fileMode(path) {
+    try {
+        const info = await stat(path);
+        return info.mode & 0o777;
+    }
+    catch {
+        return 0o600;
+    }
+}
+/**
+ * Writes a file atomically: a temporary file next to it, then a rename over the target.
+ *
+ * A rename is atomic on every platform Super Pi runs on, so a reader - Pi, or a person with an
+ * editor open - sees either the old file or the new one, never half of each. Writing in place would
+ * leave a window in which Pi reads a truncated `models.json` and loses every provider in it.
+ */
+async function writeJsonAtomic(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    const mode = await fileMode(path);
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode });
+        await rename(temporary, path);
+    }
+    catch (error) {
+        await writeFile(temporary, "{}", { mode }).catch(() => { });
+        throw error;
+    }
+}
+/**
+ * The provider entry Super Pi writes into Pi's `models.json`.
+ *
+ * NO `apiKey` HERE, and that is a decision with a reason behind it: a value in `models.json` goes
+ * through Pi's config-value syntax, where `$NAME` means "read this environment variable" and
+ * `!command` means "run this and take its output". A key that happens to start with a dollar sign
+ * would be silently turned into something else. `auth.json` stores the key verbatim, and it is
+ * where Pi's own `/login` puts it, so that is where this goes.
+ */
+function toPiProvider(provider) {
+    const models = provider.models.map(model => ({
+        id: model.id,
+        name: model.name ?? model.id,
+        reasoning: model.reasoning ?? false,
+        input: model.imageInput ? ["text", "image"] : ["text"],
+        contextWindow: model.contextWindow ?? DEFAULT_CONTEXT_WINDOW,
+        maxTokens: model.maxTokens ?? DEFAULT_MAX_TOKENS,
+        ...(model.supportsDeveloperRole === undefined && model.supportsReasoningEffort === undefined
+            ? {}
+            : {
+                compat: {
+                    ...(model.supportsDeveloperRole === undefined ? {} : { supportsDeveloperRole: model.supportsDeveloperRole }),
+                    ...(model.supportsReasoningEffort === undefined ? {} : { supportsReasoningEffort: model.supportsReasoningEffort }),
+                },
+            }),
+    }));
+    return {
+        ...(provider.name ? { name: provider.name } : {}),
+        baseUrl: provider.baseUrl,
+        api: provider.api,
+        models,
+    };
+}
+/**
+ * The providers Super Pi manages, and the writes that make Pi know about them.
+ *
+ * The class owns three files: its own registry, Pi's `models.json` and Pi's `auth.json`. Only the
+ * first is a truth source; the other two are rewritten from it.
+ */
+export class ProviderRegistry {
+    dataDir;
+    piDir;
+    /**
+     * `piDir` is Pi's own configuration directory, and it is a PARAMETER rather than a lookup at
+     * write time for one reason: a test that forgets to set `PI_CODING_AGENT_DIR` would then write to
+     * the developer's real `~/.pi/agent`. With the directory in hand, a test cannot reach it by
+     * accident - it has to be given one.
+     */
+    constructor(dataDir, piDir = piAgentDir()) {
+        this.dataDir = dataDir;
+        this.piDir = piDir;
+    }
+    /** Super Pi's own registry: the providers it manages, with their keys. */
+    get registryPath() {
+        return join(this.dataDir, "providers.json");
+    }
+    /**
+     * Reads the registry.
+     *
+     * A missing file is an empty registry, not an error: nobody has added a provider yet. A file that
+     * cannot be parsed IS an error, because reading it as empty would let the next write replace
+     * somebody's keys with nothing.
+     */
+    async load() {
+        const raw = await readJsonFile(this.registryPath);
+        if (!raw || typeof raw !== "object")
+            return [];
+        const providers = raw.providers;
+        if (!Array.isArray(providers))
+            return [];
+        return providers.filter((provider) => Boolean(provider) && typeof provider === "object");
+    }
+    /** Writes the registry. The key lives here, so the file is 0600. */
+    async save(providers) {
+        await writeJsonAtomic(this.registryPath, { providers });
+    }
+    /**
+     * Makes Pi's files match the registry.
+     *
+     * `previousIds` are the providers Super Pi managed before this change: they are the only ones
+     * whose entries may be REMOVED. An id that is in Pi's `models.json` and not in `previousIds` belongs
+     * to the person who wrote that file, and touching it would be Super Pi editing a provider it does
+     * not own - so the write is refused with a message naming the id.
+     */
+    async applyToPi(previous, next) {
+        const previousIds = new Set(previous.map((provider) => provider.id));
+        const nextIds = new Set(next.map((provider) => provider.id));
+        const modelsPath = piModelsPath(this.piDir);
+        const existing = await readJsonFile(modelsPath) ?? {};
+        const existingProviders = existing.providers ?? {};
+        for (const provider of next) {
+            if (existingProviders[provider.id] !== undefined && !previousIds.has(provider.id)) {
+                throw new Error(`Pi 的 models.json 里已经有供应商「${provider.id}」，而它不是 Super Pi 添加的，所以没有动它。请换一个供应商 id，或者先在 Pi 的模型配置文件里删掉它。`);
+            }
+        }
+        const mergedProviders = { ...existingProviders };
+        for (const provider of next)
+            mergedProviders[provider.id] = toPiProvider(provider);
+        // The ones we managed and no longer do.
+        for (const id of previousIds)
+            if (!nextIds.has(id))
+                delete mergedProviders[id];
+        await writeJsonAtomic(modelsPath, { ...existing, providers: mergedProviders });
+        await this.applyKeysToPi(previous, next);
+    }
+    /**
+     * Writes the keys into Pi's `auth.json`.
+     *
+     * A credential is REMOVED only when it is the one Super Pi wrote: the same provider id and the
+     * same key. A person who replaced our key with their own - or who ran Pi's `/login` and put an
+     * OAuth token there - keeps it. Deleting somebody else's credential because they removed our
+     * provider would be the worst version of this feature.
+     *
+     * TWO CASES, and the second is the one that is easy to miss: the provider can be gone ENTIRELY
+     * (it was removed), or it can still be there with its key GONE (the person asked for the key to be
+     * cleared). Both have to take the credential with them, or "clear the key" would leave a working
+     * key sitting in Pi's auth file.
+     */
+    async applyKeysToPi(previous, next) {
+        const authPath = piAuthPath(this.piDir);
+        const auth = await readJsonFile(authPath) ?? {};
+        const nextById = new Map(next.map((provider) => [provider.id, provider]));
+        for (const provider of next) {
+            if (provider.apiKey)
+                auth[provider.id] = { type: "api_key", key: provider.apiKey };
+        }
+        for (const provider of previous) {
+            const updated = nextById.get(provider.id);
+            // The key is still wanted (the provider is unchanged, or it has a new one) - nothing to do.
+            if (updated && updated.apiKey)
+                continue;
+            if (!updated && !provider.apiKey)
+                continue;
+            const stored = auth[provider.id];
+            if (stored?.type === "api_key" && provider.apiKey && stored.key === provider.apiKey)
+                delete auth[provider.id];
+        }
+        await writeJsonAtomic(authPath, auth);
+    }
+}
+/** The provider list as the browser sees it: the key becomes a fact. */
+export function publicProviders(providers) {
+    return providers.map(provider => ({
+        id: provider.id,
+        name: provider.name ?? provider.id,
+        baseUrl: provider.baseUrl,
+        api: provider.api,
+        hasKey: Boolean(provider.apiKey),
+        models: provider.models.map(model => ({
+            id: model.id,
+            name: model.name ?? model.id,
+            reasoning: model.reasoning ?? false,
+            imageInput: model.imageInput ?? false,
+            contextWindow: model.contextWindow ?? DEFAULT_CONTEXT_WINDOW,
+            maxTokens: model.maxTokens ?? DEFAULT_MAX_TOKENS,
+        })),
+    }));
+}
+/**
+ * Checks what the form collected and returns it in the shape the registry stores.
+ *
+ * EVERY RULE HERE SAYS WHY, because a message a person reads is the only validation they get: the
+ * server cannot ask a follow-up question, so a refusal has to name the field and the reason.
+ */
+export function validateProvider(input) {
+    const raw = (input ?? {});
+    const id = typeof raw.id === "string" ? raw.id.trim() : "";
+    if (!id)
+        throw new Error("供应商 id 不能为空");
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(id))
+        throw new Error("供应商 id 只能包含字母、数字、点、下划线和连字符，且必须以字母或数字开头");
+    const name = typeof raw.name === "string" ? raw.name.trim() : "";
+    const baseUrl = typeof raw.baseUrl === "string" ? raw.baseUrl.trim() : "";
+    if (!baseUrl)
+        throw new Error("API 地址不能为空");
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        throw new Error(`API 地址不是合法的 URL：${baseUrl}`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+        throw new Error("API 地址必须是 http:// 或 https://");
+    const api = typeof raw.api === "string" ? raw.api.trim() : "";
+    if (!api)
+        throw new Error("API 类型不能为空");
+    if (!KNOWN_APIS.includes(api))
+        throw new Error(`API 类型必须是下面之一：${KNOWN_APIS.join("、")}`);
+    const apiKey = typeof raw.apiKey === "string" ? raw.apiKey.trim() : "";
+    const models = Array.isArray(raw.models) ? raw.models : [];
+    if (!models.length)
+        throw new Error("至少要添加一个模型");
+    const checked = models.map((entry) => {
+        const model = (entry ?? {});
+        const modelId = typeof model.id === "string" ? model.id.trim() : "";
+        if (!modelId)
+            throw new Error("模型 id 不能为空");
+        if (modelId.length > 200)
+            throw new Error("模型 id 太长了");
+        const modelName = typeof model.name === "string" ? model.name.trim() : "";
+        const contextWindow = typeof model.contextWindow === "number" ? Math.round(model.contextWindow) : undefined;
+        if (contextWindow !== undefined && (!Number.isFinite(contextWindow) || contextWindow <= 0))
+            throw new Error("上下文窗口必须是一个正数");
+        const maxTokens = typeof model.maxTokens === "number" ? Math.round(model.maxTokens) : undefined;
+        if (maxTokens !== undefined && (!Number.isFinite(maxTokens) || maxTokens <= 0))
+            throw new Error("最大输出 token 必须是一个正数");
+        return {
+            id: modelId,
+            ...(modelName ? { name: modelName } : {}),
+            ...(model.reasoning === true ? { reasoning: true } : {}),
+            ...(model.imageInput === true ? { imageInput: true } : {}),
+            ...(contextWindow === undefined ? {} : { contextWindow }),
+            ...(maxTokens === undefined ? {} : { maxTokens }),
+            ...(model.supportsDeveloperRole === false ? { supportsDeveloperRole: false } : {}),
+            ...(model.supportsReasoningEffort === false ? { supportsReasoningEffort: false } : {}),
+        };
+    });
+    return {
+        id,
+        ...(name ? { name } : {}),
+        baseUrl,
+        api,
+        ...(apiKey ? { apiKey } : {}),
+        models: checked,
+    };
+}

package/dist/server/runtime.d.ts

@@ -115,6 +115,28 @@ export interface AnswerInput {
      * on a card but by its working directory on a call block would be worse than having neither.
      */
     onToolCall?(call: ToolCallNotice): void;
+    /**
+     * Called when a tool that WRITES A FILE is announced, with the path it is about to write.
+     *
+     * WHY A SEPARATE CALLBACK RATHER THAN A FIELD ON `onToolCall`. Two reasons, and the second is the
+     * load-bearing one.
+     *
+     * The first: this is a fact about the FILESYSTEM, not about the transcript. The transcript's row for
+     * an `edit` is a card; this is the server learning that a file on disk is about to change, and the
+     * listener for it has to act BEFORE the change - which is the only moment the old content is still on
+     * the disk. A card that arrives after the fact is too late to be a baseline.
+     *
+     * The second: the listener's job is to capture the file's previous content, which means reading the
+     * disk, and that must not happen on the path that draws a card. `onToolCall` is called synchronously
+     * in the drain loop, between yields, and a disk read there would put an I/O stall in the middle of
+     * the stream - the latency the streaming lane exists to avoid. So this callback is fired and FORGOTTEN:
+     * the listener does its work on its own time and the drain loop moves on.
+     *
+     * The path is the tool's own spelling, resolved against the workspace by the listener - the runtime
+     * does not know which workspace a call belongs to, and a path it cannot check is a path it does not
+     * vouch for.
+     */
+    onFileWrite?(path: string, toolName: string, toolCallId?: string): void;
     /**
      * Called on `tool_execution_end` for the same `id`, carrying how the call ended.
      *
@@ -328,6 +350,20 @@ export interface AgentRuntime {
      * selected model silently clamps away.
      */
     catalog(selection?: ModelSelection): Promise<ModelCatalog>;
+    /**
+     * Throws away every cached answer about the models Pi offers.
+     *
+     * Optional, because a runtime with no Pi behind it has no cache to throw away - and because the
+     * only thing that changes the model list from outside is a person adding a provider, which is a
+     * thing a runtime with no Pi cannot have.
+     */
+    invalidateCatalog?(): void;
+    /**
+     * Makes the live sessions stale, so the next turn builds one that knows the current models.
+     *
+     * Optional for the same reason: only a runtime with sessions behind it has any.
+     */
+    bumpModelEpoch?(): void;
     /**
      * Reverts the conversation to the state right after `boundaryEntryId`, in Pi's own transcript.
      *
@@ -580,6 +616,17 @@ export declare class PiRpcRuntime implements AgentRuntime {
      * otherwise be re-imported on every picker open.
      */
     private sdkCatalogPromise?;
+    /**
+     * Bumped whenever the set of models Pi knows about changes.
+     *
+     * A live session holds its own `ModelRuntime`, built when the session was built, and that runtime
+     * does not know about a provider added afterwards. Pi's refusal to switch to a model its runtime
+     * does not have is swallowed by the session pool into a warning, so the turn would go on running
+     * the OLD model while the picker said the new one - a control that lies. The sessions are made
+     * STALE by this counter instead: each one is rebuilt at its next turn, which is a moment when
+     * throwing a session away costs nothing, and the new one is built with a runtime that knows.
+     */
+    private modelEpoch;
     /** Latches the "no extension on disk" warning, so it is said once rather than once per turn. */
     private warnedMissingExtension;
     /** Latches the "Pi's SDK is not installed" warning, for the same reason. */
@@ -1031,6 +1078,26 @@ export declare class PiRpcRuntime implements AgentRuntime {
         followUp: string[];
     }>;
     steer(conversationId: string, message: string, images?: MessageImage[]): Promise<SteerDisposition>;
+    /**
+     * Throws away every cached answer about the models Pi offers.
+     *
+     * Called when the model list itself changes - which today means a person added a provider
+     * through the settings window. The caches are three deep and all three have to go: the TTL map
+     * (ten minutes), the in-flight map (a read that is already running would answer with the old
+     * list), and the SDK catalog, which is remembered for the life of the process because it holds
+     * objects that read the auth store and the model store from disk - and those files are exactly
+     * what just changed.
+     */
+    invalidateCatalog(): void;
+    /**
+     * Makes every live session stale, so the next turn builds one that knows the current models.
+     *
+     * WHY A COUNTER AND NOT A REBUILD. Rebuilding a session means throwing it away and reading its
+     * transcript back, and a turn may be RUNNING right now. The counter is read by the session pool
+     * as part of the fingerprint, so each session notices at its next acquire - between turns, where
+     * a rebuild is free.
+     */
+    bumpModelEpoch(): void;
     /**
      * The model/thinking catalog, from Pi, cached.
      *