@youweichen/pi-harness 0.0.0-stage → 1.0.0

package/dist/server/bg-servers.js

@@ -0,0 +1,154 @@
+import { killPidTree, lookupProcessName, lookupProcessCommandLine, snapshotListeningPorts, } from "./process-utils.js";
+const BG_REFRESH_INTERVAL_MS = 30_000;
+/** bash 结束后等这么久再拍「后」快照——给后台服务绑定端口的时间。 */
+const BG_BIND_WAIT_MS = 1500;
+export class BgServerTracker {
+    opts;
+    servers = new Map();
+    /** bash 工具开始执行前拍的监听端口快照（tool_execution_start 时设置）。 */
+    listenBefore = null;
+    refreshTimer = null;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** True while AI-started background servers are tracked (keeps the client session alive). */
+    hasServers() {
+        return this.servers.size > 0;
+    }
+    /** 启动周期性存活检查（死项静默剔除）。 */
+    start() {
+        this.refreshTimer = setInterval(() => void this.refresh(), BG_REFRESH_INTERVAL_MS);
+        this.refreshTimer.unref?.();
+    }
+    stop() {
+        if (this.refreshTimer) {
+            clearInterval(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+    }
+    /** tool_execution_start(bash)：先记下「前」快照。 */
+    snapshotBefore() {
+        void snapshotListeningPorts().then((m) => {
+            this.listenBefore = m;
+        });
+    }
+    /** After a bash tool run, wait briefly for background servers to bind,
+     *  then diff the listening-port snapshot against the pre-run one and
+     *  remember anything new — those are servers the agent left running. */
+    async trackAfterBash() {
+        const before = this.listenBefore;
+        this.listenBefore = null;
+        if (!before)
+            return;
+        await new Promise((r) => setTimeout(r, BG_BIND_WAIT_MS));
+        const after = await snapshotListeningPorts();
+        let added = false;
+        for (const [port, pid] of after) {
+            if (!before.has(port) && !this.servers.has(port)) {
+                this.servers.set(port, { pid, since: Date.now() });
+                added = true;
+                // Best-effort process name + full command line so the panel shows
+                // something readable (name) AND what is actually running (command).
+                void lookupProcessName(pid).then((name) => {
+                    const cur = this.servers.get(port);
+                    if (cur && cur.pid === pid && name) {
+                        cur.name = name;
+                        this.push();
+                    }
+                });
+                void lookupProcessCommandLine(pid).then((command) => {
+                    const cur = this.servers.get(port);
+                    if (cur && cur.pid === pid && command) {
+                        cur.command = command;
+                        this.push();
+                    }
+                });
+                this.opts.emit({
+                    type: "notice",
+                    level: "info",
+                    text: `检测到 AI 启动的后台服务：端口 ${port}（pid ${pid}）——可在顶栏「后台任务」里单独停止或全部关闭`,
+                });
+            }
+        }
+        if (added)
+            this.push();
+    }
+    /** The current background-server list, oldest first. 合并插件任务。 */
+    list() {
+        const out = [...this.servers.entries()]
+            .map(([port, v]) => ({
+            port,
+            pid: v.pid,
+            since: v.since,
+            ...(v.name ? { name: v.name } : {}),
+            ...(v.command ? { command: v.command } : {}),
+        }))
+            .sort((a, b) => a.since - b.since);
+        for (const t of this.opts.pluginTasks?.() ?? [])
+            out.push(t);
+        return out;
+    }
+    /** Push the current background-task list to every connected socket. */
+    push() {
+        this.opts.emit({ type: "bg_servers", servers: this.list() });
+    }
+    /** Re-snapshot listening ports and drop tracked entries that are no longer
+     *  listening — the process exited on its own, so it must leave the panel.
+     *  Port AND pid must both match: a port reused by an unrelated process is
+     *  not our server anymore. Silent (the list just updates). */
+    async refresh() {
+        if (this.opts.isDisposed() || this.servers.size === 0)
+            return;
+        const now = await snapshotListeningPorts();
+        let changed = false;
+        for (const [port, v] of [...this.servers]) {
+            if (now.get(port) !== v.pid) {
+                this.servers.delete(port);
+                changed = true;
+            }
+        }
+        if (changed)
+            this.push();
+    }
+    /** Re-push the current list on request (panel opened); prunes dead entries first. */
+    async listAndPush() {
+        await this.refresh();
+        this.push();
+    }
+    /** Kill ONE background server (by port); returns whether anything was killed. */
+    async killOne(port) {
+        const entry = this.servers.get(port);
+        if (!entry) {
+            this.opts.emit({
+                type: "notice",
+                level: "info",
+                text: `端口 ${port} 不在后台任务列表中`,
+            });
+            this.opts.flushSnapshot();
+            return false;
+        }
+        killPidTree(entry.pid);
+        this.servers.delete(port);
+        this.push();
+        this.opts.emit({
+            type: "notice",
+            level: "info",
+            text: `已停止后台任务：端口 ${port}（pid ${entry.pid}）`,
+        });
+        this.opts.flushSnapshot();
+        return true;
+    }
+    /** Kill every background server the agent started; returns the freed ports. */
+    async killAll() {
+        if (this.servers.size === 0)
+            return [];
+        const killed = [];
+        for (const [port, { pid }] of [...this.servers]) {
+            killPidTree(pid);
+            killed.push(String(port));
+        }
+        this.servers.clear();
+        this.push();
+        return killed;
+    }
+}

package/dist/server/client-eviction.js

@@ -0,0 +1,19 @@
+export const DEFAULT_CLIENT_IDLE_MS = 30 * 60_000;
+export function clientIdleMsFromEnv(value) {
+    if (value === undefined || value.trim() === "")
+        return DEFAULT_CLIENT_IDLE_MS;
+    const minutes = Number(value);
+    return Number.isFinite(minutes) && minutes >= 0 ? minutes * 60_000 : DEFAULT_CLIENT_IDLE_MS;
+}
+/** idleMs <= 0 disables eviction. */
+export function isClientEvictable(facts, now, idleMs) {
+    if (idleMs <= 0 || facts.disposed || facts.switchingWorkspace)
+        return false;
+    if (facts.socketCount > 0 || facts.idleSince <= 0)
+        return false;
+    if (facts.streamingConversations > 0 || facts.queuedMessages > 0)
+        return false;
+    if (facts.liveTerminals > 0 || facts.backgroundTasks > 0)
+        return false;
+    return now - facts.idleSince >= idleMs;
+}

package/dist/server/client-id.js

@@ -0,0 +1,9 @@
+/**
+ * clientId arrives from the browser and is later used in file paths (uploads/<clientId>/)
+ * and as a map key. Real ids are UUIDs; accept any plain token that cannot
+ * contain a path separator or start with a dot.
+ */
+const CLIENT_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+export function isValidClientId(value) {
+    return typeof value === "string" && CLIENT_ID_RE.test(value);
+}

package/dist/server/client-state.js

@@ -0,0 +1,202 @@
+/** Per-client UI preferences and project/session navigation, persisted best-effort. */
+import { readFileSync } from "node:fs";
+import { writeFileAtomic } from "./private-file.js";
+import { dirname } from "node:path";
+/** Stable identity of an extension for its read-only resource view: the npm
+ *  spec for packages (survives version bumps), the resolved entry path
+ *  otherwise. */
+export function extensionKey(e) {
+    const src = e.sourceInfo;
+    if (src?.origin === "package" && src.source)
+        return src.source;
+    return src?.path ?? e.path;
+}
+/** Upper bound on persisted client entries (see ClientStateStore.prune). */
+const MAX_CLIENT_ENTRIES = 200;
+/**
+ * Merge persisted projects with disk-discovered ones into the project list:
+ * ordered by latest use/activity, newest first. Persisted first-added values
+ * remain as stable tie-breakers and for legacy data migration.
+ * Tombstoned entries (explicitly removed by the user) stay hidden; the list is
+ * capped at 20, dropping the least recently used first.
+ */
+export function mergeProjectSummaries(saved, disk, removed) {
+    const firstAdded = new Map();
+    const lastUsed = new Map();
+    for (const p of saved) {
+        firstAdded.set(p.path, p.firstAdded ?? p.lastUsed);
+        lastUsed.set(p.path, p.lastUsed);
+    }
+    for (const p of disk) {
+        if (!firstAdded.has(p.path))
+            firstAdded.set(p.path, p.firstAdded);
+        lastUsed.set(p.path, Math.max(lastUsed.get(p.path) ?? 0, p.lastUsed));
+    }
+    const byPath = new Map(disk.map((p) => [p.path, p]));
+    return [...firstAdded.entries()]
+        .filter(([path]) => !removed.has(path))
+        .map(([path, added]) => ({
+        path,
+        firstAdded: added,
+        lastUsed: lastUsed.get(path) ?? 0,
+        lastConversationAt: byPath.get(path)?.lastUsed,
+        conversationCount: byPath.get(path)?.conversationCount ?? 0,
+    }))
+        .sort((a, b) => b.lastUsed - a.lastUsed || b.firstAdded - a.firstAdded)
+        .slice(0, 20);
+}
+/**
+ * Persists which workspace each browser client last used + which workspaces it
+ * has opened, so a server restart / page reload restores the same project and
+ * the UI can offer a one-click recent-project list. File I/O is best-effort:
+ * persistence problems must never crash the server or block a session.
+ */
+export class ClientStateStore {
+    filePath;
+    cache = null;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    load() {
+        if (this.cache)
+            return this.cache;
+        try {
+            const parsed = JSON.parse(readFileSync(this.filePath, "utf8"));
+            this.cache = parsed && typeof parsed === "object" ? parsed : {};
+        }
+        catch {
+            this.cache = {};
+        }
+        return this.cache;
+    }
+    /** Get or create a client's entry and stamp it as recently used. */
+    entry(clientId) {
+        const all = this.load();
+        const state = (all[clientId] ??= { projects: [] });
+        state.seen = Date.now();
+        return state;
+    }
+    /** Browser tabs are a new clientId each; keep the file bounded by dropping the
+     *  least recently used entries (the desktop app's stable id stays near the top). */
+    prune() {
+        const all = this.cache;
+        if (!all)
+            return;
+        const ids = Object.keys(all);
+        if (ids.length <= MAX_CLIENT_ENTRIES)
+            return;
+        const lastSeen = (state) => state.seen ?? Math.max(0, ...(state.projects ?? []).map((p) => p.lastUsed));
+        ids.sort((a, b) => lastSeen(all[b]) - lastSeen(all[a]));
+        for (const id of ids.slice(MAX_CLIENT_ENTRIES))
+            delete all[id];
+    }
+    save() {
+        this.prune();
+        try {
+            // Atomic write (tmp + rename): a crash mid-write must never leave a
+            // half-written JSON — that would wipe ALL persisted state (recent
+            // projects and display settings) on next load. 0600: it lists the
+            // user's project paths.
+            writeFileAtomic(this.filePath, JSON.stringify(this.cache, null, 2) + "\n");
+        }
+        catch {
+            // best effort
+        }
+    }
+    get(clientId) {
+        return this.load()[clientId] ?? { projects: [] };
+    }
+    /** Freeze the order anchors of projects discovered from old session files as
+     *  soon as they are shown. Selecting one later must not make it "new". */
+    rememberDisplayedProjects(clientId, projects) {
+        const state = this.entry(clientId);
+        const known = new Set(state.projects.map((p) => p.path));
+        let changed = false;
+        for (const project of projects) {
+            if (known.has(project.path))
+                continue;
+            state.projects.push({ path: project.path, lastUsed: project.lastUsed, firstAdded: project.firstAdded });
+            known.add(project.path);
+            changed = true;
+        }
+        if (changed) {
+            state.projects.sort((a, b) => b.lastUsed - a.lastUsed || (b.firstAdded ?? 0) - (a.firstAdded ?? 0));
+            state.projects = state.projects.slice(0, 30);
+            this.save();
+        }
+    }
+    /** Remember which workspace a client last used and move it to the front. */
+    remember(clientId, cwd) {
+        const state = this.entry(clientId);
+        state.lastCwd = cwd;
+        // Distinct clicks can share one millisecond; keep ordering deterministic.
+        const now = Math.max(Date.now(), ...state.projects.map((project) => project.lastUsed + 1));
+        const existing = state.projects.find((p) => p.path === cwd);
+        if (existing) {
+            // Keep the historical first-added value as a deterministic tie-breaker.
+            existing.firstAdded ??= existing.lastUsed;
+            existing.lastUsed = now;
+        }
+        else {
+            state.projects.push({ path: cwd, lastUsed: now, firstAdded: now });
+        }
+        state.projects.sort((a, b) => b.lastUsed - a.lastUsed || (b.firstAdded ?? 0) - (a.firstAdded ?? 0));
+        state.projects = state.projects.slice(0, 30);
+        // Opening the workspace again clears its removal tombstone.
+        if (state.removedProjects?.length) {
+            state.removedProjects = state.removedProjects.filter((p) => p !== cwd);
+        }
+        this.save();
+    }
+    /** Drop one workspace from the recent-project list (user-requested removal).
+     *  Records a tombstone too: pushProjects() re-discovers cwds from session
+     *  files on every listing, so without it the entry would instantly reappear. */
+    removeProject(clientId, cwd) {
+        const state = this.entry(clientId);
+        state.projects = state.projects.filter((p) => p.path !== cwd);
+        if (state.lastCwd === cwd)
+            delete state.lastCwd;
+        const removed = new Set(state.removedProjects ?? []);
+        removed.add(cwd);
+        state.removedProjects = [...removed];
+        this.save();
+    }
+    /** Tombstoned projects (explicitly removed by the user) for filtering the
+     *  merged recent-project list. */
+    getRemovedProjects(clientId) {
+        return this.load()[clientId]?.removedProjects ?? [];
+    }
+    /** Remember conversations that were still streaming at shutdown (best-
+     *  effort; called during the graceful-shutdown path). */
+    saveInterrupted(clientId, list) {
+        if (list.length === 0)
+            return;
+        const state = this.entry(clientId);
+        state.interrupted = list.slice(0, 8);
+        this.save();
+    }
+    /** Consume the interrupted-conversation record (returns and clears it) —
+     *  called once on the client's first attach after a restart. */
+    takeInterrupted(clientId) {
+        const all = this.load();
+        const state = all[clientId];
+        const list = state?.interrupted;
+        if (list?.length && state) {
+            delete state.interrupted;
+            this.save();
+        }
+        return list;
+    }
+    /** Last-used settings-panel state for a client, or defaults. */
+    getSettings(clientId) {
+        const settings = this.load()[clientId]?.settings;
+        return { editResendNewSession: settings?.editResendNewSession ?? false, thinkingWrap: settings?.thinkingWrap ?? false, toolsWrap: settings?.toolsWrap ?? true, disabledPlugins: settings?.disabledPlugins ?? [] };
+    }
+    /** Persist the client's settings-panel state (partial merge). */
+    saveSettings(clientId, partial) {
+        const state = this.entry(clientId);
+        const current = this.getSettings(clientId);
+        state.settings = { editResendNewSession: partial.editResendNewSession ?? current.editResendNewSession ?? false, thinkingWrap: partial.thinkingWrap ?? current.thinkingWrap, toolsWrap: partial.toolsWrap ?? current.toolsWrap, disabledPlugins: partial.disabledPlugins ?? current.disabledPlugins };
+        this.save();
+    }
+}

package/dist/server/codemode-image-routes.js

@@ -0,0 +1,36 @@
+import { realpathSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { sniffImageMime } from "./text-sniff.js";
+/** A user save, separate from agent tools/context; only new files in the active workspace. */
+export function installCodemodeImageRoutes(app, service, originAllowed) {
+    app.post("/api/codemode-image", (req, res) => {
+        res.setHeader("Cache-Control", "no-store");
+        if (!originAllowed(req) || !req.is("application/json")) {
+            res.sendStatus(403);
+            return;
+        }
+        const { clientId, cwd, dataUrl } = req.body ?? {};
+        const cs = typeof clientId === "string" ? service().get(clientId) : undefined;
+        if (!cs || cs.switchingWorkspace || cs.cwd !== cwd || service().quiesceInfo().quiesced) {
+            res.status(409).json({ error: "Workspace unavailable" });
+            return;
+        }
+        try {
+            if (typeof dataUrl !== "string" || dataUrl.length > 9 * 1024 * 1024)
+                throw new Error("Image exceeds save limit (6 MB)");
+            const match = /^data:image\/(png|jpeg|gif|webp);base64,([A-Za-z0-9+/]+={0,2})$/.exec(dataUrl);
+            if (!match)
+                throw new Error("Invalid image data");
+            const buffer = Buffer.from(match[2], "base64");
+            if (buffer.length > 6 * 1024 * 1024 || sniffImageMime(buffer, "") !== `image/${match[1]}`)
+                throw new Error("Invalid image format or size");
+            const path = `codemode-${randomUUID()}.${match[1] === "jpeg" ? "jpg" : match[1]}`;
+            writeFileSync(join(realpathSync(cwd), path), buffer, { flag: "wx", mode: 0o600 });
+            res.json({ path });
+        }
+        catch (error) {
+            res.status(400).json({ error: error.message });
+        }
+    });
+}

package/dist/server/codemode-presentation.js

@@ -0,0 +1,19 @@
+/** Allowlist native renderer details; never forward arbitrary extension metadata. */
+export function codemodeDetails(value) {
+    if (!value || typeof value !== "object" || !Array.isArray(value.calls))
+        return;
+    const raw = value;
+    const calls = [];
+    for (const item of raw.calls.slice(0, 256)) {
+        if (!item || typeof item !== "object")
+            continue;
+        const call = item;
+        if (typeof call.id !== "string" || typeof call.name !== "string" || !["running", "ok", "error", "cancelled"].includes(String(call.status)))
+            continue;
+        calls.push({ id: call.id.slice(0, 500), name: call.name.slice(0, 300), args: typeof call.args === "string" ? call.args.slice(0, 4000) : "", status: call.status,
+            ...(typeof call.durationMs === "number" && Number.isFinite(call.durationMs) && call.durationMs >= 0 ? { durationMs: call.durationMs } : {}),
+            ...(typeof call.cost === "number" && Number.isFinite(call.cost) && call.cost >= 0 ? { cost: call.cost } : {}),
+            ...(typeof call.error === "string" ? { error: call.error.slice(0, 4000) } : {}), });
+    }
+    return { calls, totalCalls: raw.calls.length, ...(typeof raw.fullOutputPath === "string" ? { fullOutputPath: raw.fullOutputPath.slice(0, 4096) } : {}) };
+}

package/dist/server/component-updates.js

@@ -0,0 +1,135 @@
+import { execFile } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { DefaultPackageManager, VERSION } from "@earendil-works/pi-coding-agent";
+import { extensionDisplay } from "./extension-display.js";
+let restartRequired = false;
+export const componentRestartRequired = () => restartRequired;
+export function markComponentUpdated() { restartRequired = true; }
+const npmSource = /^npm:((?:@[a-z0-9._-]+\/)?[a-z0-9._-]+)(?:@([^\s]+))?$/i;
+function packageInfo(directory) {
+    try {
+        const value = JSON.parse(readFileSync(join(directory, "package.json"), "utf8"));
+        return { name: typeof value?.name === "string" ? value.name : undefined, version: typeof value?.version === "string" ? value.version : undefined };
+    }
+    catch {
+        return {};
+    }
+}
+export function packageManagerFor(session, cwd, agentDir) {
+    return new DefaultPackageManager({ cwd, agentDir, settingsManager: session.settingsManager });
+}
+export function updateTargets(session, manager) {
+    const targets = [
+        { id: "builtin:agent", name: "pi Agent", current: VERSION, kind: "bundled", packageName: "@earendil-works/pi-coding-agent" },
+    ];
+    const packages = manager.listConfiguredPackages();
+    for (const pkg of packages) {
+        const parsed = npmSource.exec(pkg.source);
+        const metadata = pkg.installedPath ? packageInfo(pkg.installedPath) : {};
+        const git = /^(?:git:|https?:\/\/|git@|ssh:\/\/)/.test(pkg.source);
+        targets.push({ id: `${pkg.scope}:${pkg.source}`, name: parsed?.[1] ?? metadata.name ?? pkg.source, source: pkg.source, scope: pkg.scope, directory: pkg.installedPath, kind: parsed && ["@youweichen/pi-harness", "pi-harness"].includes(parsed[1]) ? "bundled" : parsed ? "npm" : git ? "git" : "local", packageName: parsed?.[1], current: metadata.version ?? null, ambiguous: packages.filter((other) => parsed ? npmSource.exec(other.source)?.[1] === parsed[1] : other.source === pkg.source).length > 1, pinned: parsed ? !!parsed[2] : git && pkg.source.includes("#") });
+    }
+    const roots = packages.flatMap((pkg) => pkg.installedPath ? [pkg.installedPath.replaceAll("\\", "/").replace(/\/$/, "") + "/"] : []);
+    for (const extension of session.resourceLoader.getExtensions().extensions) {
+        if (extension.hidden || extension.resolvedPath.startsWith("builtin:"))
+            continue;
+        const path = extension.resolvedPath;
+        if (roots.some((root) => path.replaceAll("\\", "/").startsWith(root)))
+            continue;
+        targets.push({ id: `local:${path}`, name: extensionDisplay(path).name, current: null, kind: "local" });
+    }
+    return targets;
+}
+const parseVersion = (value) => /^(\d+)\.(\d+)\.(\d+)(-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.exec(value);
+/** Only stable registry releases are offered; prerelease builds are not silently selected. */
+export function hasNewerStableVersion(current, latest) {
+    const a = parseVersion(current), b = parseVersion(latest);
+    if (!a || !b || b[4])
+        return false;
+    for (let i = 1; i <= 3; i++)
+        if (Number(a[i]) !== Number(b[i]))
+            return Number(b[i]) > Number(a[i]);
+    return !!a[4];
+}
+const registryCache = new Map();
+export async function latestNpmVersion(name) {
+    const cached = registryCache.get(name);
+    if (cached && cached.until > Date.now())
+        return cached.promise;
+    const promise = (async () => {
+        const response = await fetch(`https://registry.npmjs.org/${encodeURIComponent(name)}/latest`, { signal: AbortSignal.timeout(8000) });
+        if (!response.ok)
+            throw Error(`HTTP ${response.status}`);
+        const data = await response.json();
+        if (typeof data.version !== "string" || !/^\d+\.\d+\.\d+(?:[-+][\w.-]+)?$/.test(data.version))
+            throw Error("Invalid registry version");
+        return data.version;
+    })();
+    registryCache.set(name, { until: Date.now() + 300_000, promise });
+    if (registryCache.size > 256)
+        registryCache.delete(registryCache.keys().next().value);
+    try {
+        return await promise;
+    }
+    catch (error) {
+        registryCache.delete(name);
+        throw error;
+    }
+}
+export const gitOutput = (cwd, args) => new Promise((resolve, reject) => {
+    execFile("git", args, { cwd, timeout: 8000, maxBuffer: 1024 * 1024, windowsHide: true, env: { ...process.env, GIT_TERMINAL_PROMPT: "0" } }, (error, stdout) => error ? reject(Error("Git update check failed")) : resolve(stdout.trim()));
+});
+export async function checkComponent(target, npm = latestNpmVersion, git = gitOutput) {
+    const result = { id: target.id, name: target.name, current: target.current, latest: null, kind: target.kind, scope: target.scope, status: "manual", canUpdate: false };
+    try {
+        if (target.kind === "local")
+            return result;
+        if (target.kind === "git") {
+            if (!target.directory)
+                throw Error("Package not installed");
+            result.current = (await git(target.directory, ["rev-parse", "HEAD"])).slice(0, 12);
+            if (target.pinned)
+                return { ...result, status: "pinned" };
+            const upstream = await git(target.directory, ["rev-parse", "--abbrev-ref", "@{upstream}"]).catch(() => "");
+            const ref = upstream.startsWith("origin/") ? `refs/heads/${upstream.slice(7)}` : "HEAD";
+            const remote = await git(target.directory, ["ls-remote", "origin", ref]);
+            const sha = /^([0-9a-f]{40,64})\s/m.exec(remote)?.[1];
+            if (!sha)
+                throw Error("Remote version unavailable");
+            result.latest = sha.slice(0, 12);
+        }
+        else {
+            if (!target.packageName)
+                throw Error("Package name unavailable");
+            result.latest = await npm(target.packageName);
+        }
+        const comparable = !!result.current && (target.kind === "git" || !!parseVersion(result.current) && !!parseVersion(result.latest) && !parseVersion(result.latest)[4]);
+        const available = comparable && (target.kind === "git" ? result.current !== result.latest : hasNewerStableVersion(result.current, result.latest));
+        return { ...result, status: target.ambiguous ? "manual" : target.pinned ? "pinned" : !comparable ? "unknown" : available ? "available" : "current", canUpdate: available && !target.pinned && !target.ambiguous && target.kind !== "bundled" };
+    }
+    catch (error) {
+        return { ...result, status: "error", error: error instanceof Error ? error.message : "Check failed" };
+    }
+}
+export async function checkComponents(targets) {
+    const results = [];
+    // Keep registry/git concurrency bounded for installations with many extensions.
+    for (let i = 0; i < targets.length; i += 4)
+        results.push(...await Promise.all(targets.slice(i, i + 4).map((target) => checkComponent(target))));
+    return results;
+}
+/** Resolve updates from the server catalog, never a client-supplied package spec. */
+export async function updateComponentPackage(targets, id, update, check = checkComponent, git = gitOutput) {
+    const target = targets.find((entry) => entry.id === id);
+    if (!target?.source || target.kind === "bundled" || target.kind === "local" || target.pinned)
+        throw Error("该组件需要随应用升级或手动维护");
+    if (target.ambiguous)
+        throw Error("同一来源安装在多个范围，请按范围手动更新");
+    if (!(await check(target)).canUpdate)
+        throw Error("没有可安装的更新，请重新检查");
+    if (target.kind === "git" && target.directory && await git(target.directory, ["status", "--porcelain"]))
+        throw Error("扩展目录有本地改动，请先保存或提交后再更新");
+    await update(target.source);
+    markComponentUpdated();
+}

package/dist/server/context-breakdown.js

@@ -0,0 +1,56 @@
+/** Provider APIs report one context total, not a breakdown by content origin.
+ * Allocate that total using the SDK's chars/4 heuristic (images ≈1200 tokens).
+ * The UI must label these four values as estimates. */
+export function estimateContextParts(messages, systemPrompt, totalTokens) {
+    if (totalTokens === null || !Number.isFinite(totalTokens) || totalTokens < 0)
+        return null;
+    const raw = { system: systemPrompt.length / 4, tools: 0, conversation: 0, attachments: 0 };
+    const content = (value, category) => {
+        if (typeof value === "string") {
+            raw[category] += value.length / 4;
+            return;
+        }
+        if (!Array.isArray(value))
+            return;
+        for (const block of value) {
+            if (!block || typeof block !== "object")
+                continue;
+            if (block.type === "image") {
+                raw.attachments += 1200;
+                continue;
+            }
+            if (block.type === "toolCall") {
+                raw.tools += (String(block.name ?? "").length + JSON.stringify(block.arguments ?? {}).length) / 4;
+                continue;
+            }
+            if (typeof block.text === "string")
+                raw[category] += block.text.length / 4;
+            if (typeof block.thinking === "string")
+                raw[category] += block.thinking.length / 4;
+        }
+    };
+    for (const message of messages) {
+        if (message.role === "assistant" || message.role === "user")
+            content(message.content, "conversation");
+        else if (message.role === "toolResult" || message.role === "custom")
+            content(message.content, "tools");
+        else if (message.role === "bashExecution")
+            raw.tools += (message.command.length + message.output.length) / 4;
+        else if (message.role === "branchSummary" || message.role === "compactionSummary")
+            raw.conversation += message.summary.length / 4;
+    }
+    const keys = ["system", "tools", "conversation", "attachments"];
+    const rawTotal = keys.reduce((sum, key) => sum + raw[key], 0);
+    if (rawTotal <= 0)
+        return { system: 0, tools: 0, conversation: Math.round(totalTokens), attachments: 0 };
+    const target = Math.round(totalTokens);
+    const exact = keys.map((key) => raw[key] * target / rawTotal);
+    const values = exact.map(Math.floor);
+    let remaining = target - values.reduce((sum, value) => sum + value, 0);
+    for (const index of keys.map((_, index) => index).sort((a, b) => exact[b] % 1 - exact[a] % 1)) {
+        if (remaining-- <= 0)
+            break;
+        values[index]++;
+    }
+    return { system: values[0], tools: values[1], conversation: values[2], attachments: values[3] };
+}