oh-my-agent-web 0.3.0 → 0.5.0

package/dist/server/engine/dsh-transport.js

@@ -0,0 +1,37 @@
+/**
+ * DSH（DeepSeek Harness）ACP 客户端 = 通用 JSON-RPC stdio + ACP 握手。
+ *
+ * 为什么走 ACP（`dsh --profile acp`）而不是 SDK（`--profile sdk`）或 headless：
+ *   - SDK 面只有 `initialize / session/prompt / shutdown`，没有会话列表/续接/取消/配置/权限，
+ *     这些要么自己读文件、要么自己写插件补（pi-web-ui 就是这么干的，代价是 26 个本地依赖 + 重启换模型）；
+ *   - ACP 原生给了 `session/new|list|resume|close`、`session/set_config_option`（模型/思考档）、
+ *     `session/cancel`、`session/request_permission`，我们只需当客户端；
+ *   - headless 是一次性进程，没有权限问询。
+ *
+ * 协议细节见 ADR-0037；映射规则在 dsh-map.ts（纯函数，单测覆盖）。
+ */
+import { createJsonRpcStdioClient } from "./jsonrpc-stdio.js";
+/** ACP 要求初始化的能力协商；我们不用它的 fs/terminal 桥（工具都在 DSH 进程里跑） */
+const CLIENT_CAPABILITIES = {
+    fs: { readTextFile: false, writeTextFile: false },
+    terminal: false,
+};
+export function createDshClient(options = {}) {
+    return createJsonRpcStdioClient({
+        bin: options.bin ?? "dsh",
+        args: ["--profile", "acp", ...(options.patches ?? []).flatMap((file) => ["--patch", file])],
+        env: options.home ? { DSH_HOME: options.home } : undefined,
+        name: "dsh",
+        log: options.log ?? (() => { }),
+        timeoutMs: options.timeoutMs,
+        // ACP 是标准 JSON-RPC 2.0：帧里必须带 jsonrpc 字段
+        jsonrpc: true,
+        async handshake(call) {
+            const result = (await call("initialize", {
+                protocolVersion: 1,
+                clientCapabilities: CLIENT_CAPABILITIES,
+            }));
+            return { version: result?.agentInfo?.version ?? null };
+        },
+    });
+}

package/dist/server/engine/dsh.js

