@evandu/super-pi 0.1.123 → 0.1.125

package/dist/server/providers.js

@@ -168,35 +168,54 @@ async function writeJsonAtomic(path, value) {
     }
 }
 /**
- * The provider entry Super Pi writes into Pi's `models.json`.
+ * The provider entry Super Pi writes into Pi's `models.json`, MERGED into what was already there.
  *
- * 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.
+ * NO `apiKey` IS WRITTEN 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. A key the PERSON wrote there is
+ * left alone, because this function never touches fields it does not own.
+ *
+ * WHY IT MERGES RATHER THAN REPLACES. Pi's provider schema holds more than this form collects -
+ * `cost`, `headers`, `samplingParams`, `thinkingLevelMap`, `modelOverrides`, `oauth`, `authHeader`,
+ * an inline `apiKey` - and a settings panel that calls itself a view of Pi's configuration cannot
+ * delete the parts of it it has no field for. An earlier version replaced the whole entry, so
+ * editing ONE provider silently rewrote every OTHER entry in the file in this app's shape.
  */
-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 }),
-                },
-            }),
-    }));
+function toPiProvider(provider, existing) {
+    const base = existing && typeof existing === "object" ? { ...existing } : {};
+    const previousModels = Array.isArray(base.models) ? base.models : [];
+    const models = provider.models.map(model => {
+        const prior = previousModels.find((entry) => entry?.id === model.id);
+        const priorModel = prior && typeof prior === "object" ? prior : {};
+        const priorCompat = priorModel.compat && typeof priorModel.compat === "object"
+            ? priorModel.compat
+            : {};
+        const compat = {
+            ...priorCompat,
+            ...(model.supportsDeveloperRole === undefined ? {} : { supportsDeveloperRole: model.supportsDeveloperRole }),
+            ...(model.supportsReasoningEffort === undefined ? {} : { supportsReasoningEffort: model.supportsReasoningEffort }),
+        };
+        return {
+            ...priorModel,
+            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,
+            ...(Object.keys(compat).length ? { compat } : { compat: undefined }),
+        };
+    });
     return {
+        ...base,
         ...(provider.name ? { name: provider.name } : {}),
-        baseUrl: provider.baseUrl,
-        api: provider.api,
+        // AN EMPTY ADDRESS IS OMITTED, not written as "". Pi's schema refuses a baseUrl shorter than one
+        // character, so writing "" for an entry that had none - a built-in override, for instance -
+        // would make Pi reject the whole file at its next start.
+        ...(provider.baseUrl ? { baseUrl: provider.baseUrl } : {}),
+        ...(provider.api ? { api: provider.api } : {}),
         models,
     };
 }
