pi-web-ui 0.23.0 → 0.24.0

package/README.md

@@ -9,6 +9,65 @@ built-in terminal, manage models, tweak the system prompt, toggle skills and
 extensions on/off, and save/apply settings presets — all from a settings panel.
 Requires Node.js ≥ 22.19 and a configured pi install.
 
+## Features
+
+**Chat**
+
+- Streaming agent chat over WebSocket — the pi SDK runs in-process; events are pushed as snapshots (60 ms throttled) and the browser renders them.
+- Thinking blocks, tool-call cards and bash outputs with live status (running → finished · waiting for the model · duration).
+- **补充 (steer)** — send a follow-up while the agent is replying; it is queued and injected as soon as the current turn's tool calls settle (the "Interrupt" equivalent of the pi CLI).
+- **Slash commands** — `/` opens a command picker (built-in / extension / template / skill); built-ins include `/new /model /compact /cwd /thinking /resume`, plus `/help` (command list) and `/copy` (copy last reply).
+- **Multiple conversations per project** — each conversation gets its own agent runtime and keeps running in the background after you switch away; the "Running conversations" list shows stream progress and lets you switch back.
+- **Edit & re-ask** — fork any past question into a new branch and re-prompt; the original conversation stays untouched.
+- Long threads auto-collapse messages older than 30 into lazy summary rows (click to expand).
+- Question navigation — a floating rail plus per-question tags to jump between questions.
+
+**Files, images & attachments**
+
+- Three attachment modes: `inline` (≤12 KB), `reference` (path only), `lines` (selected ranges) — over-limit ones degrade automatically.
+- Paste / drag-drop / upload images — resized client-side and sent as image content when the model supports vision (warning otherwise).
+- **Vision bridge** — when the current model is text-only, images are transcribed into text evidence by an auto-discovered vision model (cached per batch; model & on/off configurable in Settings).
+- Attach arbitrary files without a workspace path — stored in a global uploads dir, inlined when small, referenced by absolute path otherwise.
+- File preview — line numbers, click/drag/Shift selection (add to chat as `lines`), GBK fallback decoding, binary hex view, media preview over HTTP with Range support, and a download button.
+- Live file tree — the server watches the listed directory (fs.watch) and re-lists on change; oversized directories show a truncation warning.
+
+**Terminal & Git**
+
+- Built-in terminal (xterm.js + node-pty) with per-client PTY management; Windows auto-selects Git Bash (busybox fallback).
+- **Source control (Git) panel** — status / branch / diff / untracked files via a hidden query terminal; commit, switch branch, push and pull run in the visible terminal and auto-switch to the terminal view.
+
+**Models & settings**
+
+- Model management — edit `models.json` in the UI and set per-provider API keys (keys/headers never leave the server).
+- Thinking level per model (only the levels the model actually supports are shown).
+- First-run setup wizard.
+- Settings panel — system prompt (append or replace), toggle skills/extensions on/off with immediate effect, save/apply/delete settings presets, and vision-bridge model & switch.
+
+**Goal mode**
+
+- Goal bar — set a target with a review model, max rounds and a lock switch.
+- Goal wizard ("AI 提炼") — turns a raw request into a concrete goal through a guided questionnaire.
+- Automatic review loop — after each turn an independent review session checks the goal against the final text and `git diff HEAD`; on fail the feedback is injected as steer until it passes (or the round cap is hit).
+
+**Background tasks**
+
+- Background-task panel — servers launched by the agent are detected via port snapshots and listed (port/pid/name); stop one or kill all.
+- Tool watchdog — a tool call running over 20 minutes is aborted automatically.
+- **Stop bash command only** — abort a running bash tool without killing the conversation.
+
+**Safety & operations**
+
+- Loopback-only by default; set `PI_WEB_HOST=0.0.0.0` for LAN / containers.
+- WebSocket Origin/Host same-authority check — cross-origin pages are rejected (403); `PI_WEB_ALLOW_ORIGINS` whitelist for reverse proxies.
+- Quiesce drain mode via a local control socket (`server status|quiesce|unquiesce`).
+- Credentials stay server-side — provider headers are never sent to the browser.
+- Sound alerts, Chinese/English UI, and a recent-projects list (click to switch workspace).
+
+**Deploy & update**
+
+- Foreground, global npm install, Docker (docker-compose), macOS launchd, Linux systemd, Windows Task Scheduler, and a desktop shortcut (`server shortcut`).
+- In-app self-update — checks the npm registry, installs and auto-restarts the service.
+
 ## Screenshots
 
 ![pi-web-ui main interface](https://cdn.jsdelivr.net/gh/xing-shuyin/pi-web-ui@main/assets/shot.jpeg)
@@ -105,3 +164,4 @@ port/cwd.
 ## License
 
 MIT
+

package/README.zh-CN.md

@@ -7,6 +7,65 @@
 模型管理，以及设置面板（自定义系统提示词、技能/插件开关、设置预设一键应用）等功能。
 需要 Node.js ≥ 22.19 及配置好的 pi 环境。
 
+## 功能特性
+
+**对话**
+
+- WebSocket 流式聊天 —— pi SDK 在服务端进程内运行，事件以快照（60ms 节流）推送，浏览器按快照渲染。
+- 思考块、工具调用卡片、bash 输出，实时显示状态（执行中 → 已结束 · 等模型 · 耗时）。
+- **补充（steer）** —— 回复流式中可排队发送跟进消息，当前回合工具结算后立即注入（对应 pi CLI 的 Enter 打断语义）。
+- **斜杠命令** —— 输入 `/` 弹出命令选择器（内置 / 扩展 / 模板 / 技能）；内置 `/new /model /compact /cwd /thinking /resume`，另有 `/help`（命令清单）与 `/copy`（复制上一条回复）。
+- **每项目多对话并发** —— 每个对话独立 agent runtime，切走后仍在后台运行；「运行的对话」列表显示流式进度，可随时切回。
+- **编辑重问** —— 把任意历史问题 fork 成新分支重新提问，原对话不受影响。
+- 超过 30 条的消息自动折叠为摘要行（惰性渲染，点击展开）。
+- 问题导航 —— 右侧浮动导航条 + 每个问题顶部的序号标签，一键跳转。
+
+**文件、图片与附件**
+
+- 三种附件模式：`inline`（≤12KB 内联）、`reference`（仅路径引用）、`lines`（选中行），超限自动降级。
+- 粘贴 / 拖拽 / 上传图片 —— 浏览器端自动缩放，模型支持识图时作为图片内容发送（不支持时提示警告）。
+- **视觉桥** —— 当前模型不支持识图时，把图片交给自动发现的视觉模型转写成文字证据（按批次缓存，可在设置里指定模型/开关）。
+- 免工作区路径附加任意文件 —— 存入全局上传目录，小文件内联，其余以绝对路径引用。
+- 文件预览 —— 行号、点选/拖拽/Shift 选区（可添加到对话为 lines 附件）、GBK 回退解码、二进制十六进制视图、媒体 HTTP 预览（支持 Range）、下载按钮。
+- 实时文件树 —— 服务端对当前列出目录 fs.watch，改动即静默重列；超大目录显示截断提示。
+
+**终端与 Git**
+
+- 内置终端（xterm.js + node-pty），每客户端独立 PTY 管理；Windows 自动选择 Git Bash（busybox 兜底）。
+- **源代码管理（Git）面板** —— 经隐藏查询终端展示 status / branch / diff / 未跟踪文件；提交、切换分支、推送、拉取复用可见终端并自动切换到终端视图。
+
+**模型与设置**
+
+- 模型管理 —— UI 里编辑 models.json、按 provider 设置 API key（密钥/headers 永不下发浏览器）。
+- 思考强度（thinking level）按模型切换（只显示该模型实际支持的档位）。
+- 首次配置引导（PiSetupModal）。
+- 设置面板 —— 系统提示词（追加或整体替换）、技能/插件一键开关（即时生效）、设置预设保存/应用/删除、视觉桥模型与开关。
+
+**目标（Goal）模式**
+
+- GoalBar 目标栏 —— 设置目标 + 审查模型 + 最大轮数 + 锁定开关。
+- 目标调研向导（「AI 提炼」）—— 通过引导式问卷把原始需求收敛成明确目标。
+- 自动审查循环 —— 每轮结束后用独立审查会话核对「目标 + 最终文本 + git diff HEAD」；不达标就把审查意见作为 steer 注入重改，直到通过或达到轮数上限。
+
+**后台任务**
+
+- 后台任务面板 —— 通过端口快照检测 agent 启动的服务（端口/pid/名称），可单独停止或全部关闭。
+- 工具看门狗 —— 单个工具调用超过 20 分钟自动中断会话。
+- **只停止 bash 命令** —— 中止运行中的 bash 工具而不打断对话。
+
+**安全与运维**
+
+- 默认只绑 loopback；局域网 / 容器需显式 `PI_WEB_HOST=0.0.0.0`。
+- WebSocket Origin/Host 同权威校验 —— 跨源页面直接拒绝（403）；反代场景用 `PI_WEB_ALLOW_ORIGINS` 白名单。
+- 本地控制 socket 提供 `server status|quiesce|unquiesce`（排空模式：拒绝新工作、存量跑完）。
+- 凭据不下发浏览器 —— provider headers（可能含 Authorization/API key）永不发送到前端。
+- 声音提醒、中英文界面、最近项目列表（点击即切换工作目录）。
+
+**部署与更新**
+
+- 前台运行 / 全局 npm 安装 / Docker（docker-compose）/ macOS launchd / Linux systemd / Windows 计划任务 / 桌面快捷方式（`server shortcut`）。
+- 界面内自更新 —— 对比 npm registry 版本，安装后自动重启服务。
+
 ## 界面截图
 
 ![pi-web-ui 主界面](https://cdn.jsdelivr.net/gh/xing-shuyin/pi-web-ui@main/assets/shot.jpeg)

package/dist/server/agent-service.js

@@ -18,6 +18,7 @@ import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentS
 import { Type } from "typebox";
 import { serializeMessage, serializeStreamingMessage, } from "./serialize.js";
 import { loadCommands, saveCommandsFile, TerminalManager, } from "./terminals.js";
+import { findVisionModels, transcribeImages, } from "./vision-bridge.js";
 const SNAPSHOT_INTERVAL_MS = 60;
 const WIDGET_REFRESH_MS = 2000;
 const WIDGET_WIDTH = 80;
@@ -230,6 +231,42 @@ function decodeText(buf) {
         }
     }
 }
