@co0ontty/wand 4.72.1 → 4.72.2-beta.g26c27fb

package/dist/server.js

@@ -55,7 +55,8 @@ import { isLogBusActive, wandTuiLog } from "./tui/log-bus.js";
 import { EMBEDDED_WEB_ASSETS } from "./web-ui/embedded-assets.js";
 import { renderApp } from "./web-ui/index.js";
 import { WsBroadcastManager } from "./ws-broadcast.js";
-import { createTerminalHost, TerminalDaemonClient } from "./terminal-daemon-client.js";
+import { TerminalDaemonClient } from "./terminal-daemon-client.js";
+import { createUpgradeAwareTerminalHost, resolveRenderEngine } from "./render-host.js";
 import { checkRateLimit, recordFailedLogin, resetRateLimit } from "./middleware/rate-limit.js";
 import { updateProviderClis, verifyProviderCliUpdateResults, } from "./provider-cli-updater.js";
 const SERVER_MODULE_DIR = path.dirname(new URL(import.meta.url).pathname);
@@ -317,12 +318,34 @@ export async function startServer(config, configPath, options = {}) {
         config,
         repositoryUrl: PKG_REPO_URL,
     });
-    const terminalHost = options.terminalHost ?? await createTerminalHost(configPath);
+    // PTY 所有者可以是 legacy terminald 或常驻的 Rust Render：升级期由复合 host 按所有权
+    // 路由（旧会话留在 legacy，新会话进 Render），对客户端契约没有任何改变。
+    const ptyHosts = options.terminalHost
+        ? { host: options.terminalHost, renderHost: null, legacyHost: null }
+        : await createUpgradeAwareTerminalHost(configPath, {
+            engine: config.render?.engine,
+            binaryPath: config.render?.binaryPath,
+        });
+    const terminalHost = ptyHosts.host;
     const processes = new ProcessManager(config, storage, configDir, terminalHost);
     const structuredLogger = new SessionLogger(configDir, config.shortcutLogMaxBytes);
     // Production startup requires the daemon-backed host so CLI runs outlive web
     // restarts. In-process hosts are retained only for explicit test injection.
-    const structuredExecHost = terminalHost instanceof TerminalDaemonClient ? terminalHost : undefined;
+    const structuredExecHost = ptyHosts.legacyHost
+        ?? (terminalHost instanceof TerminalDaemonClient ? terminalHost : undefined);
+    // Render 协议 v1 没有任何 structured* 方法，而 Render 模式对 legacy terminald 只
+    // adopt、不 spawn：本机没有旧 terminald 时这里就是 undefined，结构化 CLI run 会
+    // 退化成进程内运行（`recoverDetachedRuns()` 也会 no-op）。这相对「web 重启不丢任务」
+    // 是功能回退，绝不能静默发生 —— 见 docs/render-upgrade-path.md §10.4。
+    if (!structuredExecHost && process.env.WAND_TEST_MODE !== "1" && !process.env.NODE_TEST_CONTEXT) {
+        const renderEngine = resolveRenderEngine(process.env.WAND_RENDER_ENGINE, config.render?.engine);
+        process.stderr.write("[wand] WARNING: structured CLI runs will NOT survive a web restart. " +
+            `render.engine=${renderEngine} only adopts an existing legacy terminald (it never spawns one) and Render protocol v1 has no ` +
+            "structured methods, so structured runs stay inside this web process and recoverDetachedRuns() is a no-op. " +
+            `Workaround: set "render": { "engine": "legacy" } in ${configPath} so Wand starts/adopts the legacy terminald again ` +
+            "(PTYs already owned by Render keep running), or keep a legacy terminald alive on this machine. " +
+            "See docs/render-upgrade-path.md §10.4.\n");
+    }
     const structuredSessions = new StructuredSessionManager(storage, config, structuredLogger, undefined, {}, structuredExecHost);
     const sessionRegistry = new SessionRegistry(processes, structuredSessions, storage);
     const missions = new Missions(storage, structuredSessions, sessionRegistry);

package/dist/session-transport.js

