@evandu/super-pi 0.1.104 → 0.1.106

package/dist/server/file-index.js

@@ -0,0 +1,150 @@
+import { readdir, stat } from "node:fs/promises";
+import { SEARCH_SKIP_DIRS, createRootGuard, fileMeta, isTextName, toRelative } from "./files.js";
+const MAX_DIRECTORIES = 4000;
+const MAX_FILES = 30000;
+const MAX_MS = 4000;
+/**
+ * Per-workspace index. The background pass uses readdir only because measurements on this repository
+ * show directory enumeration under a second while stat for every entry costs 2-3 seconds. Most entries
+ * deliberately have no etag: an etag belongs to a file a user has opened or a known write has touched,
+ * where the existing read/write metadata already paid for it. The client polls only those open files.
+ */
+export class FileIndex {
+    workspaceId;
+    broadcast;
+    entries = new Map();
+    history = [];
+    root = "";
+    queue = [];
+    building = false;
+    skipped = [];
+    version = 0;
+    builtAt = 0;
+    complete = false;
+    constructor(workspaceId, broadcast) {
+        this.workspaceId = workspaceId;
+        this.broadcast = broadcast;
+    }
+    start(root) {
+        if (this.building || this.builtAt)
+            return;
+        this.root = root;
+        this.building = true;
+        this.queue = [""];
+        void this.scan();
+    }
+    stop() { }
+    snapshot(since) {
+        const valid = Number.isFinite(since) && since !== undefined;
+        const deltas = valid ? this.history.filter((item) => item.version > since) : [];
+        return { version: this.version, builtAt: this.builtAt, complete: this.complete, skipped: this.skipped,
+            changed: valid ? deltas.flatMap((item) => item.changed) : [...this.entries.values()],
+            removed: valid ? deltas.flatMap((item) => item.removed) : [] };
+    }
+    async refresh(path) {
+        if (!this.root)
+            return;
+        const guard = createRootGuard(this.root);
+        try {
+            const absolute = await guard(path);
+            const info = await stat(absolute);
+            const rel = toRelative(this.root, absolute);
+            if (info.isDirectory())
+                this.publish([{ path: rel, kind: "directory", size: null, mtimeMs: null, etag: null, text: null }], []);
+            else {
+                const meta = await fileMeta(absolute);
+                this.recordFile(rel, meta, info.mtimeMs);
+            }
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "ENOENT" || code === "ENOTDIR")
+                this.remove(path);
+            else
+                throw error;
+        }
+    }
+    /** Record metadata already obtained by opening, saving, or polling an open file. No second stat: the
+     * caller's file API operation has already passed the sole containment guard and read this metadata. */
+    recordFile(path, meta, mtimeMs = Date.parse(meta.modifiedAt)) {
+        const previous = this.entries.get(path);
+        if (previous?.kind === "file" && previous.etag === meta.etag)
+            return;
+        this.publish([{ path, kind: "file", size: meta.size, mtimeMs, etag: meta.etag, text: isTextName(path) }], []);
+    }
+    remove(path) { if (this.entries.delete(path))
+        this.publish([], [path]); }
+    async scan() {
+        const started = Date.now();
+        let dirs = 0;
+        let files = 0;
+        let incomplete = false;
+        const changed = [];
+        const guard = createRootGuard(this.root);
+        scan: while (this.queue.length) {
+            if (dirs >= MAX_DIRECTORIES || files >= MAX_FILES || Date.now() - started >= MAX_MS) {
+                incomplete = true;
+                break;
+            }
+            const directory = this.queue.shift();
+            let listed;
+            try {
+                listed = await readdir(await guard(directory), { withFileTypes: true });
+            }
+            catch {
+                this.skipped.push(directory || "/");
+                incomplete = true;
+                continue;
+            }
+            dirs += 1;
+            for (const entry of listed) {
+                const path = directory ? directory + "/" + entry.name : entry.name;
+                if (entry.isSymbolicLink()) {
+                    this.skipped.push(path);
+                    continue;
+                }
+                if (entry.isDirectory()) {
+                    if (SEARCH_SKIP_DIRS.has(entry.name)) {
+                        this.skipped.push(path);
+                        continue;
+                    }
+                    this.queue.push(path);
+                    changed.push({ path, kind: "directory", size: null, mtimeMs: null, etag: null, text: null });
+                }
+                else if (entry.isFile()) {
+                    if (files >= MAX_FILES || Date.now() - started >= MAX_MS) {
+                        incomplete = true;
+                        break scan;
+                    }
+                    files += 1;
+                    changed.push({ path, kind: "file", size: null, mtimeMs: null, etag: null, text: isTextName(path) });
+                }
+            }
+            await new Promise((resolve) => setTimeout(resolve, 0));
+        }
+        this.building = false;
+        this.complete = !incomplete;
+        this.builtAt = Date.now();
+        // Quick Open does not need per-directory progress. One final batch bounds WS traffic and keeps the
+        // existing on-demand tree interactive throughout the scan (including dependency directories).
+        this.publish(changed, [], true);
+    }
+    publish(changed, removed, force = false) {
+        changed = changed.map((entry) => {
+            // A targeted stat may race the cheap directory walk. Do not let the later readdir-only result erase
+            // metadata that was already paid for and verified.
+            const previous = this.entries.get(entry.path);
+            const merged = previous?.kind === entry.kind && entry.size === null ? { ...entry, size: previous.size, mtimeMs: previous.mtimeMs, etag: previous.etag } : entry;
+            this.entries.set(entry.path, merged);
+            return merged;
+        });
+        if (!changed.length && !removed.length && !force)
+            return;
+        this.version += 1;
+        const event = { type: "files.index", workspaceId: this.workspaceId, version: this.version, changed, removed, complete: this.complete, skipped: this.skipped };
+        this.history.push({ version: this.version, changed, removed });
+        if (this.history.length > 128)
+            this.history.shift();
+        this.broadcast(event);
+    }
+}