@@ -0,0 +1,284 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createDshClient } from "./dsh-transport.js";
+import { locateSessionFile, readSessionHeader, readSessionLog } from "./dsh-log.js";
+import { logToTranscript, logToUiMessages, statsFromLog } from "./dsh-history.js";
+import { sanitizeHistoricalActions } from "../markers/actions.js";
+import { currentModelId, currentThinkingLevel, friendlyDshError, modelOptions, modelValueFor, parseModelValue, permissionApprovalRequest, permissionOptionId, pickDefaultModelValue, stopReasonToTurnEnd, thinkingLevels, updateToEvent, } from "./dsh-map.js";
+const MAX_TOOL_FACTS = 200;
+export function createDshEngine(options = {}) {
+    /** DSH_HOME（会话日志与投影缓存都在它下面）；测试可覆盖 */
+    const home = options.home ?? process.env.DSH_HOME?.trim() ?? join(homedir(), ".dsh");
+    const sessionsRoot = join(home, "sessions");
+    const client = options.client ?? createDshClient({ bin: options.bin, home: options.home, log: options.log ?? (() => { }) });
+    const bindings = new Map();
+    const bySession = new Map();
+    const active = new Map();
+    /** toolCallId → 工具事实（权限请求只带 id，名字/参数得从这里补） */
+    const toolFacts = new Map();
+    let approvalHandler = null;
+    let lastError = null;
+    /**
+     * 最近一次拿到的 configOptions（模型/思考档目录）。
+     * 历史会话在 resume 之前没有 config，但选择器不该是空的 —— 用它兜底；
+     * 真正切模型时仍会先 resume（拿不到就报可读错误）。
+     */
+    let lastConfig = [];
+    const rememberTool = (id, update) => {
+        toolFacts.set(id, { title: update.title, rawInput: update.rawInput });
+        if (toolFacts.size > MAX_TOOL_FACTS) {
+            const oldest = toolFacts.keys().next().value;
+            if (oldest)
+                toolFacts.delete(oldest);
+        }
+    };
+    const applyConfig = (binding, config) => {
+        if (!Array.isArray(config) || config.length === 0)
+            return;
+        lastConfig = config;
+        if (binding)
+            binding.config = lastConfig;
+    };
+    const bindingOf = (conversationId) => bindings.get(conversationId) ?? null;
+    /** 会话 id → 日志文件；cwd 未知时按 id 扫一层（历史会话第一次打开就是这条路径） */
+    const logFileOf = (binding, sessionId) => {
+        const id = binding?.sessionId ?? sessionId;
+        const file = locateSessionFile(sessionsRoot, id, binding?.cwd || undefined);
+        if (!file)
+            return null;
+        // 顺手把 cwd 补上：`session/resume` 必须带 cwd，而历史会话的 cwd 只在 header 里
+        if (binding && binding.cwd === "") {
+            const header = readSessionHeader(file);
+            if (typeof header?.cwd === "string")
+                binding.cwd = header.cwd;
+        }
+        return file;
+    };
+    const anyConfig = (conversationId) => {
+        const binding = conversationId ? bindingOf(conversationId) : undefined;
+        if (binding && binding.config.length > 0)
+            return binding.config;
+        return [...bindings.values()].find((item) => item.config.length > 0)?.config ?? lastConfig;
+    };
+    /** 历史会话首次使用时才 resume（ACP 的 resume 会拿到写句柄，所以按需） */
+    const ensureLive = async (conversationId) => {
+        const binding = bindingOf(conversationId);
+        if (!binding)
+            return null;
+        if (binding.live)
+            return binding;
+        const result = await client.request("session/resume", {
+            sessionId: binding.sessionId,
+            cwd: binding.cwd,
+            mcpServers: [],
+        });
+        binding.live = true;
+        applyConfig(binding, result?.configOptions);
+        return binding;
+    };
+    const setOption = async (conversationId, configId, value) => {
+        lastError = null;
+        try {
+            const binding = await ensureLive(conversationId);
+            if (!binding) {
+                lastError = "先打开一个会话";
+                return false;
+            }
+            const result = await client.request("session/set_config_option", {
+                sessionId: binding.sessionId,
+                configId,
+                value,
+            });
+            applyConfig(binding, result?.configOptions);
+            return true;
+        }
+        catch (error) {
+            lastError = friendlyDshError(error);
+            return false;
+        }
+    };
+    const handleNotification = (notification) => {
+        if (notification.method !== "session/update")
+            return;
+        const params = notification.params;
+        const sessionId = typeof params.sessionId === "string" ? params.sessionId : "";
+        const conversationId = bySession.get(sessionId);
+        if (!conversationId)
+            return;
+        const update = (params.update ?? {});
+        if (update.sessionUpdate === "tool_call" && typeof update.toolCallId === "string") {
+            rememberTool(update.toolCallId, update);
+        }
+        if (update.sessionUpdate === "config_option_update") {
+            applyConfig(bindingOf(conversationId) ?? undefined, update.configOptions);
+        }
+        const event = updateToEvent(update);
+        const turn = active.get(conversationId);
+        if (event && turn && !turn.ended)
+            turn.onEvent(event);
+    };
+    const handlePermission = async (id, params) => {
+        const facts = params.toolCall?.toolCallId ? toolFacts.get(params.toolCall.toolCallId) : undefined;
+        const request = permissionApprovalRequest(params, facts);
+        let decision = "deny";
+        if (approvalHandler) {
+            try {
+                decision = await approvalHandler(request);
+            }
+            catch {
+                decision = "deny";
+            }
+        }
+        client.respond(id, { outcome: { outcome: "selected", optionId: permissionOptionId(params.options, decision) } });
+    };
+    client.onNotification(handleNotification);
+    client.onServerRequest((request) => {
+        if (request.method === "session/request_permission") {
+            void handlePermission(request.id, request.params);
+            return;
+        }
+        // 认不出的服务端请求必须回包，否则 DSH 那一轮会一直等
+        client.respondError(request.id, -32601, `agent-web 未实现的服务端请求：${request.method}`);
+    });
+    return {
+        client,
+        version: () => client.version(),
+        async prewarm() {
+            await client.ensureStarted();
+        },
+        async createSession(sessionOptions) {
+            const created = await client.request("session/new", { cwd: sessionOptions.workspace, mcpServers: [] });
+            const sessionId = created?.sessionId;
+            if (!sessionId)
+                throw new Error("dsh 没有返回 sessionId");
+            const binding = {
+                sessionId,
+                cwd: sessionOptions.workspace,
+                live: true,
+                config: created.configOptions ?? [],
+            };
+            bindings.set(sessionOptions.sessionId, binding);
+            bySession.set(sessionId, sessionOptions.sessionId);
+            // 默认模型：优先「账号路由」，否则第一次 prompt 会报 no API key（见 pickDefaultModelValue）
+            const wanted = pickDefaultModelValue(binding.config, options.model);
+            const current = currentModelId(binding.config);
+            if (wanted && parseModelValue(wanted)) {
+                const wantedId = modelOptions(binding.config).find((model) => modelValueFor(binding.config, model.id) === wanted);
+                if (!current || (wantedId && wantedId.id !== current)) {
+                    await setOption(sessionOptions.sessionId, "model", wanted);
+                }
+            }
+            return { sessionPath: null, engineSessionId: sessionId };
+        },
+        async openSession(openOptions) {
+            const sessionId = openOptions.engineSessionId ?? openOptions.sessionPath ?? openOptions.sessionId;
+            const binding = { sessionId, cwd: openOptions.cwd ?? "", live: false, config: [] };
+            bindings.set(openOptions.sessionId, binding);
+            bySession.set(sessionId, openOptions.sessionId);
+        },
+        async sendMessage(sessionId, text, onEvent) {
+            const binding = await ensureLive(sessionId).catch((error) => {
+                throw new Error(friendlyDshError(error));
+            });
+            if (!binding)
+                throw new Error("DSH 会话还没准备好（先新建一个会话）");
+            const turn = { onEvent, ended: false };
+            active.set(sessionId, turn);
+            try {
+                const result = await client.request("session/prompt", { sessionId: binding.sessionId, prompt: [{ type: "text", text }] }, 
+                // 一轮跑很久是正常的（有工具调用）：给 30 分钟，别用默认 30 秒掐掉
+                { timeoutMs: 30 * 60 * 1000 });
+                if (!turn.ended)
+                    onEvent({ type: "turn_end", reason: stopReasonToTurnEnd(result?.stopReason) });
+            }
+            finally {
+                turn.ended = true;
+                active.delete(sessionId);
+            }
+        },
+        async interrupt(sessionId) {
+            const binding = bindingOf(sessionId);
+            if (!binding)
+                return;
+            // ACP 里 cancel 是**通知**（无 id）：发成请求会被当成未知方法丢掉 → 停止按钮没反应
+            client.notify("session/cancel", { sessionId: binding.sessionId });
+        },
+        /** 不看了：关掉会话释放写句柄（DSH 自己的 web/tui 才能打开它） */
+        async parkSession(sessionId) {
+            const binding = bindingOf(sessionId);
+            if (!binding || !binding.live)
+                return;
+            binding.live = false;
+            await client.request("session/close", { sessionId: binding.sessionId }).catch(() => undefined);
+        },
+        async closeSession(sessionId) {
+            await this.parkSession?.(sessionId);
+            const binding = bindingOf(sessionId);
+            bindings.delete(sessionId);
+            if (binding)
+                bySession.delete(binding.sessionId);
+        },
+        async dispose() {
+            lastConfig = [];
+            bindings.clear();
+            bySession.clear();
+            active.clear();
+            toolFacts.clear();
+            client.close();
+        },
+        setApprovalHandler(handler) {
+            approvalHandler = handler;
+        },
+        async listModels(sessionId) {
+            return modelOptions(anyConfig(sessionId));
+        },
+        async switchModel(sessionId, modelId) {
+            const value = modelValueFor(anyConfig(sessionId), modelId);
+            if (!value) {
+                lastError = `这个模型不在 DSH 的可选列表里：${modelId}`;
+                return false;
+            }
+            return setOption(sessionId, "model", value);
+        },
+        async currentModel(sessionId) {
+            const parsed = parseModelValue(anyConfig(sessionId).find((option) => option.id === "model")?.currentValue);
+            return parsed;
+        },
+        async sessionModel(sessionId) {
+            return this.currentModel?.(sessionId) ?? null;
+        },
+        async listThinkingLevels(sessionId) {
+            return thinkingLevels(anyConfig(sessionId));
+        },
+        async getThinkingLevel(sessionId) {
+            return currentThinkingLevel(anyConfig(sessionId));
+        },
+        async setThinkingLevel(sessionId, level) {
+            return setOption(sessionId, "reasoning_effort", level);
+        },
+        lastError: () => lastError,
+        /**
+         * 历史回放：ACP 不支持 `session/load`，所以读 DSH 自己的 v4 日志
+         * （多帧 zstd → 事件流 → 消息块；规则见 dsh-history.ts）。
+         */
+        async readUiMessages(sessionId) {
+            const file = logFileOf(bindingOf(sessionId), sessionId);
+            if (!file)
+                return [];
+            return sanitizeHistoricalActions(logToUiMessages(readSessionLog(file)));
+        },
+        async readTranscript(sessionId) {
+            const file = logFileOf(bindingOf(sessionId), sessionId);
+            if (!file)
+                return [];
+            return logToTranscript(readSessionLog(file));
+        },
+        /** 用量统计：四桶来自 `assistant/message.data.usage`，不依赖 ACP 的 usage_update */
+        async sessionStats(sessionId) {
+            const file = logFileOf(bindingOf(sessionId), sessionId);
+            if (!file)
+                return null;
+            return statsFromLog(readSessionLog(file));
+        },
+    };
+}

