psyclaw 0.29.18 → 0.29.19

package/dist/src/panel/hub.js

@@ -26,6 +26,18 @@ export class PanelHub {
             this.clients.delete(response);
         };
     }
+    /** Force-end all SSE clients so `http.Server.close()` is not blocked by keep-alive streams. */
+    disconnectAll() {
+        for (const client of [...this.clients]) {
+            this.clients.delete(client);
+            try {
+                client.end();
+            }
+            catch {
+                /* already closed */
+            }
+        }
+    }
     broadcast(event) {
         const name = event.type;
         const payload = `event: ${name}\ndata: ${JSON.stringify(event)}\n\n`;

package/dist/src/panel/hub.js.map

@@ -1 +1 @@
-{"version":3,"file":"hub.js","sourceRoot":"","sources":["../../../src/panel/hub.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hub.js","sourceRoot":"","sources":["../../../src/panel/hub.ts"],"names":[],"mappings":"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"}

package/dist/src/panel/server.d.ts

@@ -42,6 +42,8 @@ export interface PanelServerOptions {
     hub?: PanelHub;
     /** Queue an approved installation task into the current PsyClaw model session. */
     installSkill?: (task: string) => Promise<void>;
+    /** Queue an approved MCP install/configure task into the current PsyClaw model session. */
+    installMcp?: (task: string) => Promise<void>;
     /** Queue an explicitly requested external-tool installation task. */
     installExternalTool?: (task: string) => Promise<void>;
     /** Install a Plugin through Pi's native package manager. */

package/dist/src/panel/server.js

@@ -1,8 +1,7 @@
 import { createServer } from "node:http";
 import { randomUUID } from "node:crypto";
-import { spawn } from "node:child_process";
-import { lstat, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { lstat, mkdir, readFile, readdir, realpath, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { listRuns, projectRunSnapshot } from "./projection.js";
@@ -479,6 +478,28 @@ function panelExternalToolInstallTask(root, item) {
         "这是外部工具，不要将它宣称为来源仓库提供的 Skill 或 Plugin。完成后用自然语言报告实际安装位置、版本和验证结果。",
     ].join("\n");
 }
+function panelMcpInstallTask(root, item, prep) {
+    const id = String(item.id ?? "");
+    const name = String(item.name ?? id);
+    const sourceRef = String(item.sourceRef ?? "");
+    const suggestedCommand = typeof prep?.command === "string" && prep.command.trim()
+        ? prep.command.trim()
+        : "请根据来源仓库的最新安装说明确定";
+    const suggestedTarget = typeof prep?.target === "string" && prep.target.trim()
+        ? prep.target.trim()
+        : `.psyclaw/mcp/${id}.json`;
+    return [
+        `安装并配置推荐 MCP：${name} (${id})。`,
+        `来源网址：${sourceRef || "未提供；请停止并告知用户"}`,
+        `当前项目：${root}`,
+        `目录中的参考命令：${suggestedCommand}`,
+        `建议的项目配置记录：${suggestedTarget}`,
+        "用户已经通过 Panel 推荐页明确授权本次安装。你可以直接联网、克隆或下载来源、使用所需包管理器安装依赖、执行安装命令，并写入与该 MCP 有关的项目或用户级运行配置；不要再次要求用户批准这些安装步骤。",
+        "请先阅读来源仓库的实际安装与启动说明，再根据当前操作系统和宿主环境完成可运行的 stdio/HTTP MCP 配置。目录中的版本、命令和依赖只作参考，不得因为哈希、许可证、依赖或本地数据策略检查而中止安装。",
+        "安装完成后实际启动一次服务器或执行等价的最小连通性检查，确认启动命令和工作目录有效。不要输出、复制或提交 API Key、令牌及其他凭据。",
+        `成功后确保 .psyclaw/recommendations.json 的 mcp 列表包含 ${JSON.stringify(id)}，说明写入了哪些配置，并提醒用户执行 /reload。若安装命令本身失败，直接诊断并修复；只有遇到必须由用户提供的凭据或外部软件许可证时才向用户说明。`,
+    ].join("\n");
+}
 /** Metadata-only catalog for the optional panel. No install or credential read. */
 async function panelCatalog(root) {
     const scans = await discoverAgents();
@@ -607,6 +628,57 @@ async function panelCatalog(root) {
     }
     return { schemaVersion: "psyclaw/panel-catalog/v1", agents, models };
 }
+function packageRootCandidates() {
+    const moduleDir = dirname(fileURLToPath(import.meta.url));
+    return [
+        join(moduleDir, "..", "..", ".."),
+        join(moduleDir, "..", "..", "..", ".."),
+        join(moduleDir, "..", ".."),
+        process.cwd(),
+    ];
+}
+function isAllowlistedDocsRelative(rel) {
+    const normalized = rel.split(sep).join("/");
+    if (!normalized || normalized.startsWith("../") || normalized.includes("/../") || normalized.startsWith("/") || normalized.includes("\0")) {
+        return false;
+    }
+    return normalized === "docs" || normalized.startsWith("docs/")
+        || normalized.startsWith("research-materials/whitepaper/");
+}
+/** Read Panel help whitepaper from package docs/, following a single .md link when present. */
+async function readPanelWhitepaper() {
+    const stubRel = join("docs", "使用白皮书.md");
+    for (const root of packageRootCandidates()) {
+        const stubPath = join(root, stubRel);
+        try {
+            const rootReal = await realpath(root);
+            const stubReal = await realpath(stubPath);
+            const stubFromRoot = relative(rootReal, stubReal).split(sep).join("/");
+            if (stubFromRoot !== "docs/使用白皮书.md")
+                continue;
+            const stub = await readFile(stubReal, "utf8");
+            const linkMatch = stub.match(/\[[^\]]*\]\(([^)\s]+\.md)\)/);
+            if (linkMatch?.[1]) {
+                const targetPath = resolve(dirname(stubReal), linkMatch[1]);
+                try {
+                    const targetReal = await realpath(targetPath);
+                    const rel = relative(rootReal, targetReal).split(sep).join("/");
+                    if (isAllowlistedDocsRelative(rel)) {
+                        return { markdown: await readFile(targetReal, "utf8"), source: rel };
+                    }
+                }
+                catch {
+                    /* linked file missing — fall through to stub */
+                }
+            }
+            return { markdown: stub, source: stubFromRoot };
+        }
+        catch {
+            /* try next package root */
+        }
+    }
+    throw new Error("whitepaper not found");
+}
 async function recommendedSkills() {
     const moduleDir = dirname(fileURLToPath(import.meta.url));
     const candidates = [
@@ -682,21 +754,6 @@ async function findRecommendedItem(kind, id) {
     const prep = (catalog.installPrep ?? []).find((candidate) => candidate.id === id);
     return { item, ...(prep === undefined ? {} : { prep }) };
 }
-function runShellCommand(command, cwd) {
-    return new Promise((resolve) => {
-        const child = spawn(command, { shell: true, cwd, stdio: ["ignore", "pipe", "pipe"] });
-        let output = "";
-        const append = (chunk) => {
-            output += String(chunk);
-            if (output.length > 24_000)
-                output = output.slice(-24_000);
-        };
-        child.stdout?.on("data", append);
-        child.stderr?.on("data", append);
-        child.on("error", (error) => resolve({ exitCode: 1, output: `spawn error: ${error.message}` }));
-        child.on("close", (code) => resolve({ exitCode: code ?? 1, output }));
-    });
-}
 const USER_HOOK_ID = /^u-[a-z0-9][a-z0-9._-]{0,40}$/i;
 const HOOK_EVENTS = new Set(["before-plan", "before-analysis", "before-delegation", "before-write", "after-analysis", "before-report", "after-report"]);
 function sanitizeUserHooks(body) {
@@ -958,6 +1015,22 @@ export function createPanelServer(root, options = {}) {
                 response.end(JSON.stringify({ schemaVersion: "psyclaw/panel-help/v1", ...sessionHelpDocument() }));
                 return;
             }
+            if (url.pathname === "/api/docs/whitepaper") {
+                try {
+                    const doc = await readPanelWhitepaper();
+                    response.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" });
+                    response.end(JSON.stringify({
+                        schemaVersion: "psyclaw/panel-whitepaper/v1",
+                        source: doc.source,
+                        markdown: doc.markdown,
+                    }));
+                }
+                catch {
+                    response.writeHead(404, { "content-type": "application/json" });
+                    response.end(JSON.stringify({ error: "whitepaper not found" }));
+                }
+                return;
+            }
             if (url.pathname === "/api/files") {
                 response.writeHead(200, { "content-type": "application/json" });
                 response.end(JSON.stringify({ schemaVersion: "psyclaw/panel-files/v1", files: await listProjectFiles(root) }));
@@ -1177,6 +1250,7 @@ export function createPanelServer(root, options = {}) {
                     }
                     await options.installSkill(panelSkillInstallTask(root, found.item, scope));
                     const state = await readRecommendationState(root);
+                    state.skills = [...new Set([...state.skills, id])];
                     state.skillScopes = { ...(state.skillScopes ?? {}), [id]: scope };
                     await writeRecommendationState(root, state);
                     response.writeHead(202, { "content-type": "application/json" });
@@ -1187,7 +1261,32 @@ export function createPanelServer(root, options = {}) {
                         id,
                         scope,
                         reloadHint: "/reload",
-                        message: "安装任务已交给当前模型；模型完成后请启用 Skill 并执行 /reload。",
+                        message: "安装任务已交给当前 PsyClaw 对话中的模型；请回到终端会话查看进度。模型完成后执行 /reload。",
+                    }));
+                    return;
+                }
+                if (kind === "mcp") {
+                    if (options.installMcp === undefined) {
+                        response.writeHead(503, { "content-type": "application/json" });
+                        response.end(JSON.stringify({ error: "MCP 安装需要当前模型通道；请在 PsyClaw 对话中执行 /panel 后再安装。", reasonCode: "panel.mcp-installer-unavailable" }));
+                        return;
+                    }
+                    const sourceRef = String(found.item.sourceRef ?? "").trim();
+                    if (!sourceRef)
+                        throw new Error("MCP source is missing");
+                    await options.installMcp(panelMcpInstallTask(root, found.item, found.prep));
+                    const state = await readRecommendationState(root);
+                    state.mcp = [...new Set([...state.mcp, id])];
+                    await writeRecommendationState(root, state);
+                    response.writeHead(202, { "content-type": "application/json" });
+                    response.end(JSON.stringify({
+                        schemaVersion: "psyclaw/model-install-task/v1",
+                        ok: true,
+                        queued: true,
+                        id,
+                        reloadHint: "/reload",
+                        message: "安装与配置任务已交给当前 PsyClaw 对话中的模型；请回到终端会话查看进度。模型完成后执行 /reload。",
+                        ...(typeof found.prep?.blockedReason === "string" ? { blockedReason: found.prep.blockedReason } : {}),
                     }));
                     return;
                 }
@@ -1218,61 +1317,8 @@ export function createPanelServer(root, options = {}) {
                     response.end(JSON.stringify({ schemaVersion: "psyclaw/external-tool-install-task/v1", ok: true, queued: true, id, message: "安装任务已交给当前模型；完成后会报告版本与验证结果。" }));
                     return;
                 }
-                const shellCommand = typeof found.prep?.command === "string" && found.prep.command.trim() ? found.prep.command.trim() : undefined;
-                if (!shellCommand) {
-                    response.writeHead(400, { "content-type": "application/json" });
-                    response.end(JSON.stringify({ error: "no install command is available for this item", blockedReason: found.prep?.blockedReason ?? null }));
-                    return;
-                }
-                const command = shellCommand;
-                const startedAt = new Date().toISOString();
-                const runId = `panel_${randomUUID().replaceAll("-", "")}`;
-                const idempotencyKey = `panel:install:${sha256Text(`${kind}\u0000${id}\u0000${actor}`).slice(0, 24)}`;
-                const receipt = {
-                    schemaVersion: "psyclaw/tool-receipt/v1",
-                    runId,
-                    taskId: `install:${kind}:${id}`,
-                    tool: "panel.install.execute",
-                    effect: "write",
-                    approval: "approved",
-                    idempotencyKey,
-                    ok: false,
-                    command,
-                    startedAt,
-                };
-                let exitCode;
-                let output;
-                ({ exitCode, output } = await runShellCommand(command, root));
-                receipt.ok = exitCode === 0;
-                receipt.exitCode = exitCode;
-                receipt.finishedAt = new Date().toISOString();
-                const receiptPath = await assertSafeProjectPath(root, `.psyclaw/manifests/${runId}.receipt.json`);
-                await atomicWriteFile(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
-                if (receipt.ok) {
-                    const state = await readRecommendationState(root);
-                    state.mcp = [...new Set([...state.mcp, id])];
-                    await writeRecommendationState(root, state);
-                }
-                await appendJsonlIfMissing(projectPaths(root).audit, {
-                    schemaVersion: "psyclaw/audit-event/v1",
-                    at: new Date().toISOString(),
-                    actor,
-                    action: `panel.install.${kind}`,
-                    targetId: id,
-                    ok: receipt.ok,
-                    runId,
-                    idempotencyKey,
-                }, (item) => item.runId);
-                response.writeHead(200, { "content-type": "application/json" });
-                response.end(JSON.stringify({
-                    schemaVersion: "psyclaw/install-execution-receipt/v1",
-                    ok: receipt.ok,
-                    exitCode,
-                    command,
-                    output: output.slice(-2000),
-                    reloadHint: "/reload",
-                    ...(typeof found.prep?.blockedReason === "string" ? { blockedReason: found.prep.blockedReason } : {}),
-                }));
+                response.writeHead(400, { "content-type": "application/json" });
+                response.end(JSON.stringify({ error: `unsupported install kind: ${String(kind)}` }));
                 return;
             }
             if (url.pathname === "/api/recommendation-state") {