@evandu/super-pi 0.1.103 → 0.1.105

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

@@ -328,6 +328,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.
      *
@@ -431,14 +445,27 @@ export declare function describeSteerDisposition(data: unknown): SteerDispositio
 /**
  * Keys Pi's model answers by. Exported so the store and the tests agree with the runtime.
  *
- * THE MODEL IS NOT PART OF THE KEY, and that is the second half of why the picker no longer starts a
- * process. The MODEL LIST is the same answer whichever model a conversation has selected - it is the
- * list of models Pi offers, not the ones one conversation may use. The only thing that varies with the
- * selection is the THINKING LEVELS, which belong to the model in use.
+ * THE MODEL LIST IS SHARED. The list of models Pi offers is the same answer whichever model a
+ * conversation has selected - it is not the list of models one conversation may use. So the list has
+ * ONE key, and every conversation shares it.
  *
- * So the key records just whether levels were asked for. Keying on the model (as this used to) meant a
- * cache miss for every model a person ever picked, and every miss was a process start - so the picker
- * went grey again after every model change, which is exactly when a person is moving between models.
+ * THE THINKING LEVELS BELONG TO THE MODEL IN USE, so they get a key PER MODEL. This used to be one
+ * "levels" key for every model, on the assumption that the level list is the same whichever model is
+ * selected - and that assumption is wrong: Pi computes the levels from the model itself
+ * (`getSupportedThinkingLevels`: a model that cannot reason offers only "off", and a model whose
+ * thinking map says so offers fewer). Measured with one key: after reading the levels for a reasoning
+ * model, a NON-reasoning model was offered the reasoning model's levels, and the other way round - so
+ * the picker offered levels the model in force does not have, and hid the ones it does. Super Pi
+ * cannot compute the levels itself instead: Pi's rule is not exported, and a second implementation of
+ * it would drift from Pi's.
+ *
+ * THE COST OF A KEY PER MODEL, and why it is not what it used to be. An earlier version of this
+ * comment said that keying on the model "meant a cache miss for every model a person ever picked, and
+ * every miss was a process start - so the picker went grey again after every model change". That was
+ * true when the catalog ALWAYS answered by spawning a Pi, which is no longer how the ordinary path
+ * works: the SDK path reads the levels out of a session (measured ~30ms, no process at all) and caches
+ * them per model. The one-shot path - a Pi the person named explicitly - does pay a spawn for a model
+ * it has not read yet, and that is the price of asking Pi rather than guessing at its rule.
  */
 export declare const catalogKey: (selection?: ModelSelection) => string;
 /**
@@ -567,6 +594,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. */
@@ -1018,6 +1056,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.
      *

package/dist/server/runtime.js

@@ -196,16 +196,29 @@ const CATALOG_COMMAND_TIMEOUT_MS = 15_000;
 /**
  * Keys Pi's model answers by. Exported so the store and the tests agree with the runtime.
  *
- * THE MODEL IS NOT PART OF THE KEY, and that is the second half of why the picker no longer starts a
- * process. The MODEL LIST is the same answer whichever model a conversation has selected - it is the
- * list of models Pi offers, not the ones one conversation may use. The only thing that varies with the
- * selection is the THINKING LEVELS, which belong to the model in use.
+ * THE MODEL LIST IS SHARED. The list of models Pi offers is the same answer whichever model a
+ * conversation has selected - it is not the list of models one conversation may use. So the list has
+ * ONE key, and every conversation shares it.
  *
- * So the key records just whether levels were asked for. Keying on the model (as this used to) meant a
- * cache miss for every model a person ever picked, and every miss was a process start - so the picker
- * went grey again after every model change, which is exactly when a person is moving between models.
+ * THE THINKING LEVELS BELONG TO THE MODEL IN USE, so they get a key PER MODEL. This used to be one
+ * "levels" key for every model, on the assumption that the level list is the same whichever model is
+ * selected - and that assumption is wrong: Pi computes the levels from the model itself
+ * (`getSupportedThinkingLevels`: a model that cannot reason offers only "off", and a model whose
+ * thinking map says so offers fewer). Measured with one key: after reading the levels for a reasoning
+ * model, a NON-reasoning model was offered the reasoning model's levels, and the other way round - so
+ * the picker offered levels the model in force does not have, and hid the ones it does. Super Pi
+ * cannot compute the levels itself instead: Pi's rule is not exported, and a second implementation of
+ * it would drift from Pi's.
+ *
+ * THE COST OF A KEY PER MODEL, and why it is not what it used to be. An earlier version of this
+ * comment said that keying on the model "meant a cache miss for every model a person ever picked, and
+ * every miss was a process start - so the picker went grey again after every model change". That was
+ * true when the catalog ALWAYS answered by spawning a Pi, which is no longer how the ordinary path
+ * works: the SDK path reads the levels out of a session (measured ~30ms, no process at all) and caches
+ * them per model. The one-shot path - a Pi the person named explicitly - does pay a spawn for a model
+ * it has not read yet, and that is the price of asking Pi rather than guessing at its rule.
  */