package/dist/server/files.d.ts

@@ -15,6 +15,14 @@ export declare const MAX_SEARCH_RESULTS = 500;
 /** How deep the recursive search walks. Twelve levels is past any real source tree; the cap is what
  *  turns a pathologically deep dependency tree from a hang into a result. */
 export declare const MAX_SEARCH_DEPTH = 12;
+/** Directories the recursive search skips. The TREE does not skip them - a directory the user cannot
+ *  browse is a directory they cannot inspect a file in, and the binary handling below is only reachable
+ *  if `node_modules` is reachable. A recursive filename search, by contrast, returns thousands of matches
+ *  from these and nothing a person searched for, so they are excluded from the scan and the exclusion is
+ *  reported in the response rather than being invisible. */
+/** Shared exclusion list for recursive search and the quick-open index. The directory tree intentionally
+ * does not use it: users may still browse dependencies on demand. */
+export declare const SEARCH_SKIP_DIRS: Set<string>;
 /**
  * Extensions this panel OPENS without needing a sniff. It is a hint used only to label a file in the tree
  * before it is read, and never as a permission: a `.png` is refused by name even if a sniffing pass would

package/dist/server/files.js

@@ -52,7 +52,9 @@ export const MAX_SEARCH_DEPTH = 12;
  *  if `node_modules` is reachable. A recursive filename search, by contrast, returns thousands of matches
  *  from these and nothing a person searched for, so they are excluded from the scan and the exclusion is
  *  reported in the response rather than being invisible. */
-const SEARCH_SKIP_DIRS = new Set([".git", "node_modules", "dist", "build", ".super-pi", ".next", ".cache", "coverage", ".venv"]);
+/** Shared exclusion list for recursive search and the quick-open index. The directory tree intentionally
+ * does not use it: users may still browse dependencies on demand. */
+export const SEARCH_SKIP_DIRS = new Set([".git", "node_modules", "dist", "build", ".super-pi", ".next", ".cache", "coverage", ".venv"]);
 /**
  * Extensions that are binary by definition, checked BEFORE any bytes are read.
  *

package/dist/server/git.d.ts

@@ -35,3 +35,20 @@ export declare function gitDiff(root: string, path: string, staged: boolean): Pr
     diff: string;
     kind: "text";
 }>;
+/**
+ * The content of a file AS IT WAS COMMITTED, or `null` when there is no such version.
+ *
+ * WHY THIS EXISTS ALONGSIDE `gitDiff`. `gitDiff` answers "what changed relative to HEAD" as a PATCH -
+ * which is a good thing to read and a bad thing to diff against: a patch is a set of hunks, and
+ * reconstructing the "before" text from it is a lossy operation that a review view should not depend on.
+ * The review view needs the two TEXTS, so that the difference between them is computed by one
+ * well-tested algorithm rather than by two different ones.
+ *
+ * `null` covers three different situations, and the caller must not confuse them: the repository has no
+ * commits yet (`unborn`), the file was never committed (it is new or untracked), or the file is not in
+ * this repository at all. The first two are the same answer for a review - "there is no committed
+ * version to compare against" - and the third is a refusal, which the caller reports.
+ */
+export declare function gitHeadContent(root: string, path: string): Promise<string | null>;
+/** Whether the directory is a git repository at all. The review view asks before it offers a git baseline. */
+export declare function isGitRepository(root: string): Promise<boolean>;