+/** Sniff an image MIME type from magic bytes (extension is only a hint).
+ *  Returns null when the bytes don't look like a known raster format —
+ *  callers keep such files as plain path references. */
+function sniffImageMime(buf, ext) {
+    if (buf.length >= 8 &&
+        buf[0] === 0x89 &&
+        buf[1] === 0x50 &&
+        buf[2] === 0x4e &&
+        buf[3] === 0x47) {
+        return "image/png";
+    }
+    if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) {
+        return "image/jpeg";
+    }
+    const head = buf.slice(0, 6).toString("ascii");
+    if (head === "GIF87a" || head === "GIF89a")
+        return "image/gif";
+    if (buf.length >= 12 &&
+        buf.slice(0, 4).toString("ascii") === "RIFF" &&
+        buf.slice(8, 12).toString("ascii") === "WEBP") {
+        return "image/webp";
+    }
+    if (buf.length >= 2 && buf[0] === 0x42 && buf[1] === 0x4d)
+        return "image/bmp";
+    // Unknown but raster-looking extension — trust the extension so existing
+    // image attachments keep working.
+    const known = {
+        ".png": "image/png",
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".gif": "image/gif",
+        ".webp": "image/webp",
+        ".bmp": "image/bmp",
+    };
+    return known[ext] ?? null;
+}
 /** Windows persona appendix — appended to the SDK system prompt on win32 only.
  *  Two failure modes it guards against: (1) the SDK bash tool has NO default
  *  timeout, so a long-running command hangs the whole conversation forever;
@@ -868,6 +905,8 @@ class ClientStateStore {
             customSystemPrompt: s?.settings?.customSystemPrompt ?? "",
             disabledSkills: s?.settings?.disabledSkills ?? [],
             disabledExtensions: s?.settings?.disabledExtensions ?? [],
+            visionBridgeEnabled: s?.settings?.visionBridgeEnabled ?? true,
+            visionBridgeModel: s?.settings?.visionBridgeModel ?? null,
         };
     }
     /** Persist the client's settings-panel state (partial merge). */