-export const catalogKey = (selection) => (selection?.provider && selection.modelId ? "levels" : "list");
+export const catalogKey = (selection) => (selection?.provider && selection.modelId ? `levels:${selection.provider}/${selection.modelId}` : "list");
 /**
  * Where the `task` extension lives, as an ABSOLUTE path.
  *
@@ -329,6 +342,17 @@ export class PiRpcRuntime {
      * otherwise be re-imported on every picker open.
      */
     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.
+     */
+    modelEpoch = 0;
     /** Latches the "no extension on disk" warning, so it is said once rather than once per turn. */
     warnedMissingExtension = false;
     /** Latches the "Pi's SDK is not installed" warning, for the same reason. */
@@ -416,7 +440,7 @@ export class PiRpcRuntime {
             // ABOUT that session and stop being true with it.
             this.sessionHosts.delete(conversationId);
             this.reportedSessionFiles.delete(conversationId);
-        }, options.sessionFactory ?? createPiSession, (conversationId) => mintCapability(conversationId));
+        }, options.sessionFactory ?? createPiSession, (conversationId) => mintCapability(conversationId), () => this.modelEpoch);
     }
     /**
      * The configuration of the session that was built for a conversation, for tests to inspect.
@@ -721,9 +745,14 @@ export class PiRpcRuntime {
             announced.add(key);
             console.warn(`PiRpcRuntime: unhandled Pi session event ${key} - consumed without action.`);
         };
+        // THE FAILURE THE TURN ENDED ON, if it ended on one. Held here rather than thrown on the spot,
+        // because Pi retries on its own and only the LAST assistant message of a turn decides whether the
+        // turn failed. The bridge clears it when a new assistant message starts, and raises it when Pi
+        // settles.
+        const failure = { current: undefined };
         const unsubscribe = session.subscribe((event) => {
             try {
-                handleSessionEvent(event, queue, handlers, report);
+                handleSessionEvent(event, queue, handlers, report, failure);
             }
             catch (error) {
                 console.warn(`PiRpcRuntime: the session event handler threw: ${error instanceof Error ? error.message : "unknown error"}`);
@@ -2224,6 +2253,32 @@ export class PiRpcRuntime {
         }
         return answer;
     }
+    /**
+     * 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() {
+        this.catalogs.clear();
+        this.pendingCatalogs.clear();
+        this.sdkCatalogPromise = undefined;
+    }
+    /**
+     * 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() {
+        this.modelEpoch += 1;
+    }
     /**
      * The model/thinking catalog, from Pi, cached.
      *
@@ -2346,14 +2401,22 @@ export class PiRpcRuntime {
             const pick = (model) => (model ? { provider: model.provider, modelId: model.modelId, label: model.label } : undefined);
             // The levels belong to the SELECTED model, so they are asked of the model in question rather
             // than of whatever Pi would have defaulted to.
+            //
+            // AND WHEN THE SDK DOES NOT KNOW THAT MODEL, THE WHOLE READ IS HANDED OVER rather than answered
+            // with another model's levels. The model in force may belong to a Pi the SDK is not (a Pi the
+            // person named explicitly), and a list of levels for a DIFFERENT model is worse than no answer:
+            // the picker would offer levels the model in force does not have.
             const forModel = selection ?? reader.defaultModel;
-            const levels = forModel ? await reader.thinkingLevelsFor(forModel) : [];
+            const levels = forModel ? await reader.thinkingLevelsFor(forModel) : undefined;
+            if (forModel && !levels)
+                return undefined;
+            const levelNames = levels ?? [];
             const value = {
                 source: "pi",
                 models,
-                levels,
+                levels: levelNames,
                 defaultModel: pick(reader.defaultModel ? describeModel({ provider: reader.defaultModel.provider, id: reader.defaultModel.modelId, name: reader.defaultModel.modelId }) : undefined),
-                defaultThinkingLevel: reader.defaultThinkingLevel ?? levels[0],
+                defaultThinkingLevel: reader.defaultThinkingLevel ?? levelNames[0],
                 fetchedAt: new Date().toISOString(),
             };
             return value;

package/dist/server/server-context.d.ts

@@ -7,6 +7,7 @@ import type { ConversationService } from "./application/conversation-service.js"
 import type { RunService } from "./application/run-service.js";
 import type { ExtensionUiService } from "./application/extension-ui-service.js";
 import type { CatalogService } from "./application/catalog-service.js";
+import type { ProviderService } from "./application/provider-service.js";
 import type { ExecService } from "./exec-service.js";
 import type { ToolRegistry } from "./tool-registry.js";
 import type { ToolRunner } from "./tool-runner.js";
@@ -49,6 +50,8 @@ export interface ServerContext {
     runService: RunService;
     extensionUiService: ExtensionUiService;
     catalogService: CatalogService;
+    /** The providers a person added through the settings window. */
+    providerService: ProviderService;
     execService: ExecService;
     toolRegistry: ToolRegistry;
     toolRunner: ToolRunner;