package/dist/server/git.js

@@ -28,3 +28,42 @@ export async function gitLog(root, limit) { const hasHead = await git(root, ["re
 export async function gitDiff(root, path, staged) { const safe = resolve(root, path); if (!safe.startsWith(resolve(root) + sep) || !existsSync(safe))
     throw Object.assign(new Error("文件路径无效"), { code: "path" }); const check = await git(root, ["ls-files", "--error-unmatch", "--", path]).then(() => true).catch(() => false); if (!check)
     return { path, staged, diff: null, kind: "untracked" }; const out = await git(root, ["diff", ...(staged ? ["--cached"] : []), "--", path]); return { path, staged, diff: out.stdout, kind: "text" }; }
+/**
+ * The content of a file AS IT WAS COMMITTED, or `null` when there is no such version.
+ *
+ * WHY THIS EXISTS ALONGSIDE `gitDiff`. `gitDiff` answers "what changed relative to HEAD" as a PATCH -
+ * which is a good thing to read and a bad thing to diff against: a patch is a set of hunks, and
+ * reconstructing the "before" text from it is a lossy operation that a review view should not depend on.
+ * The review view needs the two TEXTS, so that the difference between them is computed by one
+ * well-tested algorithm rather than by two different ones.
+ *
+ * `null` covers three different situations, and the caller must not confuse them: the repository has no
+ * commits yet (`unborn`), the file was never committed (it is new or untracked), or the file is not in
+ * this repository at all. The first two are the same answer for a review - "there is no committed
+ * version to compare against" - and the third is a refusal, which the caller reports.
+ */
+export async function gitHeadContent(root, path) {
+    const safe = resolve(root, path);
+    if (!safe.startsWith(resolve(root) + sep))
+        throw Object.assign(new Error("文件路径无效"), { code: "path" });
+    const hasHead = await git(root, ["rev-parse", "--verify", "HEAD"]).then(() => true).catch(() => false);
+    if (!hasHead)
+        return null;
+    const tracked = await git(root, ["ls-files", "--error-unmatch", "--", path]).then(() => true).catch(() => false);
+    if (!tracked)
+        return null;
+    try {
+        const out = await git(root, ["show", `HEAD:${path}`]);
+        return out.stdout;
+    }
+    catch {
+        // The file is tracked but `HEAD:path` does not resolve - a path with characters git quotes, or a
+        // repository in a state this server does not model. Treated as "no committed version", which is the
+        // honest answer rather than a crash.
+        return null;
+    }
+}
+/** Whether the directory is a git repository at all. The review view asks before it offers a git baseline. */
+export async function isGitRepository(root) {
+    return git(root, ["rev-parse", "--git-dir"]).then(() => true).catch(() => false);
+}

package/dist/server/http-server.js

@@ -8,9 +8,12 @@ import { describe as describeFilesError, fileMeta, listDirectory, MAX_FILE_BYTES
 import { findUploadFile, MAX_UPLOAD_BODY_BYTES, saveUpload } from "./upload.js";
 import { checkDiskVersion } from "./version.js";
 import { gitDiff, gitLog, gitStatus } from "./git.js";
+import { computeFileDiff } from "./file-diff.js";
 import { MAX_KNOWLEDGE_REQUEST_BYTES } from "./knowledge.js";
 import { MAX_TOOL_BODY_BYTES } from "./tool-registry.js";
 import { packageUpdateArgs } from "./update.js";
+import { FileIndex } from "./file-index.js";
+import { MAX_CONTENT_DEPTH, MAX_CONTENT_FILE_BYTES, MAX_CONTENT_RESULTS, searchByContent } from "./content-search.js";
 const MIME_TYPES = {
     ".css": "text/css; charset=utf-8",
     ".html": "text/html; charset=utf-8",
@@ -952,6 +955,118 @@ export function createHttpServer(options) {
             }
             return;
         }
+        if (url.pathname === "/api/files/diff") {
+            const json = (status, body) => {
+                response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
+            };
+            try {
+                const workspaceId = url.searchParams.get("workspaceId")?.trim();
+                const workspace = store.snapshot().workspaces.find((item) => item.id === workspaceId);
+                if (!workspaceId || !workspace) {
+                    json(404, { error: `Workspace ${workspaceId ?? "(missing)"} not found`, code: "no_workspace" });
+                    return;
+                }
+                const path = url.searchParams.get("path")?.trim() ?? "";
+                if (!path) {
+                    json(400, { error: "需要 path 参数", code: "bad_request" });
+                    return;
+                }
+                const requested = url.searchParams.get("base")?.trim();
+                const preferred = requested === "git" || requested === "agent" ? requested : "auto";
+                // The baseline is chosen by the server, but the client can name one - and when it names one, that
+                // is the one it gets. A silent fall-back would show the user a comparison they did not ask for.
+                const diff = await computeFileDiff({
+                    root: workspace.path,
+                    path,
+                    preferred,
+                    tracker: context.fileChanges,
+                    workspaceId,
+                });
+                json(200, diff);
+            }
+            catch (error) {
+                const described = describeFilesError(error);
+                json(described.status, described.body);
+            }
+            return;
+        }
+        if (url.pathname === "/api/files/search") {
+            const json = (status, body) => { response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body)); };
+            try {
+                if (request.method !== "GET") {
+                    json(405, { error: "Content search requires GET", code: "method" });
+                    return;
+                }
+                const workspaceId = url.searchParams.get("workspaceId")?.trim();
+                const query = url.searchParams.get("q")?.trim() ?? "";
+                const workspace = store.snapshot().workspaces.find((item) => item.id === workspaceId);
+                if (!workspaceId || !workspace) {
+                    json(404, { error: "workspace not found", code: "no_workspace" });
+                    return;
+                }
+                await resolveInsideRoot(workspace.path, "");
+                if (query.length > 256 || /[\r\n]/.test(query)) {
+                    json(400, { error: "Search query must be one line, at most 256 characters", code: "bad_query" });
+                    return;
+                }
+                if (!query) {
+                    json(200, { mode: "content", query, hits: [], truncated: false, skipped: [], complete: true, reasons: [], maxResults: MAX_CONTENT_RESULTS, maxFileBytes: MAX_CONTENT_FILE_BYTES, maxDepth: MAX_CONTENT_DEPTH });
+                    return;
+                }
+                const indexes = context.fileIndexes ?? new Map();
+                if (!context.fileIndexes)
+                    context.fileIndexes = indexes;
+                let index = indexes.get(workspaceId);
+                if (!index) {
+                    index = new FileIndex(workspaceId, (event) => broadcaster.broadcast(event));
+                    indexes.set(workspaceId, index);
+                }
+                index.start(workspace.path);
+                const deadline = Date.now() + 4500;
+                while (!index.builtAt && Date.now() < deadline)
+                    await new Promise((resolve) => setTimeout(resolve, 25));
+                const snapshot = index.snapshot();
+                const result = await searchByContent(workspace.path, [...index.entries.values()], query, snapshot);
+                json(200, { mode: "content", query, ...result, maxResults: MAX_CONTENT_RESULTS, maxFileBytes: MAX_CONTENT_FILE_BYTES, maxDepth: MAX_CONTENT_DEPTH });
+            }
+            catch (error) {
+                const described = describeFilesError(error);
+                json(described.status, described.body);
+            }
+            return;
+        }
+        if (url.pathname === "/api/files/index") {
+            const json = (status, body) => { response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body)); };
+            try {
+                if (request.method !== "GET") {
+                    json(405, { error: "File index requires GET", code: "method" });
+                    return;
+                }
+                const workspaceId = url.searchParams.get("workspaceId")?.trim();
+                const workspace = store.snapshot().workspaces.find((item) => item.id === workspaceId);
+                if (!workspaceId || !workspace) {
+                    json(404, { error: `Workspace ${workspaceId ?? "(missing)"} not found`, code: "no_workspace" });
+                    return;
+                }
+                const indexes = context.fileIndexes ?? new Map();
+                if (!context.fileIndexes)
+                    context.fileIndexes = indexes;
+                let index = indexes.get(workspaceId);
+                if (!index) {
+                    index = new FileIndex(workspaceId, (event) => broadcaster.broadcast(event));
+                    indexes.set(workspaceId, index);
+                }
+                index.start(workspace.path);
+                const sinceRaw = url.searchParams.get("since");
+                const since = sinceRaw === null ? undefined : Number(sinceRaw);
+                json(200, index.snapshot(Number.isSafeInteger(since) && since >= 0 ? since : undefined));
+            }
+            catch (error) {
+                const described = describeFilesError(error);
+                json(described.status, described.body);
+            }
+            return;
+        }
         if (url.pathname === "/api/files" || url.pathname === "/api/file") {
             const json = (status, body) => {
                 response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
@@ -983,10 +1098,14 @@ export function createHttpServer(options) {
                     const rel = url.searchParams.get("path") ?? "";
                     if (url.searchParams.get("meta") === "1") {
                         const resolved = await resolveInsideRoot(root, rel);
-                        json(200, { path: toRelative(root, resolved), ...(await fileMeta(resolved)) });
+                        const meta = await fileMeta(resolved);
+                        const path = toRelative(root, resolved);
+                        context.fileIndexes?.get(workspaceId)?.recordFile(path, meta);
+                        json(200, { path, ...meta });
                         return;
                     }
                     const file = await readWorkspaceFile(root, rel);
+                    context.fileIndexes?.get(workspaceId)?.recordFile(file.path, file.meta);
                     json(200, { path: file.path, content: file.content, eol: file.eol, bom: file.bom, meta: file.meta, maxBytes: MAX_FILE_BYTES });
                     return;
                 }
@@ -1018,6 +1137,7 @@ export function createHttpServer(options) {
                         return;
                     }
                     const outcome = await writeWorkspaceFile(root, parsed.path, parsed.content, parsed.baseEtag);
+                    context.fileIndexes?.get(workspaceId)?.recordFile(outcome.path, outcome.meta);
                     json(200, outcome);
                     return;
                 }

package/dist/server/index.js

@@ -16,7 +16,10 @@ import { SubagentRunRecorder } from "./subagent-runs.js";
 import { WorkflowEngine } from "./workflow-engine.js";
 import { ExtensionUiService } from "./application/extension-ui-service.js";
 import { CatalogService } from "./application/catalog-service.js";
+import { ProviderService } from "./application/provider-service.js";
+import { ProviderRegistry } from "./providers.js";
 import { RunService } from "./application/run-service.js";
+import { FileChangeTracker } from "./file-changes.js";
 import { ConversationService } from "./application/conversation-service.js";
 import { WorkspaceService } from "./application/workspace-service.js";
 import { CommandHandler } from "./command-handler.js";
@@ -178,8 +181,29 @@ const onDirsChanged = (dirs) => {
     workspaceService.setAgentsDir(dirs);
 };
 const catalogService = new CatalogService(runtime, broadcaster, initialAgentDirs, store, rootDir, onDirsChanged);
+/**
+ * The providers a person added through the settings window.
+ *
+ * The registry lives in Super Pi's own data directory and holds the API keys; Pi's `models.json` and
+ * `auth.json` are written from it, so a provider added here is a provider Pi can use - in a session,
+ * in a spawned Pi, and in the terminal.
+ */
+const providerRegistry = new ProviderRegistry(dataDir);
+const providerService = new ProviderService(providerRegistry, runtime, broadcaster, catalogService, store);
 const runService = new RunService(store, runtime, subagents, broadcaster, extensionUiService, initialAgentDirs, workflows);
 runService.setMemory(memory);
+/**
+ * WHAT THE AGENT CHANGED, and what each file looked like before.
+ *
+ * The tracker is created here rather than inside the service because it outlives one run: the changes a
+ * session produced are the session's record, and a tracker that died with the run would take the answer
+ * to "what did you just change" with it. It is handed to the run service as a setter, the same shape
+ * `memory` uses.
+ */
+const fileChanges = new FileChangeTracker();
+runService.setFileChanges(fileChanges);
+const fileIndexes = new Map();
+runService.setFileIndexes(fileIndexes);
 const conversationService = new ConversationService(store, runtime, subagents, broadcaster, catalogService, runService, extensionUiService, initialAgentDirs);
 conversationService.setMemory(memory);
 const workspaceService = new WorkspaceService(store, runtime, broadcaster, catalogService, runService, extensionUiService, uploadsDir, initialAgentDirs);
@@ -216,14 +240,17 @@ const serverContext = {
     runService,
     extensionUiService,
     catalogService,
+    providerService,
     execService,
     toolRegistry,
     toolRunner,
     toolLlm,
+    fileChanges,
+    fileIndexes,
     terminalEnabled: () => terminalService.enabled,
     terminalDisabledReason: () => terminalDisabledReason(),
 };
-const commandHandler = new CommandHandler(workspaceService, conversationService, runService, extensionUiService, catalogService, terminalService, rootDir);
+const commandHandler = new CommandHandler(workspaceService, conversationService, runService, extensionUiService, catalogService, terminalService, rootDir, providerService);
 // ------------------------------------------------------------- Lifecycle & shutdown
 let shutdownPromise;
 async function closeHttpServer() {

package/dist/server/pi-session-events.d.ts

@@ -60,6 +60,15 @@ export type TurnItem =
 /** The callbacks a turn supplies. The names match the RPC runtime's, so the two paths behave alike. */
 export interface TurnEventHandlers {
     onToolCall?(call: ToolCallNotice): void;
+    /**
+     * Called when a tool that WRITES A FILE is announced, with the path it is about to write.
+     *
+     * The same hook the RPC runtime has, and for the same reason: the announcement is the last moment
+     * the old content is still on the disk, so it is the only moment a diff baseline can be taken. The two
+     * paths (SDK session and spawned RPC) must agree on WHEN this fires, or the same edit would be
+     * baselined on one path and not on the other.
+     */
+    onFileWrite?(path: string, toolName: string, toolCallId?: string): void;
     onToolUpdate?(call: ToolCallNotice): void;
     onToolPreparing?(call: ToolCallPreparing): void;
     onToolEnd?(call: ToolCallNotice): void;

package/dist/server/pi-session-events.js

@@ -17,6 +17,7 @@
  * from, not what they mean.
  */
 import { describeToolCall, describeToolCallArgs, extractPartialResultText } from "./tool-calls.js";
+import { toolTargetPath } from "./file-changes.js";
 /** Keeps only real strings, so a malformed queue snapshot cannot put objects into a broadcast. */
 const textList = (value) => Array.isArray(value) ? value.filter((item) => typeof item === "string") : undefined;
 /**
@@ -258,6 +259,17 @@ export function handleSessionEvent(event, queue, handlers, report, failure) {
             catch (error) {
                 console.warn(`PiRpcRuntime: the tool call handler threw: ${error instanceof Error ? error.message : "unknown error"}`);
             }
+            // The file-writing call, announced before it runs - the only moment the old content is still on
+            // the disk. Fired and forgotten: the listener does its own I/O, off this handler's path.
+            const writePath = toolTargetPath(name, record.args);
+            if (writePath) {
+                try {
+                    handlers.onFileWrite?.(writePath, name, id);
+                }
+                catch (error) {
+                    console.warn(`PiRpcRuntime: the file-write handler threw: ${error instanceof Error ? error.message : "unknown error"}`);
+                }
+            }
             return true;
         }
         case "tool_execution_update": {

package/dist/server/pi-session-pool.d.ts

@@ -78,6 +78,15 @@ export declare class PiSessionPool {
      * knows what one looks like.
      */
     private readonly mintCapability;
+    /**
+     * How many times the set of models Pi knows about has changed.
+     *
+     * Injected rather than imported for the same reason the capability minting is: the pool needs to
+     * know WHEN a session is stale, and the caller knows what changed. A provider added through the
+     * settings window makes every live session unable to reach the new model, and the next turn is
+     * where that gets fixed.
+     */
+    private readonly modelEpoch;
     private readonly sessions;
     constructor(
     /** Where Pi keeps its session files. */
@@ -104,7 +113,16 @@ export declare class PiSessionPool {
      * does not have to know what a capability is - it needs to know WHEN one is needed, and the caller
      * knows what one looks like.
      */
-    mintCapability?: (conversationId: string) => string);
+    mintCapability?: (conversationId: string) => string, 
+    /**
+     * How many times the set of models Pi knows about has changed.
+     *
+     * Injected rather than imported for the same reason the capability minting is: the pool needs to
+     * know WHEN a session is stale, and the caller knows what changed. A provider added through the
+     * settings window makes every live session unable to reach the new model, and the next turn is
+     * where that gets fixed.
+     */
+    modelEpoch?: () => number);
     /**
      * The session for a conversation, built if there is none and REPLACED if the live one is stale.
      *

package/dist/server/pi-session-pool.js

@@ -48,6 +48,7 @@ export class PiSessionPool {
     onSessionDestroyed;
     factory;
     mintCapability;
+    modelEpoch;
     sessions = new Map();
     constructor(
     /** Where Pi keeps its session files. */
@@ -74,13 +75,23 @@ export class PiSessionPool {
      * does not have to know what a capability is - it needs to know WHEN one is needed, and the caller
      * knows what one looks like.
      */
-    mintCapability = () => "") {
+    mintCapability = () => "", 
+    /**
+     * How many times the set of models Pi knows about has changed.
+     *
+     * Injected rather than imported for the same reason the capability minting is: the pool needs to
+     * know WHEN a session is stale, and the caller knows what changed. A provider added through the
+     * settings window makes every live session unable to reach the new model, and the next turn is
+     * where that gets fixed.
+     */
+    modelEpoch = () => 0) {
         this.sessionDir = sessionDir;
         this.repositoryRoot = repositoryRoot;
         this.agentDir = agentDir;
         this.onSessionDestroyed = onSessionDestroyed;
         this.factory = factory;
         this.mintCapability = mintCapability;
+        this.modelEpoch = modelEpoch;
     }
     /**
      * The session for a conversation, built if there is none and REPLACED if the live one is stale.
@@ -227,6 +238,7 @@ export class PiSessionPool {
             tools: request.tools,
             excludeTools: request.excludeTools,
             extensions: superPiExtensionPaths(this.repositoryRoot),
+            modelEpoch: this.modelEpoch(),
         };
     }
     /**

package/dist/server/pi-session.d.ts

@@ -129,6 +129,16 @@ export interface SessionFingerprint {
     excludeTools: string[] | undefined;
     /** Which of Super Pi's own extensions were mounted. */
     extensions: string[];
+    /**
+     * How many times the set of models Pi knows about has changed.
+     *
+     * NOT THE MODEL, BUT THE WORLD THE MODEL LIVES IN. A session's `ModelRuntime` is built with it and
+     * does not learn about a provider added afterwards, so a session that keeps running on the old
+     * runtime cannot switch to a model that only exists in the new one - and Pi's refusal to switch is
+     * swallowed into a warning, which would leave the turn running a model the picker does not name.
+     * The counter makes such a session stale, and it is rebuilt at its next turn.
+     */
+    modelEpoch: number;
 }
 /**
  * Fingerprints are compared by VALUE, and this is where that comparison is spelled out.

package/dist/server/pi-session.js

@@ -185,6 +185,8 @@ export function sameFingerprint(a, b) {
         return false;
     if (!sameSet(a.extensions, b.extensions))
         return false;
+    if (a.modelEpoch !== b.modelEpoch)
+        return false;
     return true;
 }
 function sameSet(a, b) {
@@ -343,8 +345,17 @@ async function resolveSessionManager(sdk, creation) {
  * file goes out of its way not to do for a path it can derive. The derivation is Pi's own default:
  * `~/.pi/agent`, with the home directory taken from the environment rather than from `os.homedir()`,
  * because on Windows the two disagree often enough to matter.
+ *
+ * `PI_CODING_AGENT_DIR` WINS, exactly as it wins in Pi (`core/config.ts:getAgentDir`). A person who
+ * set it expects Pi to read its whole configuration from there, and this function used to disagree
+ * with Pi about it: Pi's model runtime read `models.json` from that directory while the session's
+ * resource loader read the skills from `~/.pi/agent`. Two halves of one Pi pointed at two
+ * directories, and only one of them was the one the person had configured.
  */
 function defaultAgentDir() {
+    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");
 }