@@ -223,25 +242,53 @@ export class ProviderRegistry {
     get registryPath() {
         return join(this.dataDir, "providers.json");
     }
+    /** The registry file as one object: the managed providers AND the ones turned off. */
+    async readRegistry() {
+        const raw = await readJsonFile(this.registryPath);
+        if (!raw || typeof raw !== "object")
+            return { providers: [], disabled: [] };
+        const record = raw;
+        const providerList = Array.isArray(record.providers)
+            ? record.providers.filter((p) => Boolean(p) && typeof p === "object")
+            : [];
+        const disabledList = Array.isArray(record.disabled)
+            ? record.disabled.filter((p) => Boolean(p) && typeof p === "object" && typeof p.id === "string")
+            : [];
+        return { providers: providerList, disabled: disabledList };
+    }
+    /** Writes one half of the registry file without losing the other. */
+    async writeRegistry(value) {
+        const current = await this.readRegistry();
+        await writeJsonAtomic(this.registryPath, {
+            providers: value.providers ?? current.providers,
+            disabled: value.disabled ?? current.disabled,
+        });
+    }
     /**
      * Reads all configured providers directly from Pi's models.json and auth.json.
      * Super Pi acts as the direct visual management plane for Pi's model configurations.
+     *
+     * PROVIDERS THAT ARE TURNED OFF ARE NOT IN HERE. They have been taken out of Pi's files - that is
+     * what "off" means - so this list is exactly what Pi would offer, which is what the write path
+     * (`set`, `remove`, `applyToPi`) has to reason about. `loadDisabled()` is the other half, for the
+     * panel that has to be able to switch them back on.
      */
     async load() {
         const modelsPath = piModelsPath(this.piDir);
         const authPath = piAuthPath(this.piDir);
         const piModels = (await readJsonFile(modelsPath))?.providers ?? {};
         const piAuth = (await readJsonFile(authPath)) ?? {};
-        // Backup registry from Super Pi data dir if needed
-        const rawBackup = await readJsonFile(this.registryPath);
-        const backupList = rawBackup && typeof rawBackup === "object" && Array.isArray(rawBackup.providers)
-            ? rawBackup.providers.filter((p) => Boolean(p) && typeof p === "object")
-            : [];
+        const registry = await this.readRegistry();
+        const backupList = registry.providers;
         const backupMap = new Map(backupList.map((p) => [p.id, p]));
+        // A provider that is OFF must not come back through the backup: the backup is where our keys
+        // live, and a key for a provider the person switched off would silently switch it back on at
+        // the next `load()` - before any UI could show the switch.
+        const offIds = new Set(registry.disabled.map((entry) => entry.id));
         const providers = [];
         const seen = new Set();
         for (const [pId, pData] of Object.entries(piModels)) {
-            if (!pData || typeof pData !== "object")
+            if (!pData || typeof pData !== "object" || offIds.has(pId))
                 continue;
             seen.add(pId);
             const rec = pData;
@@ -257,6 +304,10 @@ export class ProviderRegistry {
                 imageInput: Array.isArray(m?.input) ? m.input.includes("image") : false,
                 contextWindow: typeof m?.contextWindow === "number" ? m.contextWindow : undefined,
                 maxTokens: typeof m?.maxTokens === "number" ? m.maxTokens : undefined,
+                // THE TWO COMPATIBILITY SWITCHES ARE READ BACK, or the form would show its own defaults for
+                // a setting the file explicitly turned off, and saving the form would silently turn it on.
+                ...(typeof m?.compat?.supportsDeveloperRole === "boolean" ? { supportsDeveloperRole: m.compat.supportsDeveloperRole } : {}),
+                ...(typeof m?.compat?.supportsReasoningEffort === "boolean" ? { supportsReasoningEffort: m.compat.supportsReasoningEffort } : {}),
             }));
             const apiKey = backup?.apiKey;
             providers.push({
@@ -265,20 +316,178 @@ export class ProviderRegistry {
                 baseUrl,
                 api,
                 ...(apiKey ? { apiKey } : {}),
-                hasAuthKey: Boolean(piAuth[pId]?.key || backup?.apiKey),
+                // ANY credential counts, not only a `key`. An OAuth provider keeps `access`/`refresh` in
+                // this file, and reporting "no key" for a provider Pi is happily using is a lie the panel
+                // would then show next to a working model.
+                hasAuthKey: Boolean(piAuth[pId] || backup?.apiKey),
+                // A KEY WRITTEN IN models.json IS A CREDENTIAL TOO, and it is the one Pi's own docs lead
+                // with (`"apiKey": "$MY_KEY"`). Without this, such a provider is reported as having no
+                // credential - and the panel then says "Pi will not offer it", which is wrong exactly when
+                // the environment variable is set and Pi is offering it right now.
+                ...(typeof rec.apiKey === "string" && rec.apiKey ? { keyInModelsJson: true } : {}),
                 models,
             });
         }
         for (const b of backupList) {
-            if (!seen.has(b.id)) {
+            if (!seen.has(b.id) && !offIds.has(b.id)) {
                 providers.push(b);
             }
         }
         return providers;
     }
+    /**
+     * Pi's OWN providers: the ones that exist because they have a credential in `auth.json` and no
+     * entry in `models.json`.
+     *
+     * WHY THIS IS A SEPARATE READ. A built-in such as `kimi-coding` is defined inside Pi, not in a
+     * file - the only thing a person has configured for it is the credential. Those providers are
+     * invisible to `load()`, which reads `models.json`, and that is correct for the WRITE path:
+     * writing an empty `models.json` entry for a built-in would shadow Pi's own definition with a
+     * broken one. But they are exactly what a person wants to switch off ("I stopped paying for this
+     * plan"), so the panel has to see them. This returns the ids and the fact of a credential; the
+     * models come from Pi's catalogue, which this file layer cannot see.
+     */
+    async loadCredentialOnly() {
+        const modelsPath = piModelsPath(this.piDir);
+        const authPath = piAuthPath(this.piDir);
+        const piModels = (await readJsonFile(modelsPath))?.providers ?? {};
+        const piAuth = (await readJsonFile(authPath)) ?? {};
+        const registry = await this.readRegistry();
+        const offIds = new Set(registry.disabled.map((entry) => entry.id));
+        return Object.keys(piAuth)
+            .filter((id) => !piModels[id] && !offIds.has(id))
+            .map((id) => ({ id, name: id, baseUrl: "", api: "", hasAuthKey: true, builtin: true, models: [] }));
+    }
+    /** The providers that are switched off, as the panel needs to see them. */
+    async loadDisabled() {
+        return (await this.readRegistry()).disabled;
+    }
+    /**
+     * Takes a provider out of Pi's configuration and remembers exactly what was taken out.
+     *
+     * TWO FILES, and both are needed. `models.json` is where a custom provider's models are defined;
+     * `auth.json` is where its credential is. Pi offers a provider's models only when its auth is
+     * configured (`ModelRuntime.getAvailable()` filters on exactly that), so removing the credential
+     * is what makes a BUILT-IN stop being offered - it has no `models.json` entry to remove - while
+     * removing both is what makes a custom one disappear completely.
+     *
+     * NOTHING IS THROWN AWAY. Both pieces are written into Super Pi's own registry, which is how
+     * `enable` can put them back byte for byte. A person switching off a lapsed subscription provider
+     * is not asking to forget their endpoint and their models.
+     */
+    async disable(providerId, models = []) {
+        const modelsPath = piModelsPath(this.piDir);
+        const authPath = piAuthPath(this.piDir);
+        const piModels = (await readJsonFile(modelsPath));
+        const piAuth = (await readJsonFile(authPath)) ?? {};
+        const currentProviders = { ...(piModels?.providers ?? {}) };
+        const modelsEntry = currentProviders[providerId];
+        const credential = piAuth[providerId];
+        if (!modelsEntry && !credential) {
+            throw new Error(`Pi 的配置里没有供应商「${providerId}」，无法停用`);
+        }
+        // Write Pi's files FIRST, and only then remember the switch. A registry that says "off" while
+        // Pi still offers the provider is the one state this must never leave behind: the panel would
+        // report a provider as gone while it is still in the picker.
+        if (modelsEntry) {
+            delete currentProviders[providerId];
+            await writeJsonAtomic(modelsPath, { ...(piModels ?? {}), providers: currentProviders });
+        }
+        if (credential) {
+            const nextAuth = { ...piAuth };
+            delete nextAuth[providerId];
+            await writeJsonAtomic(authPath, nextAuth);
+        }
+        const registry = await this.readRegistry();
+        const record = {
+            id: providerId,
+            ...(typeof modelsEntry === "object" && modelsEntry && typeof modelsEntry.name === "string"
+                ? { name: modelsEntry.name }
+                : {}),
+            ...(modelsEntry ? { modelsEntry: modelsEntry } : {}),
+            ...(credential ? { credential: credential } : {}),
+            models,
+        };
+        try {
+            await this.writeRegistry({
+                providers: registry.providers.filter((provider) => provider.id !== providerId),
+                disabled: [...registry.disabled.filter((entry) => entry.id !== providerId), record],
+            });
+        }
+        catch (error) {
+            // The record is what makes the switch reversible, so a failure to write it means the provider
+            // has been taken out of Pi's files with nothing left to restore it from. Pi's files are put
+            // back before the error is reported - the same rule `set()` follows, for the same reason.
+            if (modelsEntry) {
+                await writeJsonAtomic(modelsPath, { ...(piModels ?? {}), providers: { ...currentProviders, [providerId]: modelsEntry } }).catch(() => undefined);
+            }
+            if (credential) {
+                await writeJsonAtomic(authPath, { ...piAuth, [providerId]: credential }).catch(() => undefined);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Puts a provider back exactly where `disable` took it from.
+     *
+     * AN EXISTING ENTRY IS NOT OVERWRITTEN. The person may have re-created the provider (or written a
+     * new `models.json` entry for the same id) while it was off; the newer entry is theirs and wins,
+     * and only the missing piece is restored. Refusing would be worse: the switch says "back on", and
+     * the credential is what makes it usable.
+     */
+    async enable(providerId) {
+        const registry = await this.readRegistry();
+        const record = registry.disabled.find((entry) => entry.id === providerId);
+        if (!record)
+            throw new Error(`供应商「${providerId}」没有被停用`);
+        if (record.modelsEntry) {
+            const modelsPath = piModelsPath(this.piDir);
+            const piModels = (await readJsonFile(modelsPath)) ?? {};
+            const providers = { ...(piModels.providers ?? {}) };
+            if (!providers[providerId]) {
+                providers[providerId] = record.modelsEntry;
+                await writeJsonAtomic(modelsPath, { ...piModels, providers });
+            }
+        }
+        if (record.credential) {
+            const authPath = piAuthPath(this.piDir);
+            const auth = (await readJsonFile(authPath)) ?? {};
+            if (!auth[providerId]) {
+                await writeJsonAtomic(authPath, { ...auth, [providerId]: record.credential });
+            }
+        }
+        await this.writeRegistry({
+            disabled: registry.disabled.filter((entry) => entry.id !== providerId),
+        });
+    }
+    /**
+     * Deletes a BUILT-IN provider's credential from Pi's `auth.json`.
+     *
+     * THE ONLY THING THERE IS TO DELETE. A built-in's models live in Pi itself; what a person has
+     * configured for it is the credential, and removing that is what makes Pi stop offering it. This
+     * is the PERMANENT version: unlike `disable`, nothing is remembered, so switching it back on means
+     * logging in to that provider again (which is what re-subscribing to the plan involves anyway).
+     */
+    async removeCredential(providerId) {
+        const authPath = piAuthPath(this.piDir);
+        const auth = (await readJsonFile(authPath));
+        if (!auth || !auth[providerId])
+            return;
+        const nextAuth = { ...auth };
+        delete nextAuth[providerId];
+        await writeJsonAtomic(authPath, nextAuth);
+    }
+    /** Forgets a disabled provider without restoring anything: the permanent form of "off". */
+    async forgetDisabled(providerId) {
+        const registry = await this.readRegistry();
+        const next = registry.disabled.filter((entry) => entry.id !== providerId);
+        if (next.length === registry.disabled.length)
+            throw new Error(`供应商「${providerId}」没有被停用`);
+        await this.writeRegistry({ disabled: next });
+    }
     /** Writes the registry. The key lives here, so the file is 0600. */
     async save(providers) {
-        await writeJsonAtomic(this.registryPath, { providers });
+        await this.writeRegistry({ providers });
     }
     /**
      * Directly updates Pi's models.json and auth.json to match the new set of providers.
@@ -292,7 +501,7 @@ export class ProviderRegistry {
         const existingProviders = existing.providers ?? {};
         const mergedProviders = { ...existingProviders };
         for (const provider of next)
-            mergedProviders[provider.id] = toPiProvider(provider);
+            mergedProviders[provider.id] = toPiProvider(provider, existingProviders[provider.id]);
         for (const id of previousIds)
             if (!nextIds.has(id))
                 delete mergedProviders[id];
@@ -331,6 +540,9 @@ export function publicProviders(providers) {
         baseUrl: provider.baseUrl,
         api: provider.api,
         hasKey: Boolean(provider.apiKey || provider.hasAuthKey),
+        ...(provider.keyInModelsJson ? { keyInModelsJson: true } : {}),
+        ...(provider.builtin ? { builtin: true } : {}),
+        ...(provider.disabled ? { disabled: true } : {}),
         models: provider.models.map(model => ({
             id: model.id,
             name: model.name ?? model.id,

package/dist/server/runtime.d.ts

@@ -77,7 +77,7 @@ export interface AnswerInput {
      * Only fires for a steer this turn delivered, never for the prompt that started the turn: the prompt
      * is not re-announced, and a caller's own state decides whether there was anything waiting at all.
      */
-    onSteerDelivered?(text: string): void;
+    onSteerDelivered?(text: string): void | Promise<void>;
     /**
      * Called ONCE per turn with the Pi entry id of the user message that started it, or never.
      *

package/dist/server/runtime.js

@@ -729,15 +729,17 @@ export class PiRpcRuntime {
             }
         }
         const queue = new TurnQueue();
+        const deferred = (handler) => (...args) => { if (handler)
+            queue.push({ kind: "callback", run: () => handler(...args) }); };
         const handlers = {
-            onToolCall: input.onToolCall,
+            onToolCall: deferred(input.onToolCall),
             onFileWrite: input.onFileWrite,
-            onToolUpdate: input.onToolUpdate,
-            onToolPreparing: input.onToolPreparing,
-            onToolEnd: input.onToolEnd,
-            onThinking: input.onThinking,
-            onThinkingEnd: input.onThinkingEnd,
-            onSteerDelivered: input.onSteerDelivered,
+            onToolUpdate: deferred(input.onToolUpdate),
+            onToolPreparing: deferred(input.onToolPreparing),
+            onToolEnd: deferred(input.onToolEnd),
+            onThinking: deferred(input.onThinking),
+            onThinkingEnd: deferred(input.onThinkingEnd),
+            onSteerDelivered: deferred(input.onSteerDelivered),
             onPiQueue: input.onPiQueue,
         };
         const announced = new Set();
@@ -853,6 +855,10 @@ export class PiRpcRuntime {
                     yield item.delta;
                     continue;
                 }
+                if (item.kind === "callback") {
+                    await item.run();
+                    continue;
+                }
                 if (item.kind === "error")
                     throw item.error;
                 break;
@@ -1329,7 +1335,7 @@ export class PiRpcRuntime {
                     const steeredText = describeDeliveredUserMessage(record);
                     if (steeredText !== undefined) {
                         try {
-                            onSteerDelivered?.(steeredText);
+                            await onSteerDelivered?.(steeredText);
                         }
                         catch (error) {
                             console.warn(`PiRpcRuntime: the steer delivery handler threw: ${error instanceof Error ? error.message : "unknown error"}`);
@@ -2186,9 +2192,10 @@ export class PiRpcRuntime {
      */
     async clearQueues(conversationId) {
         const empty = { steering: [], followUp: [] };
-        if (this.activeTurns.has(conversationId)) {
-            const session = this.sessionPool.get(conversationId);
-            if (!session?.clearQueue)
+        // A session and its queues outlive the active turn, including the abort hand-off window.
+        const session = this.sessionPool.get(conversationId);
+        if (session) {
+            if (!session.clearQueue)
                 return empty;
             try {
                 const cleared = session.clearQueue();
@@ -2417,14 +2424,22 @@ export class PiRpcRuntime {
             // 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.
+            // A MODEL THIS PI DOES NOT KNOW IS NOT A REASON TO THROW THE WHOLE READ AWAY. The MODEL LIST
+            // does not depend on the selection at all - it is the same list for every conversation - so
+            // abandoning it because one model's levels are unknown turns "the model this session used was
+            // removed" into "the picker is empty", which is the exact opposite of what the person needs
+            // at that moment. Measured before this change: removing the model in use produced a catalog
+            // with `source: "unavailable"` and ZERO models, and the spawned fallback that produced it had
+            // only reached its own `set_model` rejection ("Model not found").
+            //
+            // The levels then come from Pi's default model, because that is the model a turn on a
+            // nonexistent model actually runs on (the session cannot resolve it and falls back), so they
+            // describe the model in force rather than a different one.
             const forModel = selection ?? reader.defaultModel;
-            const levels = forModel ? await reader.thinkingLevelsFor(forModel) : undefined;
-            if (forModel && !levels)
-                return undefined;
+            let levels = forModel ? await reader.thinkingLevelsFor(forModel) : undefined;
+            if (forModel && !levels && reader.defaultModel) {
+                levels = await reader.thinkingLevelsFor(reader.defaultModel);
+            }
             const levelNames = levels ?? [];
             const value = {
                 source: "pi",
@@ -2476,8 +2491,15 @@ export class PiRpcRuntime {
             const channel = new RpcChannel(child);
             if (selection?.provider && selection.modelId) {
                 const applied = await channel.request({ id: "catalog_set_model", type: "set_model", provider: selection.provider, modelId: selection.modelId }, CATALOG_COMMAND_TIMEOUT_MS);
-                if (applied.success === false)
-                    throw new Error(applied.error ?? "Pi rejected set_model");
+                // A MODEL PI NO LONGER OFFERS IS NOT A REASON TO FAIL THE READ. `set_model` only scopes the
+                // level list to the model in force; the MODEL LIST itself is what the picker needs, and it
+                // does not depend on the selection. Throwing here made a removed model - the model a person
+                // is most likely to have just deleted - produce an empty picker with "Model not found" as
+                // the only explanation. Pi keeps its current model when `set_model` is rejected, so the
+                // levels below are the levels of the model that actually runs.
+                if (applied.success === false) {
+                    console.warn(`PiRpcRuntime: catalog for ${key} could not select ${selection.provider}/${selection.modelId} (${applied.error ?? "unknown error"}); listing the models without it`);
+                }
             }
             channel.write({ id: "catalog_models", type: "get_available_models" });
             channel.write({ id: "catalog_levels", type: "get_available_thinking_levels" });

package/dist/server/store.d.ts

@@ -90,6 +90,7 @@ export declare class Store {
      * fields and a spread would quietly start persisting whatever is added to `ModelSelection` next.
      */
     setDefaultModel(model?: ModelSelection): Promise<void>;
+    setTerminalShell(shell?: import("./types.js").TerminalShell): Promise<void>;
     snapshot(): AppState;
     /**
      * Whether a conversation already holds a message with this id.
@@ -278,6 +279,20 @@ export declare class Store {
      * no longer change until it settles.
      */
     setConversationModel(conversationId: string, model: ModelSelection): Promise<Conversation>;
+    /**
+     * Forgets the model a conversation runs on, so it follows Pi's own default again.
+     *
+     * FOR A MODEL THAT NO LONGER EXISTS. A conversation's model is copied at birth and never re-read
+     * from the workspace - but the copied model can be removed from Pi, and leaving the field pointing
+     * at it is worse than clearing it: Pi does not fail such a turn, it runs it on its own default, so
+     * the picker names one model while another one answers. `undefined` DELETES the key rather than
+     * storing "Pi's default" as this app's state, the same as `setConversationThinking` above.
+     *
+     * THE THINKING LEVEL GOES WITH IT. A level is a property of a model (`max` on a model with one
+     * level means something different from `max` on another), so a level left behind by a model that
+     * is gone describes nothing.
+     */
+    clearConversationModel(conversationId: string): Promise<Conversation>;
     /** Restoring Pi's own default deletes the key rather than storing Pi's default as this app's state. */
     setConversationThinking(conversationId: string, level: string | undefined): Promise<Conversation>;
     /**

package/dist/server/store.js

@@ -683,6 +683,20 @@ export class Store {
             throw error;
         }
     }
+    async setTerminalShell(shell) {
+        const previous = this.state.terminalShell;
+        if (shell === undefined)
+            delete this.state.terminalShell;
+        else
+            this.state.terminalShell = { file: shell.file, args: [...shell.args] };
+        try {
+            await this.persist();
+        }
+        catch (error) {
+            this.state.terminalShell = previous;
+            throw error;
+        }
+    }
     snapshot() { return structuredClone(this.state); }
     /**
      * Whether a conversation already holds a message with this id.
@@ -1104,6 +1118,26 @@ export class Store {
         await this.persistMetadata(conversationId);
         return structuredClone(conversation);
     }
+    /**
+     * Forgets the model a conversation runs on, so it follows Pi's own default again.
+     *
+     * FOR A MODEL THAT NO LONGER EXISTS. A conversation's model is copied at birth and never re-read
+     * from the workspace - but the copied model can be removed from Pi, and leaving the field pointing
+     * at it is worse than clearing it: Pi does not fail such a turn, it runs it on its own default, so
+     * the picker names one model while another one answers. `undefined` DELETES the key rather than
+     * storing "Pi's default" as this app's state, the same as `setConversationThinking` above.
+     *
+     * THE THINKING LEVEL GOES WITH IT. A level is a property of a model (`max` on a model with one
+     * level means something different from `max` on another), so a level left behind by a model that
+     * is gone describes nothing.
+     */
+    async clearConversationModel(conversationId) {
+        const conversation = this.requireConversation(conversationId);
+        delete conversation.model;
+        delete conversation.thinkingLevel;
+        await this.persistMetadata(conversationId);
+        return structuredClone(conversation);
+    }
     /** Restoring Pi's own default deletes the key rather than storing Pi's default as this app's state. */
     async setConversationThinking(conversationId, level) {
         const conversation = this.requireConversation(conversationId);

package/dist/server/terminal.d.ts

@@ -49,6 +49,46 @@
  * only way to get them. The cost is a native module, and it is paid only by operators who set
  */
 import type { ServerEvent, Workspace } from "./types.js";
+/**
+ * WHICH SHELL, and why it is not `COMSPEC`.
+ *
+ * `process.env.COMSPEC` on Windows IS `cmd.exe`, which is what this function used to spawn - while the
+ * comment beside it claimed PowerShell. The mismatch was visible in practice: `cmd.exe` is a DOS-era
+ * console with a legacy code page, so a Chinese filename printed by `dir` arrives as mojibake and the
+ * prompt echoes the active code page. Super Pi's whole interface is Chinese, so a terminal that cannot
+ * print Chinese is not a working terminal for the people who would use it.
+ *
+ * PowerShell is therefore the default, chosen over `pwsh` by name because `powershell.exe` ships with
+ * every supported Windows version while `pwsh` is a separate install. `SUPER_PI_TERMINAL_SHELL` overrides
+ * it for anyone who wants `cmd.exe`, `pwsh`, or Git Bash.
+ *
+ * On Unix the user's own `$SHELL` is right and a login shell is requested, because the terminal should
+ * see the same PATH and aliases as the terminal they use elsewhere.
+ *
+ * The ARGS differ by family and are not an arbitrary detail: `-l` is a bash/sh login flag, and passing it
+ * to PowerShell would make the shell refuse to start.
+ */
+export declare function parseShellCommand(command: string): {
+    file: string;
+    args: string[];
+} | undefined;
+export declare function defaultShell(env?: NodeJS.ProcessEnv, configured?: {
+    file: string;
+    args: string[];
+}): {
+    file: string;
+    args: string[];
+};
+export declare function shellSource(env?: NodeJS.ProcessEnv, configured?: {
+    file: string;
+    args: string[];
+}): "设置" | "环境变量" | "平台默认";
+export declare function validateShellCommand(command: string, env?: NodeJS.ProcessEnv): string | undefined;
+export declare function terminalShellCandidates(env?: NodeJS.ProcessEnv): {
+    file: string;
+    args: string[];
+    label: string;
+}[];
 /** One shell per browser tab, and a hard ceiling so reconnects cannot accumulate processes. */
 export declare const MAX_SESSIONS = 8;
 /**
@@ -107,12 +147,23 @@ export declare class TerminalService {
     private readonly workspaceFor;
     /** Whether a command from this peer is allowed to touch a shell at all. */
     private readonly isTrustedPeer;
+    private readonly configuredShell;
+    private readonly saveConfiguredShell;
     constructor(options: {
         workspaceFor: (workspaceId: string) => Workspace | undefined;
         isTrustedPeer: (remoteAddress: string | undefined) => boolean;
+        configuredShell?: () => {
+            file: string;
+            args: string[];
+        } | undefined;
+        saveConfiguredShell?: (shell: {
+            file: string;
+            args: string[];
+        } | undefined) => Promise<void>;
         enabled?: boolean;
     });
     readonly enabled: boolean;
+    setShell(command: string | null, remoteAddress: string | undefined): Promise<boolean>;
     /**
      * WHY THE PEER CHECK LIVES ON EVERY COMMAND AND NOT ONLY ON `open`.
      *