@evandu/super-pi 0.1.144 → 0.1.146

package/dist/server/http-server.js

@@ -23,7 +23,8 @@ import { MAX_WEB_REQUEST_BYTES } from "./web.js";
 import { MAX_TOOL_BODY_BYTES } from "./tool-registry.js";
 import { packageUpdateArgs } from "./update.js";
 import { FileIndex } from "./file-index.js";
-import { ensureNameIndex } from "./file-name-index.js";
+import { ensureNameIndex, recordWorkspacePath } from "./file-name-index.js";
+import { resolveSessionCwd, sessionScopeKey, workspacePathFromSession } from "./session-cwd.js";
 import { MAX_CONTENT_DEPTH, MAX_CONTENT_FILE_BYTES, MAX_CONTENT_RESULTS, searchByContent } from "./content-search.js";
 import { getAvailableSkills, readSkill } from "./skills.js";
 /**
@@ -34,11 +35,11 @@ import { getAvailableSkills, readSkill } from "./skills.js";
  * known so far rather than refused. The scan is the server's cost, not the user's - the old
  * implementation made the user pay it on every keystroke.
  */
-function nameIndexFor(context, workspaceId, root) {
+function nameIndexFor(context, workspaceId, root, cwd = "") {
     const indexes = context.nameIndexes ?? new Map();
     if (!context.nameIndexes)
         context.nameIndexes = indexes;
-    return ensureNameIndex(indexes, workspaceId, root);
+    return ensureNameIndex(indexes, workspaceId, root, cwd);
 }
 const MIME_TYPES = {
     ".css": "text/css; charset=utf-8",
@@ -312,7 +313,7 @@ export function createHttpServer(options) {
             // the endpoint that can spend it is exactly the one an agent's own turn can reach, and the
             // management half (`/api/feishu/config`) stays behind the ordinary token AND the local-address
             // predicate.
-            if (requestPath !== "/api/memory/tool" && requestPath !== "/api/knowledge/tool" && requestPath !== "/api/documents/tool" && requestPath !== "/api/web/tool" && requestPath !== "/api/feishu/tool" && requestPath !== "/api/todos" && requestPath !== "/api/scheduled-tasks" && requestPath !== "/api/question" && (requestPath !== "/api/tools" || request.method !== "POST") && !requestPath.startsWith("/tools/") && !isAuthorized(request, accessToken)) {
+            if (requestPath !== "/api/conversation/usage" && requestPath !== "/api/memory/tool" && requestPath !== "/api/knowledge/tool" && requestPath !== "/api/documents/tool" && requestPath !== "/api/web/tool" && requestPath !== "/api/feishu/tool" && requestPath !== "/api/todos" && requestPath !== "/api/scheduled-tasks" && requestPath !== "/api/question" && (requestPath !== "/api/tools" || request.method !== "POST") && !requestPath.startsWith("/tools/") && !isAuthorized(request, accessToken)) {
                 response.writeHead(401, { "www-authenticate": "Bearer" }).end("Authentication required");
                 return;
             }
@@ -1070,6 +1071,8 @@ export function createHttpServer(options) {
                         json(404, { error: `工作区 ${workspaceId ?? "(missing)"} 不存在`, code: "no_workspace" });
                         return;
                     }
+                    const sessionRoot = await resolveSessionCwd(workspace.path, url.searchParams.get("cwd"));
+                    const cwd = relative(resolve(workspace.path), sessionRoot).replaceAll("\\", "/");
                     const op = url.searchParams.get("op") ?? "status";
                     // Blame is a read with a GET shape: every other verb is refused HERE, before the POST branch
                     // could ever route the op into gitMutate and before any body is read.
@@ -1095,7 +1098,8 @@ export function createHttpServer(options) {
                         }
                         const raw = asked.text;
                         const body = raw ? JSON.parse(raw) : {};
-                        json(200, await gitMutate(workspace.path, op, body.path, body.message));
+                        const path = body.path ? await workspacePathFromSession(workspace.path, sessionRoot, body.path) : undefined;
+                        json(200, await gitMutate(workspace.path, op, path, body.message, cwd));
                         return;
                     }
                     if (request.method !== "GET") {
@@ -1103,16 +1107,16 @@ export function createHttpServer(options) {
                         return;
                     }
                     if (op === "status")
-                        json(200, await gitStatus(workspace.path));
+                        json(200, await gitStatus(workspace.path, cwd));
                     else if (op === "log")
-                        json(200, await gitLog(workspace.path, Number(url.searchParams.get("limit") ?? 20)));
+                        json(200, await gitLog(workspace.path, Number(url.searchParams.get("limit") ?? 20), cwd));
                     else if (op === "diff") {
                         const path = url.searchParams.get("path");
                         if (!path) {
                             json(400, { error: "diff 需要 path", code: "bad_path" });
                             return;
                         }
-                        json(200, await gitDiff(workspace.path, path, url.searchParams.get("staged") === "1"));
+                        json(200, await gitDiff(workspace.path, await workspacePathFromSession(workspace.path, sessionRoot, path), url.searchParams.get("staged") === "1"));
                     }
                     else if (op === "blame") {
                         const path = url.searchParams.get("path");
@@ -1122,7 +1126,7 @@ export function createHttpServer(options) {
                         }
                         const startLine = url.searchParams.get("startLine");
                         const endLine = url.searchParams.get("endLine");
-                        json(200, await gitBlame(workspace.path, path, {
+                        json(200, await gitBlame(workspace.path, await workspacePathFromSession(workspace.path, sessionRoot, path), {
                             revision: url.searchParams.get("revision") ?? undefined,
                             startLine: startLine === null ? undefined : Number(startLine),
                             endLine: endLine === null ? undefined : Number(endLine),
@@ -1136,7 +1140,7 @@ export function createHttpServer(options) {
                     const code = error?.code;
                     if (code === 128 || code === "not_a_repo" || /not a git repository/i.test(message))
                         json(404, { error: "此工作区不是 git 仓库", code: "not_a_repo" });
-                    else if (code === "path")
+                    else if (code === "path" || code === "outside_workspace")
                         json(400, { error: message, code: "bad_path" });
                     else if (code === "not_found")
                         json(404, { error: message, code: "not_found" });
@@ -1480,27 +1484,70 @@ export function createHttpServer(options) {
                     }
                     const action = (body.action || "").trim();
                     if (action === "spawn") {
+                        // Capability auth above proves who is calling. The target workspace is a separate, explicit
+                        // choice: a parentConversationId records a tree edge and never selects that target.
+                        const requestedWorkspaceId = body.workspaceId?.trim();
+                        if (!requestedWorkspaceId) {
+                            json(400, { error: "创建会话必须显式指定 workspaceId；父会话只记录树形关系，不能代替目标工作区。" });
+                            return;
+                        }
+                        const store = context.store;
+                        const callerWorkspaceId = store && callerConversationId
+                            ? store.conversation(callerConversationId)?.workspaceId
+                            : undefined;
+                        if (requestedWorkspaceId !== callerWorkspaceId) {
+                            json(403, {
+                                error: `调用方会话 ${callerConversationId} 所在工作区为 ${callerWorkspaceId ?? "未知"}，请求的目标工作区 ${requestedWorkspaceId} 不属于调用方，拒绝在该工作区创建会话。请传入调用方自己的工作区。`,
+                            });
+                            return;
+                        }
                         if (!body.task)
                             throw new Error("spawn requires task");
                         const result = await service.spawn({
                             task: body.task,
                             parentConversationId: body.parentConversationId,
-                            workspaceId: body.workspaceId,
+                            workspaceId: requestedWorkspaceId,
                             title: body.title,
                             agentId: body.agentId,
                             model: body.model,
                             thinkingLevel: body.thinkingLevel,
                             initialPrompt: body.initialPrompt,
                             wait: body.wait,
+                            cwd: body.cwd,
                         });
                         json(200, { ok: true, ...result });
                         return;
                     }
+                    const verifyTargetScope = (targetConversationId) => {
+                        const store = context.store;
+                        const callerWorkspaceId = store && callerConversationId
+                            ? store.conversation(callerConversationId)?.workspaceId
+                            : undefined;
+                        if (!callerWorkspaceId) {
+                            return {
+                                ok: false,
+                                error: `调用方会话 ${callerConversationId} 不存在或未关联有效工作区，拒绝编排操作。`,
+                            };
+                        }
+                        const target = store?.conversation(targetConversationId);
+                        if (target && target.workspaceId !== callerWorkspaceId) {
+                            return {
+                                ok: false,
+                                error: `调用方会话 ${callerConversationId} 所在工作区为 ${callerWorkspaceId}，目标会话 ${targetConversationId} 所在工作区为 ${target.workspaceId}，拒绝跨工作区操作。目标会话必须属于调用方工作区。`,
+                            };
+                        }
+                        return { ok: true };
+                    };
                     if (action === "dispatch") {
                         if (!body.conversationId)
                             throw new Error("dispatch requires conversationId");
                         if (!body.content)
                             throw new Error("dispatch requires content");
+                        const scope = verifyTargetScope(body.conversationId);
+                        if (!scope.ok) {
+                            json(403, { error: scope.error });
+                            return;
+                        }
                         const result = await service.dispatch(body.conversationId, body.content, { wait: body.wait });
                         json(200, { ok: true, ...result });
                         return;
@@ -1508,18 +1555,48 @@ export function createHttpServer(options) {
                     if (action === "status") {
                         if (!body.conversationId)
                             throw new Error("status requires conversationId");
+                        const scope = verifyTargetScope(body.conversationId);
+                        if (!scope.ok) {
+                            json(403, { error: scope.error });
+                            return;
+                        }
                         const summary = await service.status(body.conversationId, { includeOutput: body.includeOutput });
                         json(200, { ok: true, summary });
                         return;
                     }
                     if (action === "list") {
-                        const sessions = await service.list(body.parentConversationId);
-                        json(200, { ok: true, sessions });
+                        const store = context.store;
+                        const callerWorkspaceId = store && callerConversationId
+                            ? store.conversation(callerConversationId)?.workspaceId
+                            : undefined;
+                        if (!callerWorkspaceId) {
+                            json(403, { error: `调用方会话 ${callerConversationId} 不存在或未关联有效工作区，拒绝编排操作。` });
+                            return;
+                        }
+                        const requestedParentId = body.parentConversationId?.trim();
+                        if (requestedParentId) {
+                            const targetParent = store?.conversation(requestedParentId);
+                            if (targetParent && targetParent.workspaceId !== callerWorkspaceId) {
+                                json(403, {
+                                    error: `调用方会话 ${callerConversationId} 所在工作区为 ${callerWorkspaceId}，请求的父会话 ${requestedParentId} 所在工作区为 ${targetParent.workspaceId}，拒绝跨工作区查询。父会话必须属于调用方工作区。`,
+                                });
+                                return;
+                            }
+                        }
+                        const effectiveParentId = requestedParentId || callerConversationId;
+                        const sessions = await service.list(effectiveParentId);
+                        const allowedSessions = sessions.filter((s) => !s.workspaceId || s.workspaceId === callerWorkspaceId);
+                        json(200, { ok: true, sessions: allowedSessions });
                         return;
                     }
                     if (action === "stop") {
                         if (!body.conversationId)
                             throw new Error("stop requires conversationId");
+                        const scope = verifyTargetScope(body.conversationId);
+                        if (!scope.ok) {
+                            json(403, { error: scope.error });
+                            return;
+                        }
                         const result = await service.stop(body.conversationId, { mode: body.mode, messageId: body.messageId });
                         json(200, { ok: true, ...result });
                         return;
@@ -1527,6 +1604,11 @@ export function createHttpServer(options) {
                     if (action === "resume") {
                         if (!body.conversationId)
                             throw new Error("resume requires conversationId");
+                        const scope = verifyTargetScope(body.conversationId);
+                        if (!scope.ok) {
+                            json(403, { error: scope.error });
+                            return;
+                        }
                         const result = await service.resume(body.conversationId, body.prompt, { wait: body.wait });
                         json(200, { ok: true, ...result });
                         return;
@@ -1538,6 +1620,36 @@ export function createHttpServer(options) {
                 }
                 return;
             }
+            if (url.pathname === "/api/conversation/usage") {
+                const json = (status, payload) => {
+                    response.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" }).end(JSON.stringify(payload));
+                };
+                if (request.method !== "GET" || !isLocalOrPrivateAddress(remote)) {
+                    json(403, { error: "Usage readout requires a local/private GET request." });
+                    return;
+                }
+                const callerConversationId = url.searchParams.get("callerConversationId") ?? "";
+                const capability = request.headers["x-super-pi-capability"] ?? url.searchParams.get("capability");
+                const verdict = runService.verifyPrimaryCapability(callerConversationId, capability);
+                if (!verdict.ok) {
+                    json(403, { error: verdict.message });
+                    return;
+                }
+                const target = url.searchParams.get("conversationId") ?? callerConversationId;
+                if (target !== callerConversationId) {
+                    json(403, { error: "Only the caller's own conversation usage may be read." });
+                    return;
+                }
+                const conversation = store.conversation(callerConversationId);
+                if (!conversation) {
+                    json(403, { error: "Caller conversation is unavailable." });
+                    return;
+                }
+                json(200, { ok: true, conversationId: callerConversationId, usage: conversation.usage ?? null,
+                    usageCostKnown: conversation.usageCostKnown ?? null, contextUsage: conversation.contextUsage ?? null,
+                    usageUpdatedAt: conversation.usageUpdatedAt ?? null });
+                return;
+            }
             if (url.pathname === "/api/orchestrator/status" && request.method === "GET") {
                 if (!isLocalOrPrivateAddress(remote)) {
                     response.writeHead(403).end();
@@ -1559,6 +1671,23 @@ export function createHttpServer(options) {
                     response.writeHead(400, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "缺少 conversationId" }));
                     return;
                 }
+                const store = context.store;
+                const callerWorkspaceId = store && callerConversationId
+                    ? store.conversation(callerConversationId)?.workspaceId
+                    : undefined;
+                if (!callerWorkspaceId) {
+                    response.writeHead(403, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({
+                        error: `调用方会话 ${callerConversationId} 不存在或未关联有效工作区，拒绝编排操作。`,
+                    }));
+                    return;
+                }
+                const target = store?.conversation(conversationId);
+                if (target && target.workspaceId !== callerWorkspaceId) {
+                    response.writeHead(403, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({
+                        error: `调用方会话 ${callerConversationId} 所在工作区为 ${callerWorkspaceId}，目标会话 ${conversationId} 所在工作区为 ${target.workspaceId}，拒绝跨工作区操作。目标会话必须属于调用方工作区。`,
+                    }));
+                    return;
+                }
                 try {
                     const summary = await service.status(conversationId, { includeOutput: url.searchParams.get("includeOutput") === "true" });
                     response.writeHead(200, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ ok: true, summary }));
@@ -1585,9 +1714,30 @@ export function createHttpServer(options) {
                     response.writeHead(403, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: verdict.message }));
                     return;
                 }
+                const store = context.store;
+                const callerWorkspaceId = store && callerConversationId
+                    ? store.conversation(callerConversationId)?.workspaceId
+                    : undefined;
+                if (!callerWorkspaceId) {
+                    response.writeHead(403, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({
+                        error: `调用方会话 ${callerConversationId} 不存在或未关联有效工作区，拒绝编排操作。`,
+                    }));
+                    return;
+                }
+                if (parentId) {
+                    const targetParent = store?.conversation(parentId);
+                    if (targetParent && targetParent.workspaceId !== callerWorkspaceId) {
+                        response.writeHead(403, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({
+                            error: `调用方会话 ${callerConversationId} 所在工作区为 ${callerWorkspaceId}，请求的父会话 ${parentId} 所在工作区为 ${targetParent.workspaceId}，拒绝跨工作区查询。父会话必须属于调用方工作区。`,
+                        }));
+                        return;
+                    }
+                }
                 try {
-                    const sessions = await service.list(parentId);
-                    response.writeHead(200, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ ok: true, sessions }));
+                    const effectiveParentId = parentId || callerConversationId;
+                    const sessions = await service.list(effectiveParentId);
+                    const allowedSessions = sessions.filter((s) => !s.workspaceId || s.workspaceId === callerWorkspaceId);
+                    response.writeHead(200, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ ok: true, sessions: allowedSessions }));
                 }
                 catch (error) {
                     response.writeHead(400, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: error instanceof Error ? error.message : "list failed" }));
@@ -1644,16 +1794,20 @@ export function createHttpServer(options) {
                         json(400, { error: "需要 path 参数", code: "bad_request" });
                         return;
                     }
+                    const root = await resolveSessionCwd(workspace.path, url.searchParams.get("cwd"));
+                    const workspaceRelativePath = await workspacePathFromSession(workspace.path, root, path);
                     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,
+                        root,
                         path,
                         preferred,
                         tracker: context.fileChanges,
                         workspaceId,
+                        gitRoot: workspace.path,
+                        trackerPath: workspaceRelativePath,
                     });
                     json(200, diff);
                 }
@@ -1677,7 +1831,9 @@ export function createHttpServer(options) {
                         json(404, { error: "找不到这个工作区——它可能已经被删除。", code: "no_workspace" });
                         return;
                     }
-                    await resolveInsideRoot(workspace.path, "");
+                    const root = await resolveSessionCwd(workspace.path, url.searchParams.get("cwd"));
+                    const cwd = relative(resolve(workspace.path), root).replaceAll("\\", "/");
+                    const indexKey = sessionScopeKey(workspaceId, cwd);
                     if (query.length > 256 || /[\r\n]/.test(query)) {
                         json(400, { error: "搜索词只能是一行，且不超过 256 个字符。", code: "bad_query" });
                         return;
@@ -1689,17 +1845,17 @@ export function createHttpServer(options) {
                     const indexes = context.fileIndexes ?? new Map();
                     if (!context.fileIndexes)
                         context.fileIndexes = indexes;
-                    let index = indexes.get(workspaceId);
+                    let index = indexes.get(indexKey);
                     if (!index) {
-                        index = new FileIndex(workspaceId, (event) => broadcaster.broadcast(event));
-                        indexes.set(workspaceId, index);
+                        index = new FileIndex(workspaceId, (event) => broadcaster.broadcast(event), cwd);
+                        indexes.set(indexKey, index);
                     }
-                    index.start(workspace.path);
+                    index.start(root);
                     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);
+                    const result = await searchByContent(root, [...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) {
@@ -1738,18 +1894,21 @@ export function createHttpServer(options) {
                         json(404, { error: `找不到工作区「${workspaceId ?? "未指定"}」——它可能已经被删除。`, code: "no_workspace" });
                         return;
                     }
+                    const root = await resolveSessionCwd(workspace.path, url.searchParams.get("cwd"));
+                    const cwd = relative(resolve(workspace.path), root).replaceAll("\\", "/");
+                    const indexKey = sessionScopeKey(workspaceId, cwd);
                     const indexes = context.fileIndexes ?? new Map();
                     if (!context.fileIndexes)
                         context.fileIndexes = indexes;
-                    let index = indexes.get(workspaceId);
+                    let index = indexes.get(indexKey);
                     if (!index) {
-                        index = new FileIndex(workspaceId, (event) => broadcaster.broadcast(event));
-                        indexes.set(workspaceId, index);
+                        index = new FileIndex(workspaceId, (event) => broadcaster.broadcast(event), cwd);
+                        indexes.set(indexKey, index);
                     }
-                    index.start(workspace.path);
+                    index.start(root);
                     // Quick Open requests the full index on demand. Name search can share its background scan;
                     // merely selecting a session no longer starts a multi-MB download.
-                    nameIndexFor(context, workspaceId, workspace.path);
+                    nameIndexFor(context, workspaceId, root, cwd);
                     const sinceRaw = url.searchParams.get("since");
                     const since = sinceRaw === null ? undefined : Number(sinceRaw);
                     json(200, index.snapshot(Number.isSafeInteger(since) && since >= 0 ? since : undefined));
@@ -1771,7 +1930,9 @@ export function createHttpServer(options) {
                         json(404, { error: `找不到工作区「${workspaceId ?? "未指定"}」——它可能已经被删除。`, code: "no_workspace" });
                         return;
                     }
-                    const root = workspace.path;
+                    const root = await resolveSessionCwd(workspace.path, url.searchParams.get("cwd"));
+                    const cwd = relative(resolve(workspace.path), root).replaceAll("\\", "/");
+                    const indexKey = sessionScopeKey(workspaceId, cwd);
                     if (url.pathname === "/api/files") {
                         if (request.method !== "GET") {
                             json(405, { error: "目录列表需要 GET 请求。", code: "method" });
@@ -1787,7 +1948,7 @@ export function createHttpServer(options) {
                             // report a limit about. `truncated` and `skipped` stay in the response so the protocol
                             // shape does not change under the client, but they are now constants that say the
                             // opposite of what they used to.
-                            const index = nameIndexFor(context, workspaceId, root);
+                            const index = nameIndexFor(context, workspaceId, root, cwd);
                             // THE WORKSPACE MUST EXIST, AND THE INDEX IS WHAT KNOWS.
                             //
                             // The background scan records a root it could not read rather than throwing it - a scan
@@ -1827,12 +1988,12 @@ export function createHttpServer(options) {
                             const resolved = await resolveInsideRoot(root, rel);
                             const meta = await fileMeta(resolved);
                             const path = toRelative(root, resolved);
-                            context.fileIndexes?.get(workspaceId)?.recordFile(path, meta);
+                            context.fileIndexes?.get(indexKey)?.recordFile(path, meta);
                             json(200, { path, ...meta });
                             return;
                         }
                         const file = await readWorkspaceFile(root, rel);
-                        context.fileIndexes?.get(workspaceId)?.recordFile(file.path, file.meta);
+                        context.fileIndexes?.get(indexKey)?.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;
                     }
@@ -1867,11 +2028,12 @@ 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);
+                        context.fileIndexes?.get(indexKey)?.recordFile(outcome.path, outcome.meta);
                         // The name index learns about the save too. A file the user just saved must be findable
                         // by name immediately, and the index is the thing the search reads - so this is where the
                         // index stays true without anybody re-scanning the tree.
-                        context.nameIndexes?.get(workspaceId)?.upsert(outcome.path);
+                        if (context.nameIndexes)
+                            recordWorkspacePath(context.nameIndexes, workspaceId, workspace.path, await workspacePathFromSession(workspace.path, root, outcome.path));
                         json(200, outcome);
                         return;
                     }

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

@@ -0,0 +1,46 @@
+/** One model's declared window, as the person's file states it. */
+export type DeclaredWindow = {
+    provider: string;
+    modelId: string;
+    contextWindow: number;
+};
+/**
+ * The windows the person's `models.json` declares, keyed by `provider/modelId`.
+ *
+ * Pi's file shape is `{ providers: { <providerId>: { models: [{ id, contextWindow, ... }] } } }`,
+ * and a model without a `contextWindow` is simply not declared - it does not become a zero, because
+ * a zero would be a claim ("this model has no window") rather than an absence.
+ */
+export declare function declaredWindows(modelsJson: unknown): Map<string, number>;
+/**
+ * The window to USE for a model, given what the person's file says.
+ *
+ * `undefined` means "say nothing" - the caller keeps whatever Pi believes. That is the honest
+ * answer for a model the person's file does not mention: Super Pi has no opinion about a model
+ * somebody else configured, and inventing one would be the same mistake in the other direction.
+ *
+ * TWO LOOKUPS, AND THE SECOND ONE IS THE ONE THAT MATTERS:
+ *
+ *   1. `provider/modelId` - the exact pair. This is the common case.
+ *   2. `modelId` ALONE, across every provider the person's file declares.
+ *
+ * The second lookup exists because a CONTEXT WINDOW IS A PROPERTY OF THE MODEL, NOT OF THE
+ * ENDPOINT. Measured on this machine: the person's `models.json` declares the model `MiniMax-M3`
+ * under the provider id `minimax` (the OpenAI-compatible endpoint) with `contextWindow: 128000`,
+ * while Pi's remote catalogue declares the SAME model under a DIFFERENT provider id,
+ * `minimax-cn` (the Anthropic-compatible endpoint), with `contextWindow: 1000000`. The session runs
+ * on `minimax-cn`, so the exact-pair lookup finds nothing and the bogus number survives.
+ *
+ * When several providers declare the same model with DIFFERENT windows, the SMALLEST wins: a model
+ * can never really have more context than its own limit, and a window that is too large is exactly
+ * the failure this exists to prevent - it pushes compaction past the point where the model refuses.
+ */
+export declare function effectiveContextWindow(declared: Map<string, number>, provider: string, modelId: string, reported?: number): number | undefined;
+/**
+ * Reads the person's `models.json` and returns its declared windows.
+ *
+ * A missing or unreadable file is an empty map, not a throw: Super Pi must not refuse to start
+ * because a person has not configured a custom provider, and the consequence of an empty map is
+ * simply "Super Pi has no opinion about this model's window" - which is where it started.
+ */
+export declare function readDeclaredWindows(agentDir: string): Map<string, number>;

package/dist/server/model-context-window.js

@@ -0,0 +1,121 @@
+/**
+ * THE CONTEXT WINDOW A MODEL REALLY HAS.
+ *
+ * Pi reads its model list from two places and one of them wins:
+ *
+ *   - `~/.pi/agent/models.json` - the file a PERSON writes, or that Super Pi writes from its own
+ *     registry. Its `contextWindow` is a deliberate statement about the model.
+ *   - `~/.pi/agent/models-store.json` - the REMOTE CATALOGUE Pi fetches from the provider, with
+ *     an etag and a timestamp. Its `contextWindow` is the PROVIDER'S SELF-REPORT.
+ *
+ * Pi's own merge lets the remote catalogue overwrite the person's file (`merged[index] = model`),
+ * so a provider that reports a generous window wins over the one the person configured.
+ *
+ * WHY THAT MATTERS, AND HOW IT BREAKS A SESSION:
+ *
+ *   Pi's auto-compaction is `shouldCompact(contextTokens, contextWindow, settings)`, i.e.
+ *   `contextTokens > contextWindow - reserveTokens`. With `reserveTokens = 16384` and a reported
+ *   window of 1,000,000, compaction waits for 983,616 tokens. The real window of that model is
+ *   128,000. So the model refuses the request at 128K, and the OVERFLOW RECOVERY - which asks the
+ *   SAME model to summarise the same too-long conversation - fails the same way. The session is
+ *   then a session that cannot answer anything, and the reader sees a dead conversation.
+ *
+ *   Measured on this machine: `models.json` says `MiniMax-M3` has `contextWindow: 128000`; the
+ *   remote catalogue says `1000000`; Pi ends up believing 1,000,000.
+ *
+ * SO: THE PERSON'S FILE WINS. A number somebody typed is a decision; a number a catalogue fetched
+ * is a claim, and a claim that is too generous does not fail loudly - it fails by never compacting.
+ *
+ * This module is deliberately narrow: it reads the person's file, and it says what the model
+ * window SHOULD be. It does not touch Pi, does not decide anything else, and is a pure function of
+ * two plain objects so it can be tested without a server, a socket, a browser or a model.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * The windows the person's `models.json` declares, keyed by `provider/modelId`.
+ *
+ * Pi's file shape is `{ providers: { <providerId>: { models: [{ id, contextWindow, ... }] } } }`,
+ * and a model without a `contextWindow` is simply not declared - it does not become a zero, because
+ * a zero would be a claim ("this model has no window") rather than an absence.
+ */
+export function declaredWindows(modelsJson) {
+    const out = new Map();
+    if (!modelsJson || typeof modelsJson !== "object")
+        return out;
+    const providers = modelsJson.providers;
+    if (!providers || typeof providers !== "object")
+        return out;
+    for (const [providerId, provider] of Object.entries(providers)) {
+        if (!provider || typeof provider !== "object")
+            continue;
+        const models = provider.models;
+        if (!Array.isArray(models))
+            continue;
+        for (const model of models) {
+            if (!model || typeof model !== "object")
+                continue;
+            const id = model.id;
+            const window = model.contextWindow;
+            if (typeof id !== "string" || !id.trim())
+                continue;
+            if (typeof window !== "number" || !Number.isSafeInteger(window) || window <= 0)
+                continue;
+            out.set(`${providerId}/${id}`, window);
+        }
+    }
+    return out;
+}
+/**
+ * The window to USE for a model, given what the person's file says.
+ *
+ * `undefined` means "say nothing" - the caller keeps whatever Pi believes. That is the honest
+ * answer for a model the person's file does not mention: Super Pi has no opinion about a model
+ * somebody else configured, and inventing one would be the same mistake in the other direction.
+ *
+ * TWO LOOKUPS, AND THE SECOND ONE IS THE ONE THAT MATTERS:
+ *
+ *   1. `provider/modelId` - the exact pair. This is the common case.
+ *   2. `modelId` ALONE, across every provider the person's file declares.
+ *
+ * The second lookup exists because a CONTEXT WINDOW IS A PROPERTY OF THE MODEL, NOT OF THE
+ * ENDPOINT. Measured on this machine: the person's `models.json` declares the model `MiniMax-M3`
+ * under the provider id `minimax` (the OpenAI-compatible endpoint) with `contextWindow: 128000`,
+ * while Pi's remote catalogue declares the SAME model under a DIFFERENT provider id,
+ * `minimax-cn` (the Anthropic-compatible endpoint), with `contextWindow: 1000000`. The session runs
+ * on `minimax-cn`, so the exact-pair lookup finds nothing and the bogus number survives.
+ *
+ * When several providers declare the same model with DIFFERENT windows, the SMALLEST wins: a model
+ * can never really have more context than its own limit, and a window that is too large is exactly
+ * the failure this exists to prevent - it pushes compaction past the point where the model refuses.
+ */
+export function effectiveContextWindow(declared, provider, modelId, reported) {
+    const exact = declared.get(`${provider}/${modelId}`);
+    if (exact !== undefined)
+        return exact;
+    let smallest;
+    for (const [key, window] of declared) {
+        const slash = key.indexOf("/");
+        if (slash < 0 || key.slice(slash + 1) !== modelId)
+            continue;
+        if (smallest === undefined || window < smallest)
+            smallest = window;
+    }
+    return smallest;
+}
+/**
+ * Reads the person's `models.json` and returns its declared windows.
+ *
+ * A missing or unreadable file is an empty map, not a throw: Super Pi must not refuse to start
+ * because a person has not configured a custom provider, and the consequence of an empty map is
+ * simply "Super Pi has no opinion about this model's window" - which is where it started.
+ */
+export function readDeclaredWindows(agentDir) {
+    try {
+        const raw = readFileSync(join(agentDir, "models.json"), "utf8");
+        return declaredWindows(JSON.parse(raw));
+    }
+    catch {
+        return new Map();
+    }
+}

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

@@ -349,6 +349,12 @@ export interface PiSessionLike {
         provider?: string;
         id?: string;
     } | undefined;
+    /** Pi's estimate for the current context, including its post-compaction unknown state. */
+    getContextUsage?(): {
+        tokens: number | null;
+        contextWindow: number;
+        percent: number | null;
+    } | undefined;
     /**
      * Switches the model on a LIVE session.
      *