package/dist/server/engine/fake.js

@@ -0,0 +1,231 @@
+const BIG_OUTPUT_CHARS = 200 * 1024;
+/** 触发词 → 脚本。默认行为：把用户输入原样念一遍，证明「逐字说话」。 */
+export function planFor(text) {
+    const key = text.toLowerCase();
+    if (key.includes("boom")) {
+        return [
+            { kind: "text", text: "好，我准备炸一下试试：\n" },
+            { kind: "error", code: "fake.boom", message: "假引擎按剧本报错了" },
+        ];
+    }
+    if (key.includes("approve")) {
+        return [
+            { kind: "text", text: "这一步要写文件，按规矩先问你一下：\n" },
+            {
+                kind: "approval",
+                toolName: "write_file",
+                argsSummary: 'path="docs/notes.md", bytes=128',
+                scopeKey: "write_file|/Users/me/code/agent-web/docs",
+                scopeHint: "目录 /Users/me/code/agent-web/docs",
+                riskNote: "写文件会改动磁盘内容，确认后才能执行",
+            },
+            { kind: "text", text: "（按你的决定，我要么继续、要么收手。）\n" },
+        ];
+    }
+    if (key.includes("huge")) {
+        return [
+            { kind: "text", text: "准备吐一大坨输出，看看截断提示对不对：\n" },
+            {
+                kind: "tool",
+                name: "run_command",
+                argsSummary: "cat very-big.log",
+                output: "x".repeat(BIG_OUTPUT_CHARS),
+            },
+            { kind: "text", text: "上面这段应该被截断了。\n" },
+        ];
+    }
+    if (key.includes("fail")) {
+        return [
+            { kind: "text", text: "跑一下测试：\n" },
+            {
+                kind: "tool",
+                name: "run_command",
+                argsSummary: "npm test",
+                output: "1 test failed: 期望 42 实际 43\n",
+                exitCode: 1,
+            },
+            { kind: "text", text: "失败了，退出码 1。\n" },
+        ];
+    }
+    if (key.includes("tool")) {
+        return [
+            { kind: "text", text: "我先看一下这个文件：\n" },
+            { kind: "tool", name: "read_file", argsSummary: 'path="server/index.ts"', output: "export const x = 1;\n" },
+            { kind: "text", text: "看完了。\n" },
+        ];
+    }
+    if (key.includes("slow")) {
+        const chunks = Array.from({ length: 40 }, (_, i) => `第 ${i + 1} 块 … `);
+        return [{ kind: "text", text: "慢慢说：\n" }, ...chunks.map((chunk) => ({ kind: "text", text: chunk }))];
+    }
+    return [
+        { kind: "text", text: `收到：「${text}」。\n这是假引擎在逐字说话：零 token 的测试替身，没有调用任何模型。\n` },
+        // 建议操作（ADR-0022）：默认剧本就带上，方便零 token 验证这条链路
+        { kind: "text", text: "\n[[action:suggest:继续]]\n[[action:suggest:总结一下,prompt=用三句话总结刚才的内容]]\n" },
+    ];
+}
+const sleep = (ms) => (ms <= 0 ? Promise.resolve() : new Promise((resolve) => setTimeout(resolve, ms)));
+export function createFakeEngine(options = {}) {
+    const chunkDelayMs = options.chunkDelayMs ?? 18;
+    const chunkChars = options.chunkChars ?? 6;
+    const slowChunkDelayMs = options.slowChunkDelayMs ?? 250;
+    /** 会话表：**必须先 createSession**，否则 sendMessage 报 engine.no_session（与真引擎一致） */
+    const sessions = new Map();
+    const interrupted = new Set();
+    /** 假引擎自己的模型状态（只为了让 switchModel 有地方记） */
+    const models = new Map();
+    /** 测试钩子：宿主交给引擎的图片（ADR-0020 §P3） */
+    const receivedImages = [];
+    /** switchModel 的调用记录：断言「新会话按项目的默认模型起步」 */
+    const switchedModels = [];
+    let approvalHandler = null;
+    let toolCallSeq = 0;
+    async function streamText(sessionId, text, onEvent, slow) {
+        const buffer = sessions.get(sessionId)?.transcript;
+        for (let index = 0; index < text.length; index += chunkChars) {
+            if (interrupted.has(sessionId))
+                return false;
+            const chunk = text.slice(index, index + chunkChars);
+            onEvent({ type: "text_delta", text: chunk });
+            buffer?.push({ role: "assistant", text: chunk, ts: Date.now() });
+            await sleep(slow ? slowChunkDelayMs : chunkDelayMs);
+        }
+        return true;
+    }
+    return {
+        version: () => "fake",
+        async createSession(sessionOptions) {
+            sessions.set(sessionOptions.sessionId, {
+                workspace: sessionOptions.workspace,
+                transcript: [],
+                sessionPath: `fake-sessions/${sessionOptions.sessionId}.jsonl`,
+            });
+            return { sessionPath: `fake-sessions/${sessionOptions.sessionId}.jsonl` };
+        },
+        /** 打开已有会话（ADR-0021 §2）：假引擎没有真文件，只登记「已打开」 */
+        async openSession(openOptions) {
+            if (!sessions.has(openOptions.sessionId)) {
+                sessions.set(openOptions.sessionId, {
+                    workspace: options.workspaceHint ?? "/tmp/agent-web-fake",
+                    transcript: [],
+                    sessionPath: openOptions.sessionPath ?? null,
+                });
+            }
+        },
+        async readUiMessages(sessionId) {
+            const session = sessions.get(sessionId);
+            if (!session)
+                return [];
+            return session.transcript.map((message, index) => ({
+                id: `fake-${sessionId}-${index}`,
+                role: message.role,
+                ts: message.ts,
+                blocks: [{ kind: "text", text: message.text }],
+            }));
+        },
+        async sendMessage(sessionId, text, onEvent, messageOptions) {
+            // 记下宿主交给引擎的图片（测试用；ADR-0020 §P3 的视觉注入）
+            if (messageOptions?.images?.length)
+                receivedImages.push(...messageOptions.images);
+            // 生命周期忠实于真引擎：**没有 createSession 就没有会话**（ADR-0018）
+            const session = sessions.get(sessionId);
+            if (!session) {
+                onEvent({ type: "error", code: "engine.no_session", message: `引擎里没有这个会话：${sessionId}` });
+                onEvent({ type: "turn_end", reason: "error" });
+                return;
+            }
+            const transcript = session.transcript;
+            transcript.push({ role: "user", text, ts: Date.now() });
+            const slow = text.toLowerCase().includes("slow");
+            // 中断标志只在**回合结束时**清理（不能在建回合时清）：
+            // 宿主可能在「回合已开跑但还没进到引擎」的窗口里发来中断，那时它必须仍然生效。
+            try {
+                for (const step of planFor(text)) {
+                    if (interrupted.has(sessionId)) {
+                        onEvent({ type: "turn_end", reason: "interrupted" });
+                        return;
+                    }
+                    if (step.kind === "text") {
+                        if (!(await streamText(sessionId, step.text, onEvent, slow))) {
+                            onEvent({ type: "turn_end", reason: "interrupted" });
+                            return;
+                        }
+                        continue;
+                    }
+                    if (step.kind === "tool") {
+                        const toolCallId = `fake-tool-${++toolCallSeq}`;
+                        onEvent({ type: "tool_start", toolCallId, name: step.name, argsSummary: step.argsSummary });
+                        await sleep(Math.max(chunkDelayMs, 20));
+                        onEvent({
+                            type: "tool_end",
+                            toolCallId,
+                            status: step.exitCode ? "failed" : "ok",
+                            output: step.output,
+                            ...(step.exitCode === undefined ? {} : { exitCode: step.exitCode }),
+                        });
+                        continue;
+                    }
+                    if (step.kind === "error") {
+                        onEvent({ type: "error", code: step.code, message: step.message });
+                        onEvent({ type: "turn_end", reason: "error" });
+                        return;
+                    }
+                    // 审批：把决定权交回宿主（ADR-0006）
+                    const decision = approvalHandler
+                        ? await approvalHandler({
+                            toolName: step.toolName,
+                            argsSummary: step.argsSummary,
+                            scopeKey: step.scopeKey,
+                            scopeHint: step.scopeHint,
+                            riskNote: step.riskNote,
+                        })
+                        : "deny";
+                    onEvent({ type: "text_delta", text: `审批结果：${decision}\n` });
+                }
+                onEvent({ type: "turn_end", reason: "done" });
+            }
+            finally {
+                interrupted.delete(sessionId);
+            }
+        },
+        async listModels() {
+            // 假引擎固定给两个模型（零 token 也能验证「选模型」这条链路）
+            return [
+                { id: "fake/alpha", label: "Fake Alpha", current: true },
+                { id: "fake/beta", label: "Fake Beta", current: false },
+            ];
+        },
+        async switchModel(sessionId, modelId) {
+            models.set("current", modelId);
+            switchedModels.push({ sessionId, modelId });
+            return true;
+        },
+        async closeSession(sessionId) {
+            sessions.delete(sessionId);
+        },
+        async interrupt(sessionId) {
+            interrupted.add(sessionId);
+        },
+        async readTranscript(sessionId) {
+            return [...(sessions.get(sessionId)?.transcript ?? [])];
+        },
+        setApprovalHandler(handler) {
+            approvalHandler = handler;
+        },
+        /** 测试钩子：宿主交给引擎的图片（ADR-0020 §P3） */
+        images() {
+            return receivedImages;
+        },
+        /** 测试钩子：看会话表（含 createSession 时收到的历史） */
+        sessions() {
+            return sessions;
+        },
+        switchedModels: () => [...switchedModels],
+        reset() {
+            sessions.clear();
+            interrupted.clear();
+            approvalHandler = null;
+            switchedModels.length = 0;
+        },
+    };
+}