@@ -880,6 +919,8 @@ class ClientStateStore {
             customSystemPrompt: settings.customSystemPrompt ?? cur.customSystemPrompt ?? "",
             disabledSkills: settings.disabledSkills ?? cur.disabledSkills ?? [],
             disabledExtensions: settings.disabledExtensions ?? cur.disabledExtensions ?? [],
+            visionBridgeEnabled: settings.visionBridgeEnabled ?? cur.visionBridgeEnabled ?? true,
+            visionBridgeModel: settings.visionBridgeModel ?? cur.visionBridgeModel ?? null,
         };
         this.save();
     }
@@ -1061,6 +1102,12 @@ export class ClientSession {
     }
     /** PTY terminals for this client (killed when the last socket detaches). */
     terminals = new TerminalManager((msg) => this.emit(msg));
+    /**
+     * Vision-bridge transcript cache (batch hash → text). A re-sent / re-asked
+     * prompt with the same images skips the vision API call entirely — editing
+     * a question doesn't re-burn tokens on re-transcribing identical screenshots.
+     */
+    visionBridgeCache = new Map();
     /** Web-facing extension UI context (widgets, notifications). */
     webUi = new WebUIContext((msg) => this.emit(msg));
     widgetsTimer = null;
@@ -2482,6 +2529,9 @@ export class ClientSession {
             settings: {
                 promptMode: this.settings.promptMode,
                 customSystemPrompt: this.settings.customSystemPrompt,
+                visionBridgeEnabled: this.settings.visionBridgeEnabled,
+                visionBridgeModel: this.settings.visionBridgeModel,
+                visionModels: this.collectVisionModels(),
                 disabledSkills: [...this.settings.disabledSkills],
                 disabledExtensions: [...this.settings.disabledExtensions],
                 skills,
@@ -2490,8 +2540,26 @@ export class ClientSession {
             },
         });
     }