@@ -87,7 +87,7 @@ export function toSessionDetailDTO(snapshot, options = {}) {
         outputOffset,
         outputTotal: rawOutput.length,
         outputTruncated: outputOffset > 0,
-        ...(options.messages !== undefined ? { messages: enrichStructuredMessages(options.messages) } : {}),
+        ...(options.messages !== undefined ? { messages: enrichStructuredMessages(options.messages, snapshot.id) } : {}),
         ...(options.messageOffset !== undefined ? { messageOffset: options.messageOffset } : {}),
         ...(options.messageTotal !== undefined ? { messageTotal: options.messageTotal } : {}),
         ...(options.leadingBlockOffset !== undefined ? { leadingBlockOffset: options.leadingBlockOffset } : {}),

package/dist/structured-client-protocol.d.ts

@@ -3,5 +3,7 @@ export declare const WAND_PROTOCOL_VERSION = 2;
 /**
  * Add Wand-owned semantics without mutating persisted provider blocks.
  * This is the external interface consumed by every client.
+ *
+ * 传 sessionId 时额外把内联图片改写成取图 URL（见 rewriteInlineToolImageUrls）。
  */
-export declare function enrichStructuredMessages(messages: ConversationTurn[]): ConversationTurn[];
+export declare function enrichStructuredMessages(messages: ConversationTurn[], sessionId?: string): ConversationTurn[];

package/dist/structured-client-protocol.js

@@ -1,4 +1,4 @@
-import { asRecord } from "./structured-content.js";
+import { asRecord, isStructuredImagePart } from "./structured-content.js";
 export const WAND_PROTOCOL_VERSION = 2;
 function text(value) {
     return typeof value === "string" && value ? value : undefined;
@@ -190,11 +190,54 @@ function tasksFromSegment(messages, start, end) {
         targetId,
     };
 }
+/**
+ * 把 tool_result 里的内联 base64 图片换成「按会话取图」的 URL。
+ *
+ * 为什么不能把 base64 直接下发：读一张截图动辄 1–3MB，base64 后更大，会撑爆移动端
+ * 单帧上限（iOS 默认 1MiB）导致反复断连；而且同一张图在每条快照里重复传。换成 URL
+ * 后各端用同一套带鉴权的取图通道按需加载（Web 走 <img>，原生走各自 ImageLoader）。
+ * source 本来就是 url 的图片不动，保持幂等。
+ */
+function rewriteInlineToolImageUrls(messages, sessionId) {
+    return messages.map((turn) => {
+        let turnChanged = false;
+        const content = turn.content.map((block) => {
+            if (block.type !== "tool_result" || !Array.isArray(block.content))
+                return block;
+            let imageIndex = -1;
+            let blockChanged = false;
+            const parts = block.content.map((part) => {
+                if (!isStructuredImagePart(part))
+                    return part;
+                imageIndex += 1;
+                const source = asRecord(part.source);
+                if (source?.type !== "base64" || typeof source.data !== "string")
+                    return part;
+                blockChanged = true;
+                return {
+                    type: "image",
+                    source: {
+                        type: "url",
+                        url: `/api/sessions/${encodeURIComponent(sessionId)}/tool-images/${encodeURIComponent(block.tool_use_id)}/${imageIndex}`,
+                        ...(typeof source.media_type === "string" ? { media_type: source.media_type } : {}),
+                    },
+                };
+            });
+            if (!blockChanged)
+                return block;
+            turnChanged = true;
+            return { ...block, content: parts };
+        });
+        return turnChanged ? { ...turn, content } : turn;
+    });
+}
 /**
  * Add Wand-owned semantics without mutating persisted provider blocks.
  * This is the external interface consumed by every client.
+ *
+ * 传 sessionId 时额外把内联图片改写成取图 URL（见 rewriteInlineToolImageUrls）。
  */
-export function enrichStructuredMessages(messages) {
+export function enrichStructuredMessages(messages, sessionId) {
     const enriched = stampDerivedSubagents(messages).map((turn) => ({
         ...turn,
         content: turn.content.map((block) => {
@@ -231,5 +274,5 @@ export function enrichStructuredMessages(messages) {
         }
         segmentStart = i;
     }
-    return enriched;
+    return sessionId ? rewriteInlineToolImageUrls(enriched, sessionId) : enriched;
 }

package/dist/structured-content.d.ts

@@ -1,7 +1,24 @@
 /** 把 unknown 收敛成普通对象；数组 / null / 原始值都返回 null。 */
 export declare function asRecord(value: unknown): Record<string, unknown> | null;
-/** Preserve both Responses content parts and arbitrary structured tool output. */
-export declare function normalizeStructuredToolResultContent(content: unknown): string | Array<{
+export type StructuredContentPart = {
     type: string;
     [key: string]: unknown;
-}>;
+};
+/**
+ * 各家 provider 的图片 part 形态不同：
+ *   · Anthropic：`{ type:"image", source:{ type:"base64", media_type, data } }` / `source:{ type:"url", url }`
+ *   · OpenAI Responses：`{ type:"image_url", image_url:{ url } }` / `image_url:"…"`
+ *   · Pi：`{ type:"image", data, mimeType }`
+ * 只要带图片语义就算，具体归一化交给 canonicalizeStructuredImagePart。
+ */
+export declare function isStructuredImagePart(value: unknown): boolean;
+/**
+ * 统一成客户端认识的规范形态（Web / Android / iOS / macOS 都按
+ * `{ type:"image", source:{ type:"base64"|"url", … } }` 解析）。识别不了返回 null，
+ * 由调用方原样保留，避免丢信息。
+ */
+export declare function canonicalizeStructuredImagePart(value: unknown): StructuredContentPart | null;
+/** content（字符串 / part 数组）里是否含图片 part。 */
+export declare function contentHasStructuredImage(content: unknown): boolean;
+/** Preserve both Responses content parts and arbitrary structured tool output. */
+export declare function normalizeStructuredToolResultContent(content: unknown): string | StructuredContentPart[];

package/dist/structured-content.js

@@ -4,12 +4,91 @@ export function asRecord(value) {
         ? value
         : null;
 }
+function stringValue(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/**
+ * 各家 provider 的图片 part 形态不同：
+ *   · Anthropic：`{ type:"image", source:{ type:"base64", media_type, data } }` / `source:{ type:"url", url }`
+ *   · OpenAI Responses：`{ type:"image_url", image_url:{ url } }` / `image_url:"…"`
+ *   · Pi：`{ type:"image", data, mimeType }`
+ * 只要带图片语义就算，具体归一化交给 canonicalizeStructuredImagePart。
+ */
+export function isStructuredImagePart(value) {
+    const part = asRecord(value);
+    if (!part)
+        return false;
+    if (part.type === "image_url")
+        return !!imageUrlOf(part);
+    if (part.type !== "image")
+        return false;
+    const source = asRecord(part.source);
+    if (source && (stringValue(source.data) || stringValue(source.url)))
+        return true;
+    return !!(stringValue(part.data) || stringValue(part.url));
+}
+function imageUrlOf(part) {
+    const raw = part.image_url;
+    if (typeof raw === "string")
+        return stringValue(raw);
+    return stringValue(asRecord(raw)?.url);
+}
+/**
+ * 统一成客户端认识的规范形态（Web / Android / iOS / macOS 都按
+ * `{ type:"image", source:{ type:"base64"|"url", … } }` 解析）。识别不了返回 null，
+ * 由调用方原样保留，避免丢信息。
+ */
+export function canonicalizeStructuredImagePart(value) {
+    const part = asRecord(value);
+    if (!part)
+        return null;
+    if (part.type === "image_url") {
+        const url = imageUrlOf(part);
+        return url ? { type: "image", source: { type: "url", url } } : null;
+    }
+    if (part.type !== "image")
+        return null;
+    const source = asRecord(part.source);
+    if (source) {
+        const data = stringValue(source.data);
+        if (source.type === "base64" && data) {
+            return {
+                type: "image",
+                source: { type: "base64", media_type: stringValue(source.media_type) ?? "image/png", data },
+            };
+        }
+        const url = stringValue(source.url);
+        if (url)
+            return { type: "image", source: { type: "url", url } };
+    }
+    const data = stringValue(part.data);
+    if (data) {
+        const mediaType = stringValue(part.mimeType)
+            ?? stringValue(part.mime_type)
+            ?? stringValue(source?.media_type)
+            ?? "image/png";
+        return { type: "image", source: { type: "base64", media_type: mediaType, data } };
+    }
+    const url = stringValue(part.url);
+    if (url)
+        return { type: "image", source: { type: "url", url } };
+    return null;
+}
+/** content（字符串 / part 数组）里是否含图片 part。 */
+export function contentHasStructuredImage(content) {
+    if (!Array.isArray(content))
+        return false;
+    return content.some((part) => isStructuredImagePart(part));
+}
 /** Preserve both Responses content parts and arbitrary structured tool output. */
 export function normalizeStructuredToolResultContent(content) {
     if (typeof content === "string")
         return content;
     if (Array.isArray(content)) {
-        const parts = content.filter((item) => !!item && typeof item === "object" && typeof item.type === "string");
+        const parts = content
+            .filter((item) => !!item && typeof item === "object" && typeof item.type === "string")
+            // 图片 part 归一化后客户端才能跨端渲染；非图片 part 原样保留。
+            .map((part) => canonicalizeStructuredImagePart(part) ?? part);
         if (parts.length === content.length)
             return parts;
         try {

package/dist/structured-pi-adapter.js

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { startStructuredCli } from "./structured-exec-pump.js";
-import { asRecord } from "./structured-content.js";
+import { asRecord, normalizeStructuredToolResultContent } from "./structured-content.js";
 import { thinkingEffortToPiLevel } from "./structured-provider-common.js";
 export function isMissingPiSession(error, sessionId) {
     return !!sessionId && !!error?.includes(`No session found matching '${sessionId}'`);
@@ -17,6 +17,22 @@ function textContent(value) {
         return item.text;
     return textContent(item.content);
 }
+/**
+ * Pi 的工具结果是 `{ content: [ text…, image… ] }`。图片 part 不能像以前那样只抽文本
+ * 丢掉——读图 / 截图全靠它，统一交给 normalizeStructuredToolResultContent 归一化。
+ * 纯文本结果仍压成字符串，保持既有形态。
+ */
+function piToolResultContent(value) {
+    const record = asRecord(value);
+    const raw = record && "content" in record ? record.content : value;
+    const normalized = normalizeStructuredToolResultContent(raw);
+    if (typeof normalized === "string")
+        return normalized;
+    if (normalized.length > 0 && normalized.every((part) => part.type === "text" && typeof part.text === "string")) {
+        return normalized.map((part) => part.text).filter(Boolean).join("\n");
+    }
+    return normalized;
+}
 export function buildPiArgs(session, prompt) {
     const args = ["--mode", "json", "--print"];
     const model = session.selectedModel?.trim();
@@ -141,7 +157,7 @@ export function applyPiEvent(state, event) {
     }
     if (event.type === "tool_execution_end") {
         const id = typeof event.toolCallId === "string" ? event.toolCallId : "unknown";
-        state.blocks.push({ type: "tool_result", tool_use_id: id, content: textContent(event.result), is_error: event.isError === true });
+        state.blocks.push({ type: "tool_result", tool_use_id: id, content: piToolResultContent(event.result), is_error: event.isError === true });
     }
     if (event.type === "message_end" || event.type === "turn_end") {
         const message = asRecord(event.message);

package/dist/structured-session-manager.js

@@ -207,7 +207,7 @@ function buildStructuredOutputPayload(snapshot) {
     return {
         wandProtocolVersion: WAND_PROTOCOL_VERSION,
         output: snapshot.output,
-        messages: snapshot.messages ? enrichStructuredMessages(snapshot.messages) : undefined,
+        messages: snapshot.messages ? enrichStructuredMessages(snapshot.messages, snapshot.id) : undefined,
         queuedMessages: snapshot.queuedMessages,
         queuedMessageSkills: snapshot.queuedMessageSkills,
         sessionKind: "structured",
@@ -259,7 +259,7 @@ function buildIncrementalStructuredPayload(snapshot, cardDefaults) {
     const messages = snapshot.messages ?? [];
     // Derive semantics from the complete current turn before taking the
     // incremental tail; TaskCreate results can live in an earlier provider frame.
-    const clientMessages = enrichStructuredMessages(messages);
+    const clientMessages = enrichStructuredMessages(messages, snapshot.id);
     const lastTurn = clientMessages.length > 0 ? clientMessages[clientMessages.length - 1] : undefined;
     // Streaming turn (index 0 here) is preserved verbatim; truncation only kicks
     // in if the live response is already bigger than the transport threshold,

package/dist/types.d.ts

@@ -65,6 +65,16 @@ export interface AndroidApkConfig {
     apkDir?: string;
     currentApkFile?: string;
 }
+/**
+ * PTY 归属引擎。`auto` 优先 Rust Render（找到了二进制才用），`rust` 强制 Rust，
+ * `legacy` 保留现有 terminald 行为。仅切换所有权，DB/客户端契约不变。
+ */
+export type RenderEngine = "auto" | "rust" | "legacy";
+export interface RenderConfig {
+    engine: RenderEngine;
+    /** 显式指定 wand-render 可执行文件；留空则按约定顺序自动查找。 */
+    binaryPath?: string;
+}
 export interface MacosDmgConfig {
     enabled?: boolean;
     dmgDir?: string;
@@ -123,6 +133,8 @@ export interface WandConfig {
     android?: AndroidApkConfig;
     macos?: MacosDmgConfig;
     ios?: IosIpaConfig;
+    /** Render（常驻 PTY 持有者）引擎选择。默认 auto。 */
+    render?: RenderConfig;
     /** Default expand/collapse state for card types in structured chat view */
     cardDefaults?: CardExpandDefaults;
     /** 新建会话时默认使用的 Claude 模型（别名或完整 ID）。留空则不传 --model，由 claude 自行决定。 */