pi-web-ui 0.22.1 → 0.24.0

package/dist/server/control-socket.js

@@ -0,0 +1,177 @@
+/**
+ * Local control socket for the pi-web-ui server.
+ *
+ * Lets the CLI (and humans) query status and quiesce/unquiesce the server
+ * WITHOUT opening a network port or exposing an unauthenticated HTTP
+ * endpoint. Only the local OS user can reach it:
+ *   - POSIX: a mode-0600 Unix domain socket at <dataDir>/pi-web-ui.sock
+ *   - Windows: a named pipe  \\.\pipe\pi-web-ui-<port>
+ *
+ * Protocol: one JSON object per line.
+ *   → {"cmd":"status"}        ← {"ok":true, ...serviceStatus}
+ *   → {"cmd":"quiesce"}       ← {"ok":true}
+ *   → {"cmd":"unquiesce"}     ← {"ok":true}
+ *   → anything else           ← {"ok":false,"error":"..."}
+ *
+ * Idle connections are closed after a short timeout so a stuck CLI never
+ * holds the socket.
+ */
+import { createServer, createConnection } from "node:net";
+import { chmodSync, existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+/** How long a control connection may sit idle before the server closes it. */
+const CONTROL_IDLE_TIMEOUT_MS = 5_000;
+/** How long the CLI waits for a reply before giving up. */
+const CONTROL_CLIENT_TIMEOUT_MS = 3_000;
+/** Socket path (POSIX) or pipe name (Windows). */
+export function controlPath(dataDir, port) {
+    return process.platform === "win32"
+        ? `\\\\.\\pipe\\pi-web-ui-${port}`
+        : join(dataDir, "pi-web-ui.sock");
+}
+/** Start the control socket; returns a stop function. */
+export function startControlServer(opts) {
+    const { service, dataDir, port } = opts;
+    const path = controlPath(dataDir, port);
+    let server;
+    let stop = false;
+    if (process.platform === "win32") {
+        server = createServer(handleConnection);
+    }
+    else {
+        // Remove a stale socket left by a previous crash (only if it's ours —
+        // an existing socket file that refuses connections is stale).
+        if (existsSync(path)) {
+            try {
+                rmSync(path);
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+        server = createServer(handleConnection);
+    }
+    // A second instance on the same data dir / port would fail to bind — don't
+    // crash the server over it, just log and run without a control socket.
+    server.on("error", (err) => {
+        if (err.code === "EADDRINUSE") {
+            console.warn(`[control] socket ${path} already in use — control socket disabled`);
+        }
+        else {
+            console.warn(`[control] socket error: ${err.message}`);
+        }
+    });
+    function handleConnection(sock) {
+        let buf = "";
+        const timer = setTimeout(() => {
+            sock.destroy();
+        }, CONTROL_IDLE_TIMEOUT_MS);
+        sock.on("data", (chunk) => {
+            buf += chunk.toString("utf8");
+            let nl;
+            while ((nl = buf.indexOf("\n")) >= 0) {
+                const line = buf.slice(0, nl).trim();
+                buf = buf.slice(nl + 1);
+                if (!line)
+                    continue;
+                timer.refresh();
+                let req;
+                try {
+                    req = JSON.parse(line);
+                }
+                catch {
+                    sock.write(JSON.stringify({ ok: false, error: "bad json" }) + "\n");
+                    continue;
+                }
+                let resp;
+                switch (req.cmd) {
+                    case "status":
+                        resp = { ok: true, ...service.serviceStatus() };
+                        break;
+                    case "quiesce":
+                        service.quiesce();
+                        resp = { ok: true };
+                        break;
+                    case "unquiesce":
+                        service.unquiesce();
+                        resp = { ok: true };
+                        break;
+                    default:
+                        resp = { ok: false, error: `unknown cmd: ${String(req.cmd)}` };
+                        break;
+                }
+                sock.write(JSON.stringify(resp) + "\n");
+            }
+        });
+        sock.on("error", () => {
+            /* client vanished */
+        });
+        sock.on("close", () => clearTimeout(timer));
+    }
+    if (process.platform === "win32") {
+        // net.Server on a named pipe: listen on the pipe name directly.
+        server.listen(path, () => {
+            console.log(`  control    : ${path}`);
+        });
+    }
+    else {
+        server.listen(path, () => {
+            try {
+                chmodSync(path, 0o600);
+            }
+            catch {
+                /* best-effort */
+            }
+            console.log(`  control    : ${path}`);
+        });
+    }
+    return () => {
+        stop = true;
+        server.close();
+        try {
+            if (process.platform !== "win32" && existsSync(path))
+                rmSync(path);
+        }
+        catch {
+            /* best-effort */
+        }
+    };
+}
+/**
+ * CLI-side client: send one command and return the parsed reply (or null if
+ * the server is unreachable / timed out).
+ */
+export function sendControlCommand(dataDir, port, cmd) {
+    const path = controlPath(dataDir, port);
+    return new Promise((resolve) => {
+        const sock = createConnection(path);
+        let done = false;
+        const finish = (v) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            sock.destroy();
+            resolve(v);
+        };
+        const timer = setTimeout(() => finish(null), CONTROL_CLIENT_TIMEOUT_MS);
+        let buf = "";
+        sock.on("connect", () => {
+            sock.write(JSON.stringify({ cmd }) + "\n");
+        });
+        sock.on("data", (chunk) => {
+            buf += chunk.toString("utf8");
+            const nl = buf.indexOf("\n");
+            if (nl >= 0) {
+                try {
+                    finish(JSON.parse(buf.slice(0, nl)));
+                }
+                catch {
+                    finish(null);
+                }
+            }
+        });
+        sock.on("error", () => finish(null));
+        sock.on("close", () => finish(null));
+    });
+}

package/dist/server/index.js

@@ -28,11 +28,29 @@ import { randomUUID } from "node:crypto";
 import express from "express";
 import { WebSocket, WebSocketServer } from "ws";
 import { VERSION, getAgentDir } from "@earendil-works/pi-coding-agent";
-import { AgentService, previewKind, workspacePath } from "./agent-service.js";
+import { AgentService, previewKind, workspacePath, QuiesceRejectedError, } from "./agent-service.js";
+import { startControlServer } from "./control-socket.js";
 import { ensureWindowsBash, windowsBashDir } from "./ensure-bash.js";
 const PORT = Number(process.env.PORT ?? 8787);
 const CWD = resolve(process.env.PI_WEB_CWD ?? process.cwd());
 const DATA_DIR = resolve(process.env.PI_WEB_DATA_DIR ?? join(homedir(), ".pi-web"));
+/** Bind address. Default is loopback ONLY — the service is a local personal
+ *  tool and should not be reachable from the network unless explicitly asked
+ *  (e.g. PI_WEB_HOST=0.0.0.0 for LAN access / Docker port mapping). */
+const HOST = process.env.PI_WEB_HOST ?? "127.0.0.1";
+/** Optional strict hostname allowlist (comma-separated) — only used when set.
+ *  Origin / Host same-authority matching happens regardless. */
+const ALLOW_HOSTS = (process.env.PI_WEB_ALLOW_HOSTS ?? "")
+    .split(",")
+    .map((s) => s.trim().toLowerCase())
+    .filter(Boolean);
+/** Optional extra Origins allowed through the same-authority check (comma-
+ *  separated, e.g. reverse-proxy setups where the browser origin differs
+ *  from the Host the backend sees). */
+const ALLOW_ORIGINS = (process.env.PI_WEB_ALLOW_ORIGINS ?? "")
+    .split(",")
+    .map((s) => s.trim().toLowerCase())
+    .filter(Boolean);
 // Root of the SDK default per-project session dirs — chat transcripts live in
 // <SESSION_DIR_ROOT>/--<cwd>--/, shared with the pi CLI/TUI (getAgentDir
 // honors PI_CODING_AGENT_DIR).
@@ -131,7 +149,77 @@ else if (process.env[RESTART_CHILD_ENV]) {
     process.exit(1);
 }
 const httpServer = createServer(app);
-const wss = new WebSocketServer({ server: httpServer, path: "/ws" });
+const wss = new WebSocketServer({ noServer: true });
+// ---------------------------------------------------------------------------
+// Origin / Host admission for WebSocket upgrades.
+//
+// Browsers attach an Origin header; non-browser clients (curl, ws scripts)
+// usually don't — they're admitted by the network layer / reverse proxy.
+// Rules (checked in order):
+//   4. No Origin header → admit (non-browser client).
+//   5. Anything else → 403 + close.
+//
+// Dev-mode note: the Vite dev server (:5173) proxies /ws to the backend on
+// :8788, so their authorities differ — the dev:server script sets
+// PI_WEB_ALLOW_ORIGINS=http://localhost:5173,http://127.0.0.1:5173 for that.
+// LAN / reverse-proxy setups add their own origin the same way.
+// ---------------------------------------------------------------------------
+/** "host" or "host:port" → { hostname, port }. */
+function parseAuthority(a) {
+    try {
+        const u = new URL(`http://${a}`);
+        return { hostname: u.hostname.toLowerCase(), port: u.port || "80" };
+    }
+    catch {
+        return { hostname: "", port: "" };
+    }
+}
+function originAllowed(req) {
+    const hostHeader = (req.headers.host ?? "").toLowerCase();
+    const host = parseAuthority(hostHeader);
+    if (ALLOW_HOSTS.length > 0 && !ALLOW_HOSTS.includes(host.hostname)) {
+        return false;
+    }
+    const origin = req.headers.origin;
+    if (!origin)
+        return true; // non-browser client
+    const o = origin.toLowerCase();
+    if (ALLOW_ORIGINS.includes(o))
+        return true;
+    if (o === "null")
+        return false; // file:// pages etc. are not trusted
+    const ori = parseAuthority(o.replace(/^[a-z]+:\/\//, ""));
+    if (ori.hostname === host.hostname && ori.port === host.port)
+        return true;
+    // Browsers treat host:port pairs on the SAME host as different origins —
+    // do not accept them. (Dev-mode proxying is handled by PI_WEB_ALLOW_ORIGINS
+    // set in the dev:server script; LAN/reverse-proxy setups add their origin.)
+    return false;
+    return false;
+}
+httpServer.on("upgrade", (req, socket, head) => {
+    let pathname = "/";
+    try {
+        pathname = new URL(req.url ?? "/", "http://localhost").pathname;
+    }
+    catch {
+        /* fall through to the path check below */
+    }
+    if (pathname !== "/ws") {
+        socket.destroy();
+        return;
+    }
+    if (!originAllowed(req)) {
+        // Reject cross-origin browser pages outright. The browser sees a failed
+        // WS connect; the page's own reconnect loop then backs off and retries.
+        socket.write("HTTP/1.1 403 Forbidden\r\nConnection: close\r\nContent-Length: 0\r\n\r\n");
+        socket.destroy();
+        return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => {
+        wss.emit("connection", ws, req);
+    });
+});
 // Heartbeat: lets clients detect half-open connections (server killed without
 // closing sockets, sleep/wake, network partitions). Idle connections otherwise
 // carry no traffic and TCP keepalive defaults are far too slow (~2h).
@@ -210,6 +298,9 @@ function scheduleQuit() {
 }
 service.onQuit = scheduleQuit;
 wss.on("connection", (ws) => {
+    // Count attached sockets (the control socket reports REAL sockets, not
+    // cached client-session objects).
+    service.noteSocketOpen();
     let clientId = null;
     let closed = false;
     /** Commands received while the session is still being created — replayed after attach. */
@@ -232,7 +323,7 @@ wss.on("connection", (ws) => {
         }
         switch (msg.type) {
             case "prompt":
-                void cs.prompt(msg.text, msg.attachments);
+                void cs.prompt(msg.text, msg.attachments, msg.queue);
                 break;
             case "abort":
                 void cs.abort();
@@ -381,6 +472,8 @@ wss.on("connection", (ws) => {
                     customSystemPrompt: msg.customSystemPrompt,
                     disabledSkills: msg.disabledSkills,
                     disabledExtensions: msg.disabledExtensions,
+                    visionBridgeEnabled: msg.visionBridgeEnabled,
+                    visionBridgeModel: msg.visionBridgeModel,
                 });
                 break;
             case "save_preset":
@@ -421,6 +514,19 @@ wss.on("connection", (ws) => {
                     dispatch(m);
             })
                 .catch((err) => {
+                // Admission refused (quiesce): close the socket so the browser
+                // reconnect loop keeps retrying until admission reopens. Do NOT
+                // leave a half-alive connection that can only show an error.
+                if (err instanceof QuiesceRejectedError) {
+                    closed = true;
+                    if (ws.readyState === WebSocket.OPEN) {
+                        ws.close(4403, "quiesced");
+                    }
+                    ws.terminate?.();
+                    return;
+                }
+                // Real init failure (bad agent dir etc.) — keep the connection
+                // open so the user can see the error and fix it.
                 send({
                     type: "notice",
                     level: "error",
@@ -432,6 +538,7 @@ wss.on("connection", (ws) => {
         dispatch(msg);
     });
     ws.on("close", () => {
+        service.noteSocketClose();
         closed = true;
         pending = [];
         if (clientId)
@@ -461,15 +568,19 @@ if (process.env[RESTART_CHILD_ENV] === "1") {
         await new Promise((r) => setTimeout(r, 300));
     }
 }
-httpServer.listen(PORT, () => {
+httpServer.listen(PORT, HOST, () => {
     console.log("");
     console.log("  ⚡ pi-web-ui — web chat for the pi coding agent");
     console.log(`    http://localhost:${PORT}`);
     console.log(`    workspace   : ${CWD}`);
     console.log(`    session dir : ${SESSION_DIR_ROOT}`);
     console.log(`    pi SDK      : v${VERSION}`);
+    console.log(`    bind        : ${HOST}:${PORT}`);
     console.log("");
 });
+// Local control socket (status / quiesce / unquiesce) — same data dir the
+// CLI uses, so `pi-web-ui server status|quiesce|unquiesce` just works.
+const stopControl = startControlServer({ service, dataDir: DATA_DIR, port: PORT });
 let shuttingDown = false;
 async function shutdown() {
     if (shuttingDown)
@@ -477,6 +588,7 @@ async function shutdown() {
     shuttingDown = true;
     console.log("\nshutting down…");
     clearInterval(heartbeatTimer);
+    stopControl();
     await service.disposeAll();
     wss.close();
     httpServer.close();

package/dist/server/vision-bridge.js

@@ -0,0 +1,113 @@
+/** Per-batch timeout; a slow vision provider shouldn't stall a prompt forever. */
+const TRANSCRIBE_TIMEOUT_MS = Number(process.env.PI_WEB_VISION_TIMEOUT_MS ?? 90_000);
+/** Cap the transcript length so it doesn't blow up the main context. */
+const MAX_TRANSCRIBE_TOKENS = 4000;
+/**
+ * Scan every configured provider for models that accept image input.
+ * Providers the user already configured in pi (models.json + auth.json) are
+ * reused as-is — zero new credentials to set up.
+ */
+export function findVisionModels(runtime) {
+    const out = [];
+    for (const p of runtime.getProviders()) {
+        // Only providers that actually have credentials — SDK built-ins like
+        // amazon-bedrock ship vision-capable models but are not configured
+        // unless the user added auth, and calling them would just fail.
+        if (!runtime.hasConfiguredAuth(p.id))
+            continue;
+        for (const m of runtime.getModels(p.id)) {
+            if (m.input?.includes("image")) {
+                out.push({
+                    provider: p.id,
+                    id: m.id,
+                    label: `${m.name ?? m.id} (${p.id})`,
+                });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Evidence-first transcription prompt, modeled on modlens' output contract:
+ * full verbatim text, reading-order layout blocks, entities/relations, chart
+ * axes & data. Emphasizes honesty over hallucination.
+ */
+const SYSTEM_PROMPT = `You are a vision bridge for a text-only language model. You receive one or more images and must transcribe them into precise, structured text evidence so another model that cannot see images can answer questions about them accurately.
+
+Follow these rules:
+1. Transcribe ALL visible text verbatim, preserving wording, spelling, punctuation and line breaks. This is the most important part — the reader relies on your transcription, not on the image.
+2. Describe the layout in reading order: headers, paragraphs, lists, tables, buttons, panels — say what appears where.
+3. For tables/charts/diagrams: read axes, scales (note log scale), legend entries, series names, highlighted points and their coordinates, and any data values you can discern.
+4. Name entities: people, products, companies, colors, style, objects, actions.
+5. If part of the image is too blurry/low-resolution to read, say "（读不清）" or "unclear" for that part — NEVER invent or guess content you cannot see.
+6. If there are multiple images, address them in order (图 1 / Image 1, 图 2 / Image 2, ...).
+7. Output only the transcript. No preamble, no commentary about the image itself.`;
+/** Per-batch user instruction appended after the images. */
+function buildUserPrompt(count) {
+    if (count <= 1) {
+        return "请逐字转写这张图片的内容，并按上述规则输出结构化文字证据。";
+    }
+    return `请按图片顺序（图 1 到 图 ${count}）逐张转写每张图片的内容，并按上述规则输出结构化文字证据。`;
+}
+/**
+ * Send one batch of images to a vision model and return its transcript.
+ * Throws on timeout, abort, provider error or an empty response.
+ */
+export async function transcribeImages(runtime, images, options = {}) {
+    const model = options.model ??
+        (() => {
+            const found = findVisionModels(runtime);
+            if (found.length === 0) {
+                throw new Error("未找到可用的视觉模型（models.json 中没有任何 input 含 image 的模型）");
+            }
+            return runtime.getModel(found[0].provider, found[0].id);
+        })();
+    if (!model)
+        throw new Error("视觉模型不可用（ModelRuntime.getModel 返回空）");
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), TRANSCRIBE_TIMEOUT_MS);
+    const onOuterAbort = () => ac.abort();
+    options.signal?.addEventListener("abort", onOuterAbort);
+    try {
+        const imageBlocks = images.map((img) => ({
+            type: "image",
+            data: img.data.replace(/^data:[^;]*;base64,/, ""),
+            mimeType: img.mimeType?.startsWith("image/")
+                ? img.mimeType
+                : "image/png",
+        }));
+        const context = {
+            systemPrompt: SYSTEM_PROMPT,
+            messages: [
+                {
+                    role: "user",
+                    timestamp: Date.now(),
+                    content: [
+                        ...imageBlocks,
+                        { type: "text", text: buildUserPrompt(images.length) },
+                    ],
+                },
+            ],
+        };
+        const msg = await runtime.completeSimple(model, context, {
+            signal: ac.signal,
+            maxTokens: MAX_TRANSCRIBE_TOKENS,
+        });
+        if (msg.stopReason === "error" || msg.stopReason === "aborted") {
+            throw new Error(msg.errorMessage || `视觉模型异常终止（${msg.stopReason}）`);
+        }
+        const text = msg.content
+            .filter((b) => b.type === "text")
+            .map((b) => b.text ?? "")
+            .join("\n")
+            .trim();
+        if (!text) {
+            throw new Error("视觉模型返回了空的转写结果");
+        }
+        return text;
+    }
+    finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", onOuterAbort);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-web-ui",
-  "version": "0.22.1",
+  "version": "0.24.0",
   "description": "Web chat interface for the pi coding agent, powered by the pi SDK (@earendil-works/pi-coding-agent) — one-command run, Docker/systemd/launchd deployable",
   "license": "MIT",
   "type": "module",
@@ -43,7 +43,7 @@
   "scripts": {
     "prepublishOnly": "npm run build",
     "dev": "concurrently -k -n server,web -c blue,green \"npm:dev:server\" \"npm:dev:web\"",
-    "dev:server": "cross-env PORT=8788 node --watch --import tsx server/index.ts",
+    "dev:server": "cross-env PORT=8788 PI_WEB_ALLOW_ORIGINS=http://localhost:5173,http://127.0.0.1:5173 node --watch --import tsx server/index.ts",
     "dev:web": "vite --config web/vite.config.ts",
     "build": "npm run build:web && npm run build:server",
     "build:web": "vite build --config web/vite.config.ts",