pi-web-ui 0.91.0 → 0.92.0

package/dist/server/conversation-read-tool.js

@@ -22,14 +22,23 @@
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { bilingual, pick } from "./i18n.js";
+import { extractTouches, formatTouchEntry, formatTouchesCompact, toolCallRefsOfContent, unionTouchLists, } from "./conversation-touches.js";
+/** 由 content 块提 toolCalls 字段（additive；格式化输出不受影响，见接口注释）。 */
+function fillToolCalls(target, content) {
+    const refs = toolCallRefsOfContent(content);
+    if (refs.length > 0)
+        target.toolCalls = refs;
+}
 /** AgentMessage → 转录最小结构（角色原样保留，内容不动，格式化延后）。 */
 export function toTranscriptInput(m) {
     const role = m.role;
     const r = typeof role === "string" ? role : "unknown";
     const base = { role: r };
     const anyM = m;
-    if (typeof anyM.content !== "undefined")
+    if (typeof anyM.content !== "undefined") {
         base.content = anyM.content;
+        fillToolCalls(base, anyM.content);
+    }
     if (typeof anyM.toolName === "string")
         base.toolName = anyM.toolName;
     if (typeof anyM.isError === "boolean")
@@ -118,8 +127,14 @@ function roleLabel(m) {
         return `tool result${m.toolName ? ` (${m.toolName})` : ""}`;
     return m.role;
 }
+/** 单条消息截断：超出部分标注剩余字符数（调用方一眼知道丢了多少）。 */
+export function truncateCounted(s, cap) {
+    if (s.length <= cap)
+        return s;
+    return `${s.slice(0, cap)}\n… +${s.length - cap} chars`;
+}
 function trunc(s, cap) {
-    return s.length <= cap ? s : `${s.slice(0, cap)}\n… [truncated]`;
+    return truncateCounted(s, cap);
 }
 /** 转录分页格式化：序号形如 [12/135 user]，尾部带翻页提示位（调用方拼 header）。 */
 export function formatTranscript(messages, opts) {
@@ -165,8 +180,10 @@ export function parseTranscriptLines(text) {
         if (e?.type === "message" && e.message && typeof e.message.role === "string") {
             const msg = e.message;
             const m = { role: msg.role };
-            if (typeof msg.content !== "undefined")
+            if (typeof msg.content !== "undefined") {
                 m.content = msg.content;
+                fillToolCalls(m, msg.content);
+            }
             if (typeof msg.toolName === "string")
                 m.toolName = msg.toolName;
             if (typeof msg.isError === "boolean")
@@ -191,6 +208,134 @@ export function parseTranscriptLines(text) {
 function matchesHay(hay, q) {
     return q === "" || hay.toLowerCase().includes(q);
 }
+/** read 选择器（纯函数）：view → query → last 的顺序固定，见注释。 */
+export function selectReadMessages(messages, opts) {
+    const list = Array.isArray(messages) ? messages : [];
+    const view = opts?.view === "full" ? "full" : "chat";
+    const inView = view === "full" ? list : list.filter((m) => m.role === "user" || m.role === "assistant");
+    const q = (opts?.query ?? "").trim().toLowerCase();
+    let selected = inView;
+    let hitIndices = [];
+    if (q) {
+        // 在 view 内按转录文本搜：hitIndices 只记命中（报数/定位用），
+        // selected 是命中 ±1 条上下文展开（去重保序）。
+        const hits = [];
+        const keep = new Set();
+        for (let i = 0; i < inView.length; i++) {
+            if (transcriptText(inView[i]).toLowerCase().includes(q)) {
+                hits.push(i);
+                for (let j = Math.max(0, i - 1); j <= Math.min(inView.length - 1, i + 1); j++)
+                    keep.add(j);
+            }
+        }
+        hitIndices = hits;
+        selected = [...keep].sort((a, b) => a - b).map((i) => inView[i]);
+    }
+    const last = opts?.last;
+    if (typeof last === "number" && Number.isFinite(last)) {
+        const n = Math.min(200, Math.max(1, Math.floor(last)));
+        if (selected.length > n) {
+            selected = selected.slice(selected.length - n);
+            // last 裁掉上下文外层时命中序号跟走（只留仍在选区内的）。
+            if (hitIndices.length > 0) {
+                const keep = new Set(selected);
+                hitIndices = hitIndices.filter((i) => keep.has(inView[i]));
+            }
+        }
+    }
+    return { selected, totalInView: inView.length, hitIndices };
+}
+/** 工具参数里的一句话提示（path/command，单行 ≤80 字符；拿不到就空串）。 */
+function toolHint(args) {
+    if (!args || typeof args !== "object")
+        return "";
+    const a = args;
+    for (const k of ["path", "file_path", "filePath", "command"]) {
+        const v = a[k];
+        if (typeof v === "string" && v.trim()) {
+            const oneLine = v.trim().replace(/\s+/g, " ");
+            return oneLine.length > 80 ? `${oneLine.slice(0, 80)}…` : oneLine;
+        }
+    }
+    return "";
+}
+/** action=status 的摘要器（纯函数）：只读转录，不碰 host。 */
+export function summarizeConversation(messages) {
+    const list = Array.isArray(messages) ? messages : [];
+    let lastTool;
+    let lastAssistant;
+    let lastAskIdx = -1;
+    let lastAskResultIdx = -1;
+    for (let i = 0; i < list.length; i++) {
+        const m = list[i];
+        if (!m || typeof m !== "object")
+            continue;
+        if (m.role === "assistant") {
+            const textParts = [];
+            const calls = toolCallRefsOfContent(m.content);
+            if (m.toolCalls && m.toolCalls.length > 0) {
+                for (const c of m.toolCalls) {
+                    if (c && typeof c.name === "string") {
+                        lastTool = { name: c.name, hint: toolHint(c.args) };
+                        if (c.name === "ask_user_question")
+                            lastAskIdx = i;
+                    }
+                }
+            }
+            else {
+                for (const c of calls) {
+                    lastTool = { name: c.name, hint: toolHint(c.args) };
+                    if (c.name === "ask_user_question")
+                        lastAskIdx = i;
+                }
+            }
+            if (Array.isArray(m.content)) {
+                for (const b of m.content) {
+                    if (b && typeof b === "object" && b.type === "text") {
+                        const t = b.text;
+                        if (typeof t === "string" && t)
+                            textParts.push(t);
+                    }
+                }
+            }
+            const joined = textParts.join("\n").trim();
+            if (joined)
+                lastAssistant = joined;
+        }
+        else if (m.role === "bashExecution" && typeof m.command === "string") {
+            lastTool = { name: "bash", hint: toolHint({ command: m.command }) };
+        }
+        else if (m.role === "toolResult" && m.toolName === "ask_user_question") {
+            lastAskResultIdx = i;
+        }
+    }
+    return { lastTool, lastAssistant, waitingQuestion: lastAskIdx >= 0 && lastAskResultIdx < lastAskIdx };
+}
+/** read 的附加说明行：query 命中位置 + chat 视图裁剪说明（纯函数）。 */
+export function readExtraLines(L, query, sel, rawTotal, view) {
+    const lines = [];
+    const q = query.trim();
+    if (q && sel.hitIndices.length > 0) {
+        const shown = sel.hitIndices.slice(0, 20).map((i) => i + 1);
+        const idx = sel.hitIndices.length > 20 ? `${shown.join("、")}… (+${sel.hitIndices.length - 20})` : shown.join("、");
+        lines.push(pick(L, `在对话内搜「${q}」：命中 ${sel.hitIndices.length} 条（选区第 ${idx} 条），上下文共 ${sel.selected.length} 条。`, `Searched for "${q}": ${sel.hitIndices.length} hit(s) (#${idx} in this selection), ${sel.selected.length} with context.`, "convread.read.query.head", { q, hits: sel.hitIndices.length, indices: idx, shown: sel.selected.length }));
+    }
+    if (view === "chat" && rawTotal > sel.totalInView) {
+        lines.push(pick(L, `（chat 视图只含 user/assistant 共 ${sel.totalInView} 条；另有 ${rawTotal - sel.totalInView} 条工具调用/结果，用 view="full" 看。）`, `(chat view: only user/assistant, ${sel.totalInView} messages; ${rawTotal - sel.totalInView} more tool messages with view="full".)`, "convread.read.chat.note", { chat: sel.totalInView, tools: rawTotal - sel.totalInView }));
+    }
+    return lines.length > 0 ? `\n${lines.join("\n")}` : "";
+}
+/** 认领行格式化（files/status 共用，纯函数；head 文案各调用方自己 pick）。
+ *  style: bullets = 独立成行（files 块用）；inline = 行内逗分（status 一行用）。 */
+export function formatClaimLines(claims, maxItems = 5, style = "bullets") {
+    const list = Array.isArray(claims) ? claims : [];
+    const shown = list.slice(0, Math.max(1, Math.floor(maxItems)));
+    const dash = style === "bullets" ? "- " : "";
+    const lines = shown.map((c) => `${dash}${c.path} · 「${c.ownerTitle}」${c.note ? ` · ${c.note}` : ""}`);
+    if (list.length > shown.length)
+        lines.push(`… (+${list.length - shown.length})`);
+    return lines;
+}
 export function filterRunning(list, query) {
     const q = query.trim().toLowerCase();
     if (!q)
@@ -207,7 +352,14 @@ export function filterHistory(list, query) {
 export function shortPath(p, keep = 48) {
     return p.length <= keep ? p : `…${p.slice(p.length - keep)}`;
 }
-export function makeConversationReadTool(host, lang) {
+/** action=list 的默认条数：历史默认 15（以前无上限，几百条一次吐完）；
+ *  运行中默认不限但给上限（并发对话再多也不会撑爆 details 的 64KB）。 */
+export const HISTORY_LIST_DEFAULT = 15;
+export const RUNNING_LIST_CAP = 50;
+/** action=read 单条消息默认截断（约 600 字符，超出标 “… +N chars”；
+ *  以前默认 2000，一条 bash 输出就能吃掉整个 maxChars 预算）。 */
+export const READ_PER_MSG_CAP = 600;
+export function makeConversationReadTool(host, lang, extras) {
     const getLang = lang ?? (() => "en");
     const text = (t, details = {}) => ({
         content: [{ type: "text", text: t }],
@@ -216,16 +368,22 @@ export function makeConversationReadTool(host, lang) {
     return defineTool({
         name: "conversation_read",
         label: "Read another conversation",
-        description: bilingual('Read ANOTHER conversation\'s messages: a running conversation of this client (including subagents — use its conversation id like "c3", see action=list) or a persisted history session transcript (use its file path). ' +
+        description: bilingual('Read ANOTHER conversation: a running conversation of this client (including subagents — use its conversation id like "c3", see action=list) or a persisted history session transcript (use its file path). ' +
             'Use it when the user references another chat (a quoted conversation, a pasted conversation id, or "see the other chat about X"). ' +
-            "action=list shows running conversations (id, title, project, streaming state) plus history sessions; action=read returns one transcript paged (offset/limit, capped chars — re-call with a larger offset for the rest). " +
+            "action=list shows running conversations plus history sessions (kind=running|history|all, query filter, limit; history defaults to 15). " +
+            'action=read returns one transcript: view=chat (default: only user/assistant text) or full (incl. tool calls/results); last=N takes the latest N messages instead of guessing offset; query searches within the conversation (hits ±1 context); each message is capped (~600 chars, marked "… +N chars"). ' +
+            "action=files lists files the conversation created/modified (with counts). " +
+            "action=status gives a short summary: last tool call, last assistant text, recently touched files, whether it is waiting for a question answer. " +
             "Only sessions from the session list can be read (arbitrary file paths are refused). " +
-            "Live runs in OTHER browser tabs are not readable here — they appear in history once persisted.", "读取**另一个对话**的消息：本客户端的运行中对话（含子代理——用 action=list 查 conversation id，如 c3）或已落盘的历史会话转录（用它的文件 path）。" +
+            "Live runs in OTHER browser tabs are not readable here — they appear in history once persisted.", "读取**另一个对话**：本客户端的运行中对话（含子代理——用 action=list 查 conversation id，如 c3）或已落盘的历史会话转录（用它的文件 path）。" +
             "用户引用了别的对话（引用 chip、粘过来的对话 id、“看看之前那个关于 X 的对话”）时用它。" +
-            "action=list 列运行中对话（id、标题、项目、是否进行中）与历史会话；action=read 取某一份转录（offset/limit 翻页、字符封顶——后文用更大的 offset 再取）。" +
+            "action=list 列运行中对话与历史会话（kind=running|history|all，query 过滤，limit；历史默认 15 条）。" +
+            "action=read 取某一份转录：view=chat（默认：只给 user/assistant 文本）或 full（含工具调用与结果）；last=N 取最新 N 条（不用猜 offset）；query 在对话内搜索（命中 ±1 条上下文）；每条消息独立截断（约 600 字符，超出标 “… +N chars”）。" +
+            "action=files 列该对话创建/修改过的文件（含次数）。" +
+            "action=status 给一两行摘要：最后一次工具调用、最后一句 assistant、最近动过的文件、是否在等用户回答问卷。" +
             "只能读会话列表里的转录（任意文件路径会被拒绝）。" +
             "其他浏览器标签页里的实时运行在这里读不到——它们落盘后会出现在历史里。"),
-        promptSnippet: "read another conversation's messages (running incl. subagents, or history transcript)",
+        promptSnippet: "read another conversation: list/find chats, read transcript (chat view / tail / search), touched files, status summary",
         parameters: Type.Object({
             action: Type.Optional(Type.String({
                 description: 'list = show running conversations + history sessions; read = fetch one transcript. Default "list".',
@@ -233,11 +391,22 @@ export function makeConversationReadTool(host, lang) {
             scope: Type.Optional(Type.String({
                 description: 'list only: "current" = this project, "all" = every project. Default "all".',
             })),
-            query: Type.Optional(Type.String({ description: "list only: case-insensitive filter over id/title/path/first message." })),
+            kind: Type.Optional(Type.String({
+                description: 'list only: "running" | "history" | "all" (which sections to show). Default "all".',
+            })),
+            query: Type.Optional(Type.String({
+                description: "list: case-insensitive filter over id/title/path/first message. read/files: search within the transcript (read returns hits ±1 context).",
+            })),
+            view: Type.Optional(Type.String({
+                description: 'read only: "chat" = only user/assistant text (default, cheap); "full" = incl. tool calls/results.',
+            })),
+            last: Type.Optional(Type.Number({ description: "read only: take the latest N messages (1-200) instead of guessing offset." })),
             id: Type.Optional(Type.String({ description: 'read only: running conversation id (e.g. "c3"), from action=list.' })),
             path: Type.Optional(Type.String({ description: "read only: history session file path, from action=list." })),
             offset: Type.Optional(Type.Number({ description: "read only: first message index (0-based). Default 0." })),
-            limit: Type.Optional(Type.Number({ description: "read only: max messages to return (1-200). Default 50." })),
+            limit: Type.Optional(Type.Number({
+                description: "list: max entries per section (history defaults to 15, running uncapped up to 50). read/files: max messages/entries (1-200, default 50).",
+            })),
             maxChars: Type.Optional(Type.Number({ description: "read only: max characters (1000-60000). Default 20000." })),
         }),
         execute: async (_id, p, _signal, _onUpdate, ctx) => {
@@ -248,50 +417,105 @@ export function makeConversationReadTool(host, lang) {
                     return text(pick(getLang(), `scope 非法：${p.scope}（只能是 current 或 all）。`, `Invalid scope: ${p.scope} (must be "current" or "all").`, "convread.list.bad.scope", { "p.scope": p.scope }));
                 }
                 const scope = scopeRaw;
+                const kindRaw = (p.kind ?? "all").trim().toLowerCase();
+                if (kindRaw !== "running" && kindRaw !== "history" && kindRaw !== "all") {
+                    return text(pick(getLang(), `kind 非法：${p.kind}（只能是 running、history 或 all）。`, `Invalid kind: ${p.kind} (must be "running", "history" or "all").`, "convread.list.bad.kind", { "p.kind": p.kind }));
+                }
+                const kind = kindRaw;
                 const query = typeof p.query === "string" ? p.query : "";
-                const running = filterRunning(host.listRunningConversations(), query);
-                const history = filterHistory(await host.listHistorySessions(scope, ctx.cwd), query);
+                const cap = typeof p.limit === "number" && Number.isFinite(p.limit)
+                    ? Math.min(200, Math.max(1, Math.floor(p.limit)))
+                    : undefined;
+                // kind 过滤掉的一整节直接不取不展（不为了它多一次 I/O）。
+                const running = kind === "history" ? [] : filterRunning(host.listRunningConversations(), query);
+                const history = kind === "running" ? [] : filterHistory(await host.listHistorySessions(scope, ctx.cwd), query);
+                const shownRunning = running.slice(0, cap ?? RUNNING_LIST_CAP);
+                const shownHistory = history.slice(0, cap ?? HISTORY_LIST_DEFAULT);
                 const L = getLang();
-                const runLines = running.map((c) => `- ${c.id} · ${c.title} · ${c.isSubagent ? (L === "zh" ? "子代理" : "subagent") : L === "zh" ? "对话" : "chat"}${c.isStreaming ? (L === "zh" ? "（进行中）" : " (streaming)") : ""} · ${c.messageCount} msgs · ${c.cwd}`);
-                const histLines = history.map((s) => `- ${shortPath(s.path)} · ${s.name || s.firstMessage || (L === "zh" ? "（空对话）" : "(empty)")}${s.messageCount ? ` · ${s.messageCount} msgs` : ""}`);
-                const head = L === "zh"
-                    ? `运行中对话（${running.length}）+ 历史会话（${history.length}，scope=${scope}）：`
-                    : `Running conversations (${running.length}) + history sessions (${history.length}, scope=${scope}):`;
+                const runLines = shownRunning.map((c) => `- ${c.id} · ${c.title} · ${c.isSubagent ? (L === "zh" ? "子代理" : "subagent") : L === "zh" ? "对话" : "chat"}${c.isStreaming ? (L === "zh" ? "（进行中）" : " (streaming)") : ""} · ${c.messageCount} msgs · ${c.cwd}`);
+                const histLines = shownHistory.map((s) => `- ${shortPath(s.path)} · ${s.name || s.firstMessage || (L === "zh" ? "（空对话）" : "(empty)")}${s.messageCount ? ` · ${s.messageCount} msgs` : ""}`);
+                // 超出 cap 时给计数 + 收窄指引（静默丢弃是大忌：调用方会以为这就是全量）。
+                if (running.length > shownRunning.length) {
+                    runLines.push(pick(L, `… 还有 ${running.length - shownRunning.length} 条运行中（用 query 或 limit 收窄）。`, `… ${running.length - shownRunning.length} more running (narrow with query or limit).`, "convread.list.running.more", { n: running.length - shownRunning.length }));
+                }
+                if (history.length > shownHistory.length) {
+                    histLines.push(pick(L, `… 还有 ${history.length - shownHistory.length} 条历史（用 query 或 limit 收窄；默认只给 ${HISTORY_LIST_DEFAULT} 条）。`, `… ${history.length - shownHistory.length} more history (narrow with query or limit; default shows ${HISTORY_LIST_DEFAULT}).`, "convread.list.history.more", { n: history.length - shownHistory.length }));
+                }
+                const head = kind === "running"
+                    ? pick(L, `运行中对话（${running.length}）：`, `Running conversations (${running.length}):`, "convread.list.head.running", { n: running.length })
+                    : kind === "history"
+                        ? pick(L, `历史会话（${history.length}，scope=${scope}）：`, `History sessions (${history.length}, scope=${scope}):`, "convread.list.head.history", { n: history.length })
+                        : pick(L, `运行中对话（${running.length}）+ 历史会话（${history.length}，scope=${scope}）：`, `Running conversations (${running.length}) + history sessions (${history.length}, scope=${scope}):`, "convread.list.head.all", { running: running.length, history: history.length });
                 const runHead = L === "zh" ? "【运行中】" : "[running]";
                 const histHead = L === "zh" ? "【历史】" : "[history]";
                 const empty = L === "zh" ? "（无）" : "(none)";
                 const tail = L === "zh"
-                    ? `读某一份：conversation_read(action="read", id="c…") 或 conversation_read(action="read", path="…")，长转录用 offset/limit 翻页。`
-                    : `To read one: conversation_read(action="read", id="c…") or conversation_read(action="read", path="…"); page long transcripts with offset/limit.`;
-                return text(`${head}\n${runHead}\n${runLines.join("\n") || empty}\n${histHead}\n${histLines.join("\n") || empty}\n${tail}`, { running, history, scope });
+                    ? `读某一份：conversation_read(action="read", id="c…") 或 conversation_read(action="read", path="…")，长转录用 offset/limit 翻页；只看文件用 action="files"，先看摘要再决定读不读用 action="status"。`
+                    : `To read one: conversation_read(action="read", id="c…") or conversation_read(action="read", path="…"); page long transcripts with offset/limit; action="files" lists touched files, action="status" summarizes before you decide to read.`;
+                const sections = kind === "history"
+                    ? `${head}\n${histHead}\n${histLines.join("\n") || empty}`
+                    : kind === "running"
+                        ? `${head}\n${runHead}\n${runLines.join("\n") || empty}`
+                        : `${head}\n${runHead}\n${runLines.join("\n") || empty}\n${histHead}\n${histLines.join("\n") || empty}`;
+                // details 同样有界：只带展示出的条目（历史的 firstMessage 再掐到 160
+                // 字符），以前整量 history 进 details 会撑爆 64KB 被整段丢弃。
+                return text(`${sections}\n${tail}`, {
+                    scope,
+                    kind,
+                    runningTotal: running.length,
+                    historyTotal: history.length,
+                    running: shownRunning,
+                    history: shownHistory.map((s) => ({
+                        ...s,
+                        firstMessage: typeof s.firstMessage === "string" && s.firstMessage.length > 160
+                            ? `${s.firstMessage.slice(0, 160)}…`
+                            : s.firstMessage,
+                    })),
+                    truncated: running.length > shownRunning.length || history.length > shownHistory.length,
+                });
             }
             if (action === "read") {
+                const viewRaw = (p.view ?? "chat").trim().toLowerCase();
+                if (viewRaw !== "chat" && viewRaw !== "full") {
+                    return text(pick(getLang(), `view 非法：${p.view}（只能是 chat 或 full）。`, `Invalid view: ${p.view} (must be "chat" or "full").`, "convread.read.bad.view", { "p.view": p.view }));
+                }
+                const view = viewRaw;
                 const id = typeof p.id === "string" && p.id.trim() ? p.id.trim() : undefined;
                 const path = typeof p.path === "string" && p.path.trim() ? p.path.trim() : undefined;
                 if ((id && path) || (!id && !path)) {
                     return text(pick(getLang(), `action=read 需要且只需要 id 或 path 其中之一（id 读运行中对话，path 读历史转录）。`, `action=read needs exactly one of id or path (id = running conversation, path = history transcript).`, "convread.read.bad.args"));
                 }
-                const opts = { offset: p.offset, limit: p.limit, maxChars: p.maxChars };
+                const query = typeof p.query === "string" ? p.query : "";
+                const opts = { offset: p.offset, limit: p.limit, maxChars: p.maxChars, perMsgCap: READ_PER_MSG_CAP };
                 if (id) {
                     const found = host.readRunningConversation(id);
                     if (!found) {
                         return text(pick(getLang(), `未找到运行中对话 ${id}（可能已关闭；用 action=list 看当前列表，落盘的可按 path 读历史）。`, `Running conversation ${id} not found (may be closed; use action=list for the current list, or read persisted ones by path).`, "convread.read.id.not.found", { id }));
                     }
-                    const f = formatTranscript(found.messages, opts);
+                    const rawTotal = found.messages.length;
+                    const sel = selectReadMessages(found.messages, { view, last: p.last, query });
                     const L = getLang();
+                    if (query.trim() && sel.hitIndices.length === 0) {
+                        return text(pick(L, `在对话内搜「${query.trim()}」：没有命中。换个词，或用 view="full" 把工具输出也纳入搜索。`, `No hits for "${query.trim()}". Try another term, or use view="full" to include tool outputs.`, "convread.read.query.empty", { q: query.trim() }), { id, title: found.title, view, query: query.trim(), hits: 0 });
+                    }
+                    const f = formatTranscript(sel.selected, opts);
                     const head = L === "zh"
                         ? `对话「${found.title}」（id=${id}${found.isSubagent ? "，子代理" : ""}，${found.cwd}，共 ${f.total} 条，${f.from + 1}-${f.to}）：`
                         : `Conversation "${found.title}" (id=${id}${found.isSubagent ? ", subagent" : ""}, ${found.cwd}, ${f.total} messages, showing ${f.from + 1}-${f.to}):`;
+                    const notes = readExtraLines(L, query, sel, rawTotal, view);
                     const more = f.truncated && f.total > 0
                         ? L === "zh"
                             ? `\n…还有后文（offset=${f.to} 再取）。`
                             : `\n…more below (re-call with offset=${f.to}).`
                         : "";
                     const emptyNote = f.total === 0 ? (L === "zh" ? "（该对话暂无消息）" : "(no messages yet)") : "";
-                    return text(`${head}\n${f.text || emptyNote}${more}`, {
+                    return text(`${head}${notes}\n${f.text || emptyNote}${more}`, {
                         id,
                         title: found.title,
+                        view,
+                        ...(query.trim() ? { query: query.trim(), hitIndices: sel.hitIndices.slice(0, 500) } : {}),
                         total: f.total,
+                        rawTotal,
                         from: f.from,
                         to: f.to,
                     });
@@ -300,26 +524,144 @@ export function makeConversationReadTool(host, lang) {
                 if (!found) {
                     return text(pick(getLang(), `读不到历史会话 ${path}（不在会话列表里：只能读 action=list 列出的转录路径）。`, `Cannot read history session ${path} (not in the session list: only transcripts from action=list can be read).`, "convread.read.path.not.found", { path }));
                 }
-                const f = formatTranscript(found.messages, opts);
+                const rawTotal = found.messages.length;
+                const sel = selectReadMessages(found.messages, { view, last: p.last, query });
                 const L = getLang();
+                if (query.trim() && sel.hitIndices.length === 0) {
+                    return text(pick(L, `在对话内搜「${query.trim()}」：没有命中。换个词，或用 view="full" 把工具输出也纳入搜索。`, `No hits for "${query.trim()}". Try another term, or use view="full" to include tool outputs.`, "convread.read.query.empty", { q: query.trim() }), { path: found.sessionPath, title: found.title, view, query: query.trim(), hits: 0 });
+                }
+                const f = formatTranscript(sel.selected, opts);
                 const head = L === "zh"
                     ? `历史会话「${found.title || found.sessionPath}」（${found.cwd}，共 ${f.total} 条，${f.from + 1}-${f.to}）：`
                     : `History session "${found.title || found.sessionPath}" (${found.cwd}, ${f.total} messages, showing ${f.from + 1}-${f.to}):`;
+                const notes = readExtraLines(L, query, sel, rawTotal, view);
                 const more = f.truncated && f.total > 0
                     ? L === "zh"
                         ? `\n…还有后文（offset=${f.to} 再取）。`
                         : `\n…more below (re-call with offset=${f.to}).`
                     : "";
                 const emptyNote = f.total === 0 ? (L === "zh" ? "（该会话暂无消息）" : "(no messages yet)") : "";
-                return text(`${head}\n${f.text || emptyNote}${more}`, {
+                return text(`${head}${notes}\n${f.text || emptyNote}${more}`, {
                     path: found.sessionPath,
                     title: found.title,
+                    view,
+                    ...(query.trim() ? { query: query.trim(), hitIndices: sel.hitIndices.slice(0, 500) } : {}),
                     total: f.total,
+                    rawTotal,
                     from: f.from,
                     to: f.to,
                 });
             }
-            return text(pick(getLang(), `action 非法：${p.action}（只能是 list 或 read）。`, `Invalid action: ${p.action} (must be "list" or "read").`, "convread.bad.action", { "p.action": p.action }));
+            if (action === "files" || action === "status") {
+                const id = typeof p.id === "string" && p.id.trim() ? p.id.trim() : undefined;
+                const path = typeof p.path === "string" && p.path.trim() ? p.path.trim() : undefined;
+                if ((id && path) || (!id && !path)) {
+                    return text(pick(getLang(), `action=${action} 需要且只需要 id 或 path 其中之一（id 读运行中对话，path 读历史转录）。`, `action=${action} needs exactly one of id or path (id = running conversation, path = history transcript).`, action === "files" ? "convread.files.bad.args" : "convread.status.bad.args"));
+                }
+                // 取数（错误复用 read 的 not found 文案：同一个“找不到”语义）。
+                let title = "";
+                let cwd = "";
+                let messages = [];
+                if (id) {
+                    const found = host.readRunningConversation(id);
+                    if (!found) {
+                        return text(pick(getLang(), `未找到运行中对话 ${id}（可能已关闭；用 action=list 看当前列表，落盘的可按 path 读历史）。`, `Running conversation ${id} not found (may be closed; use action=list for the current list, or read persisted ones by path).`, "convread.read.id.not.found", { id }));
+                    }
+                    title = found.title;
+                    cwd = found.cwd;
+                    messages = found.messages;
+                }
+                else {
+                    const found = await host.readHistorySession(path);
+                    if (!found) {
+                        return text(pick(getLang(), `读不到历史会话 ${path}（不在会话列表里：只能读 action=list 列出的转录路径）。`, `Cannot read history session ${path} (not in the session list: only transcripts from action=list can be read).`, "convread.read.path.not.found", { path }));
+                    }
+                    title = found.title || found.sessionPath;
+                    cwd = found.cwd;
+                    messages = found.messages;
+                }
+                const L = getLang();
+                const where = id ? { id } : { path };
+                if (action === "files") {
+                    const fq = (typeof p.query === "string" ? p.query : "").trim().toLowerCase();
+                    // sidecar（压缩前的触碰）∪ 实时转录：union 语义，见 unionTouchLists。
+                    const all = unionTouchLists(host.readTouchSidecar?.(id, path) ?? [], extractTouches(messages));
+                    const filtered = fq ? all.filter((t) => t.path.toLowerCase().includes(fq)) : all;
+                    const listedClaims = (() => {
+                        try {
+                            const rows = extras?.listClaims?.(cwd) ?? [];
+                            return fq ? rows.filter((c) => c.path.toLowerCase().includes(fq)) : rows;
+                        }
+                        catch {
+                            return [];
+                        }
+                    })();
+                    const cap = typeof p.limit === "number" && Number.isFinite(p.limit)
+                        ? Math.min(200, Math.max(1, Math.floor(p.limit)))
+                        : 50;
+                    const shown = filtered.slice(0, cap);
+                    if (filtered.length === 0 && listedClaims.length === 0) {
+                        return text(pick(L, `对话「${title}」还没有可识别的文件写入（只读围观/刚开场/压缩丢了旧记录都有可能）。`, `Conversation "${title}" has no recognizable file writes yet (read-only so far, just started, or pre-compaction touches lost).`, "convread.files.empty", { title }), { ...where, title, total: 0, files: [] });
+                    }
+                    const sections = [];
+                    if (filtered.length > 0) {
+                        const lines = shown.map((t) => `- ${formatTouchEntry(t)}`);
+                        if (filtered.length > shown.length) {
+                            lines.push(pick(L, `… 还有 ${filtered.length - shown.length} 个（用 query 或 limit 收窄）。`, `… ${filtered.length - shown.length} more (narrow with query or limit).`, "convread.files.more", { n: filtered.length - shown.length }));
+                        }
+                        sections.push(`${pick(L, `对话「${title}」创建/修改过的文件（${filtered.length} 个，只算写不算读）：`, `Files created/modified by "${title}" (${filtered.length}, writes only):`, "convread.files.head", { title, total: filtered.length })}\n${lines.join("\n")}`);
+                    }
+                    if (listedClaims.length > 0) {
+                        sections.push(`${pick(L, `本项目认领（${listedClaims.length} 条，绕行参考，先到先得）：`, `Claims in this project (${listedClaims.length}, steer clear, first-wins):`, "convread.files.claims", { total: listedClaims.length })}\n${formatClaimLines(listedClaims).join("\n")}`);
+                    }
+                    return text(sections.join("\n"), {
+                        ...where,
+                        title,
+                        total: filtered.length,
+                        files: shown,
+                        claims: listedClaims.map((c) => ({ path: c.path, ownerTitle: c.ownerTitle })),
+                    });
+                }
+                // action === "status"：一两行摘要，读全文前的低成本侦察。
+                const sum = summarizeConversation(messages);
+                const touched = unionTouchLists(host.readTouchSidecar?.(id, path) ?? [], extractTouches(messages)).slice(0, 6);
+                let statusClaims = [];
+                try {
+                    statusClaims = extras?.listClaims?.(cwd) ?? [];
+                }
+                catch {
+                    statusClaims = [];
+                }
+                const head = pick(L, `对话「${title}」状态（共 ${messages.length} 条）：`, `Status of "${title}" (${messages.length} messages):`, "convread.status.head", { title, total: messages.length });
+                const toolLine = sum.lastTool
+                    ? pick(L, `最后工具：${sum.lastTool.name}${sum.lastTool.hint ? `（${sum.lastTool.hint}）` : ""}。`, `Last tool: ${sum.lastTool.name}${sum.lastTool.hint ? ` (${sum.lastTool.hint})` : ""}.`, "convread.status.last.tool", { name: sum.lastTool.name, hint: sum.lastTool.hint })
+                    : pick(L, `还没调用过工具。`, `No tool calls yet.`, "convread.status.no.tool");
+                const sayLine = sum.lastAssistant
+                    ? pick(L, `最后一句：${truncateCounted(sum.lastAssistant, 200)}`, `Last assistant message: ${truncateCounted(sum.lastAssistant, 200)}`, "convread.status.last.say", { text: truncateCounted(sum.lastAssistant, 200) })
+                    : pick(L, `assistant 还没说过话。`, `No assistant message yet.`, "convread.status.no.say");
+                const touchLine = touched.length > 0
+                    ? pick(L, `最近动过：${formatTouchesCompact(touched, { maxItems: 5 })}。`, `Recently touched: ${formatTouchesCompact(touched, { maxItems: 5 })}.`, "convread.status.touched", { files: formatTouchesCompact(touched, { maxItems: 5 }) })
+                    : pick(L, `最近没动过文件。`, `No files touched recently.`, "convread.status.touched.none");
+                // 等问卷只能从转录推断（ask_user_question 调了没回）；DSH 问卷不走
+                // 工具调用，推断不出 —— 文案写“转录显示”，不夸大。
+                const waitLine = sum.waitingQuestion
+                    ? `\n${pick(L, `⚠ 转录显示它在等用户回答问卷（先回它，再干别的）。`, `⚠ The transcript shows it waiting for a question answer (answer first).`, "convread.status.waiting")}`
+                    : "";
+                // 认领只在有的时候占一行（没有就不提，省 token）。
+                const claimLine = statusClaims.length > 0
+                    ? `\n- ${pick(L, `认领：${formatClaimLines(statusClaims, 3, "inline").join("、")}。`, `Claims: ${formatClaimLines(statusClaims, 3, "inline").join("; ")}.`, "convread.status.claims", { total: statusClaims.length })}`
+                    : "";
+                return text(`${head}\n- ${toolLine}\n- ${sayLine}\n- ${touchLine}${claimLine}${waitLine}`, {
+                    ...where,
+                    title,
+                    lastTool: sum.lastTool,
+                    lastAssistant: sum.lastAssistant ? truncateCounted(sum.lastAssistant, 200) : undefined,
+                    touched: touched.slice(0, 5),
+                    claims: statusClaims.map((c) => ({ path: c.path, ownerTitle: c.ownerTitle })),
+                    waitingQuestion: sum.waitingQuestion,
+                });
+            }
+            return text(pick(getLang(), `action 非法：${p.action}（只能是 list、read、files 或 status）。`, `Invalid action: ${p.action} (must be "list", "read", "files" or "status").`, "convread.bad.action", { "p.action": p.action }));
         },
     });
 }