+    /** Vision-capable configured models, for the settings-panel picker. */
+    collectVisionModels() {
+        try {
+            return findVisionModels(this.session.modelRuntime).map((m) => ({
+                provider: m.provider,
+                id: m.id,
+                label: m.label,
+            }));
+        }
+        catch {
+            // Session not ready yet — the picker stays empty until next push.
+            return [];
+        }
+    }
     /** Persist + apply a partial settings update (prompt text/mode, toggles). */
     async setSettings(partial) {
+        const needsReload = partial.promptMode !== undefined ||
+            partial.customSystemPrompt !== undefined ||
+            partial.disabledSkills !== undefined ||
+            partial.disabledExtensions !== undefined;
         if (partial.promptMode !== undefined)
             this.settings.promptMode = partial.promptMode;
         if (partial.customSystemPrompt !== undefined) {
@@ -2503,9 +2571,16 @@ export class ClientSession {
         if (partial.disabledExtensions !== undefined) {
             this.settings.disabledExtensions = partial.disabledExtensions;
         }
+        if (partial.visionBridgeEnabled !== undefined) {
+            this.settings.visionBridgeEnabled = partial.visionBridgeEnabled;
+        }
+        if (partial.visionBridgeModel !== undefined) {
+            this.settings.visionBridgeModel = partial.visionBridgeModel ?? null;
+        }
         this.stateStore.saveSettings(this.clientId, this.settings);
         this.pushSettings();
-        await this.applyRuntimeSettings();
+        if (needsReload)
+            await this.applyRuntimeSettings();
     }
     /** Save the CURRENT settings as a named preset (overwrites if exists). */
     async savePreset(name) {
@@ -2541,6 +2616,9 @@ export class ClientSession {
             customSystemPrompt: p.customSystemPrompt,
             disabledSkills: [...p.disabledSkills],
             disabledExtensions: [...p.disabledExtensions],
+            // Presets don't capture vision-bridge prefs — keep the current ones.
+            visionBridgeEnabled: this.settings.visionBridgeEnabled,
+            visionBridgeModel: this.settings.visionBridgeModel,
         };
         this.stateStore.saveSettings(this.clientId, this.settings);
         this.pushSettings();
@@ -2629,7 +2707,14 @@ export class ClientSession {
             n += c.queueFollowUp + c.queueSteering;
         return n;
     }
-    async prompt(text, attachments) {
+    async prompt(text, attachments, 
+    /**
+     * true = followUp: while streaming, queue the prompt and deliver it only
+     * after the WHOLE run finishes (补充 button — "AI 生成结束才发送").
+     * false/undefined = steer: the pi CLI Enter semantic — injected right
+     * after the current turn settles, skipping remaining planned tool calls.
+     */
+    queue = false) {
         try {
             const s = this.session;
             // Native slash commands (see NATIVE_COMMANDS) are executed here and
@@ -2652,13 +2737,19 @@ export class ClientSession {
                 await s.sendCustomMessage(aside.message, { deliverAs: "nextTurn" });
             }
             if (s.isStreaming) {
-                // Steer: interrupts the current run — the message is delivered right
-                // after the current assistant turn settles (remaining planned tool
-                // calls are skipped) and the agent immediately responds to it. This
-                // is the pi CLI Enter-during-streaming semantic (docs/usage: Enter
-                // queues a steering message); followUp would wait for the whole run
+                // queue=true (补充 button) → followUp: the message is delivered only
+                // after the whole run finishes — the agent finishes what it started,
+                // then responds to the queued message. queue=false/undefined
+                // (plain Enter) → steer: interrupts the current run — the message
+                // is delivered right after the current assistant turn settles
+                // (remaining planned tool calls are skipped) and the agent
+                // immediately responds to it. This is the pi CLI
+                // Enter-during-streaming semantic (docs/usage: Enter queues a
+                // steering message); followUp would wait for the whole run
                 // to finish, which users perceive as ordinary queueing.
-                await s.prompt(text, { streamingBehavior: "steer" });
+                await s.prompt(text, {
+                    streamingBehavior: queue ? "followUp" : "steer",
+                });
             }
             else {
                 await s.prompt(text);
@@ -2727,9 +2818,147 @@ export class ClientSession {
             ".svg": "image/svg+xml",
         };
         const out = [];
+        // -- Vision bridge ------------------------------------------------------
+        // When the active model can't accept images (DeepSeek, GLM, …), pasted
+        // images are transcribed by a configured vision model first and the
+        // transcript is fed to the text-only model as text evidence (see
+        // vision-bridge.ts — any model in models.json whose input includes
+        // "image" works, zero extra config). Vision-capable main models keep
+        // the raw image-content path untouched.
+        const mainModel = this.session.model;
+        const mainSupportsVision = mainModel?.input?.includes("image") ?? false;
+        const bridgedImages = [];
+        /** Raw image bytes for path-referenced image files (idx → info), pre-read
+         *  so the loop below doesn't re-read them. SVG stays a plain text file —
+         *  the model reads its source, far more useful than a rasterized blob. */
+        const pathImageData = new Map();
+        /** Cap for path images (fully read + base64'd); larger ones fall back to
+         *  a plain path reference (the model can still attempt to read them). */
+        const MAX_PATH_IMAGE_BYTES = 5 * 1024 * 1024;
+        for (const [idx, att] of attachments.entries()) {
+            if (att.imageData) {
+                const raw = att.imageData.replace(/^data:[^;]*;base64,/, "");
+                const mimeType = att.mimeType?.startsWith("image/")
+                    ? att.mimeType
+                    : "image/png";
+                const bytes = Buffer.byteLength(raw, "base64");
+                // Only images that would actually be sent (non-empty, under the cap).
+                if (bytes > 0 && bytes <= 2 * 1024 * 1024) {
+                    if (!mainSupportsVision) {
+                        bridgedImages.push({ idx, att, raw, mimeType, bytes });
+                    }
+                }
+                continue;
+            }
+            if (att.fileData || !att.path)
+                continue;
+            const ext = extname(att.path).toLowerCase();
+            if (!IMAGE_EXT.has(ext) || ext === ".svg")
+                continue;
+            const abs = resolve(root, att.path);
+            const rawRel = relative(root, abs);
+            if (rawRel.startsWith("..") || rawRel.includes(`${sep}..`))
+                continue;
+            let st;
+            try {
+                st = await fs.stat(abs);
+            }
+            catch {
+                continue;
+            }
+            if (!st.isFile() || st.size === 0 || st.size > MAX_PATH_IMAGE_BYTES) {
+                continue;
+            }
+            const buf = await fs.readFile(abs);
+            const mime = sniffImageMime(buf, ext);
+            if (!mime)
+                continue;
+            const raw = buf.toString("base64");
+            pathImageData.set(idx, { raw, mimeType: mime, bytes: st.size });
+            if (!mainSupportsVision) {
+                bridgedImages.push({ idx, att, raw, mimeType: mime, bytes: st.size });
+            }
+        }
+        /** Transcript per attachment index (filled below, keyed by bridgedImages idx). */
+        const bridgeTranscripts = new Map();
+        if (bridgedImages.length > 0) {
+            if (!this.settings.visionBridgeEnabled) {
+                this.emit({
+                    type: "notice",
+                    level: "warning",
+                    text: `当前模型（${mainModel?.name ?? mainModel?.id ?? "未知"}）不支持识图，且视觉桥已在设置中关闭：图片将原样发送、可能被忽略。`,
+                });
+            }
+            else {
+                const visionModels = findVisionModels(this.session.modelRuntime);
+                // Preferred model from settings ("provider/id") — validated to exist
+                // and actually accept images; falls back to the first auto-detected.
+                let chosen = visionModels[0] ?? null;
+                const pref = this.settings.visionBridgeModel;
+                if (pref) {
+                    const spec = this.resolveReviewModel(pref);
+                    if (spec) {
+                        const pm = this.session.modelRuntime.getModel(spec.provider, spec.id);
+                        if (pm?.input?.includes("image")) {
+                            chosen = {
+                                provider: spec.provider,
+                                id: spec.id,
+                                label: `${pm.name ?? pm.id} (${spec.provider})`,
+                            };
+                        }
+                    }
+                }
+                if (!chosen) {
+                    this.emit({
+                        type: "notice",
+                        level: "warning",
+                        text: `当前模型（${mainModel?.name ?? mainModel?.id ?? "未知"}）不支持识图，且未找到可用的视觉模型：图片将原样发送、可能被忽略。在模型配置里添加任意支持图片的模型（如 qwen-vl、GLM-4V、Gemini）即可自动启用视觉桥转写。`,
+                    });
+                }
+                else {
+                    // Batch hash so re-sending identical images (edit & re-ask) reuses
+                    // the transcript instead of re-burning tokens on the vision API.
+                    const batchHash = bridgedImages
+                        .map((b) => `${b.att.name ?? "img"}:${b.raw.slice(0, 48)}`)
+                        .join("|");
+                    let transcript = this.visionBridgeCache.get(batchHash);
+                    if (transcript === undefined) {
+                        this.emit({
+                            type: "notice",
+                            level: "info",
+                            text: `当前模型不支持识图，正在用视觉桥（${chosen.label}）转写 ${bridgedImages.length} 张图片…`,
+                        });
+                        try {
+                            const chosenModel = this.session.modelRuntime.getModel(chosen.provider, chosen.id);
+                            transcript = await transcribeImages(this.session.modelRuntime, bridgedImages.map((b) => ({
+                                data: b.raw,
+                                mimeType: b.mimeType,
+                                name: b.att.name,
+                            })), { model: chosenModel ?? undefined });
+                            this.visionBridgeCache.set(batchHash, transcript);
+                            this.emit({
+                                type: "notice",
+                                level: "info",
+                                text: `✅ 图片已由视觉桥转写完成（${chosen.label}）`,
+                            });
+                        }
+                        catch (err) {
+                            transcript = "";
+                            this.emit({
+                                type: "notice",
+                                level: "error",
+                                text: `图片转写失败（${chosen.label}）：${err.message}。图片将原样发送、可能被忽略。`,
+                            });
+                        }
+                    }
+                    for (const b of bridgedImages)
+                        bridgeTranscripts.set(b.idx, transcript ?? "");
+                }
+            }
+        }
         /** Cap for reading a file in "lines" mode (selected slice is inlined). */
         const MAX_LINES_READ_BYTES = 2 * 1024 * 1024;
-        for (const att of attachments) {
+        for (const [idx, att] of attachments.entries()) {
             // Raw pasted/dropped/uploaded image — no workspace path involved (the
             // browser downscales client-side; this guard only prevents abuse).
             if (att.imageData) {
@@ -2753,6 +2982,32 @@ export class ClientSession {
                     });
                     continue;
                 }
+                const transcript = bridgeTranscripts.get(idx);
+                if (transcript) {
+                    // Bridged: the text-only main model can't see images, so it gets the
+                    // vision model's transcript as text evidence; the image block is
+                    // kept so the card still shows the original thumbnail.
+                    out.push({
+                        message: {
+                            customType: "file",
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `\n<vision-bridge>\n${transcript}\n</vision-bridge>`,
+                                },
+                                { type: "image", data: raw, mimeType },
+                            ],
+                            display: true,
+                            details: {
+                                name: att.name ?? "image.png",
+                                path: undefined,
+                                mode: "bridged",
+                                size: bytes,
+                            },
+                        },
+                    });
+                    continue;
+                }
                 out.push({
                     message: {
                         customType: "file",
@@ -2905,8 +3160,63 @@ export class ClientSession {
                 continue;
             }
             const ext = extname(att.path).toLowerCase();
-            if (IMAGE_EXT.has(ext)) {
-                // Images can't be referenced — they must be inlined, so keep a hard cap.
+            if (IMAGE_EXT.has(ext) && ext !== ".svg") {
+                const pathImg = pathImageData.get(idx);
+                const transcript = bridgeTranscripts.get(idx);
+                if (transcript) {
+                    // Text-only main model: the vision bridge transcribed this image —
+                    // the model gets the transcript as text evidence (+ thumbnail).
+                    out.push({
+                        message: {
+                            customType: "file",
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `
+<vision-bridge>
+${transcript}
+</vision-bridge>`,
+                                },
+                                ...(pathImg
+                                    ? ([{
+                                            type: "image",
+                                            data: pathImg.raw,
+                                            mimeType: pathImg.mimeType,
+                                        }])
+                                    : []),
+                            ],
+                            display: true,
+                            details: {
+                                name,
+                                path: rel,
+                                mode: "bridged",
+                                size: stat.size,
+                            },
+                        },
+                    });
+                    continue;
+                }
+                if (pathImg) {
+                    // Vision-capable main model (or bridge failed): send the raw image
+                    // content straight from the pre-read bytes.
+                    out.push({
+                        message: {
+                            customType: "file",
+                            content: [
+                                {
+                                    type: "image",
+                                    data: pathImg.raw,
+                                    mimeType: pathImg.mimeType,
+                                },
+                            ],
+                            display: true,
+                            details: { name, path: rel, mode: "image", size: stat.size },
+                        },
+                    });
+                    continue;
+                }
+                // Pre-read failed (unsupported sniff / too large): fall back to the
+                // legacy inline-cap behavior.
                 if (stat.size > MAX_ATTACHMENT_BYTES) {
                     this.emit({
                         type: "notice",

package/dist/server/index.js

@@ -323,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();
@@ -472,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":