@armadra/agent 0.3.0 → 0.5.0

package/dist/session/export.js

@@ -0,0 +1,187 @@
+/**
+ * 会话导出（`ama sessions export`）：md（给人读）/ json（结构化）/ jsonl（原格式子集）。[W4-D]
+ *
+ * - 范围：`leaf` = 根 → 当前叶子的分支（同 `/tree` 当前位置），`all` = 文件里全部条目（文件顺序）。
+ * - 三种格式都先脱敏（redact.ts）：json / jsonl 对每个字符串值做（图片 base64 保留），md 对成文做。
+ * - md：用户 / 助手消息、工具调用（参数 JSON 截到 500 字符）与结果（截到 2000 字符）、压缩与分支摘要、
+ *   末尾用量合计；思考块与 system 消息不写；图片写成占位 `[图片 image/png]`。
+ * - jsonl：头 + 所选条目，形状与会话文件相同（可以再被 ama 读），不带 leaf 行。
+ */
+import { contentImages, contentText, numberUserMessages } from "./reuse.js";
+import { redactSecrets, redactValue } from "./redact.js";
+import { indexEntries, pathToRoot } from "./tree.js";
+export function selectEntries(input, branch) {
+    return branch === "all"
+        ? [...input.entries]
+        : pathToRoot(indexEntries(input.entries), input.leaf);
+}
+export function usageTotals(entries) {
+    const totals = { requests: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+    let cost = 0;
+    let costed = 0;
+    const add = (usage) => {
+        if (usage === undefined)
+            return;
+        totals.requests++;
+        totals.input += usage.input;
+        totals.output += usage.output;
+        totals.cacheRead += usage.cacheRead;
+        totals.cacheWrite += usage.cacheWrite;
+        if (usage.cost !== undefined) {
+            cost += usage.cost.total;
+            costed++;
+        }
+    };
+    for (const entry of entries) {
+        if (entry.type === "message" && entry.message.role === "assistant")
+            add(entry.message.usage);
+        else if (entry.type === "usage")
+            add(entry.usage);
+        else if (entry.type === "compaction" || entry.type === "branch_summary")
+            add(entry.usage);
+    }
+    if (costed > 0)
+        totals.cost = cost;
+    return totals;
+}
+function sessionName(entries) {
+    let name;
+    for (const entry of entries)
+        if (entry.type === "session_info")
+            name = entry.name;
+    return name;
+}
+function truncate(text, max) {
+    return text.length > max ? `${text.slice(0, max)}\n…（截断，原长 ${text.length} 字符）` : text;
+}
+function fence(text, lang = "") {
+    let ticks = "```";
+    while (text.includes(ticks))
+        ticks += "`";
+    return `${ticks}${lang}\n${text}\n${ticks}`;
+}
+function time(iso) {
+    return iso.replace("T", " ").replace(/\.\d+Z$|Z$/, "");
+}
+function imagesNote(content) {
+    return contentImages(content)
+        .map((image) => `[图片 ${image.mimeType}]`)
+        .join(" ");
+}
+export function renderMarkdown(input, branch) {
+    const entries = selectEntries(input, branch);
+    const numbers = new Map(numberUserMessages(input.entries).map((u) => [u.entryId, u.n]));
+    const name = sessionName(input.entries);
+    const out = [
+        `# ${name ?? `会话 ${input.header.id.slice(0, 8)}`}`,
+        "",
+        `- id：${input.header.id}`,
+        `- 目录：${input.header.cwd}`,
+        `- 创建：${time(input.header.timestamp)}`,
+        `- 范围：${branch === "all" ? "全部条目" : "当前分支"}（${entries.length} 条条目）`,
+        ...(input.header.parentSession !== undefined
+            ? [`- 来源会话：${input.header.parentSession}`]
+            : []),
+        "",
+    ];
+    for (const entry of entries) {
+        switch (entry.type) {
+            case "message": {
+                const m = entry.message;
+                if (m.role === "user") {
+                    const n = numbers.get(entry.id);
+                    const origin = m.origin;
+                    out.push(`## 用户${n !== undefined ? ` #${n}` : ""}${origin !== undefined ? `（${origin}）` : ""} · ${time(entry.timestamp)}`, "");
+                    const text = contentText(m.content);
+                    if (text !== "")
+                        out.push(text, "");
+                    const images = imagesNote(m.content);
+                    if (images !== "")
+                        out.push(images, "");
+                }
+                else if (m.role === "assistant") {
+                    out.push(`## 助手 · ${m.provider}/${m.model} · ${time(entry.timestamp)}`, "");
+                    for (const block of m.content) {
+                        if (block.type === "text" && block.text.trim() !== "")
+                            out.push(block.text, "");
+                        if (block.type === "toolCall") {
+                            out.push(`**工具调用** \`${block.name}\``, "", fence(truncate(JSON.stringify(block.arguments, null, 2), 500), "json"), "");
+                        }
+                    }
+                    if (m.stopReason === "error" || m.stopReason === "aborted") {
+                        out.push(`> 停止：${m.stopReason}${m.errorMessage !== undefined ? ` · ${m.errorMessage}` : ""}`, "");
+                    }
+                }
+                else if (m.role === "toolResult") {
+                    out.push(`**结果** \`${m.toolName}\`${m.isError ? "（出错）" : ""}`, "", fence(truncate(contentText(m.content), 2000)), "");
+                    const images = imagesNote(m.content);
+                    if (images !== "")
+                        out.push(images, "");
+                }
+                break;
+            }
+            case "compaction":
+                out.push(`## 压缩摘要 · ${time(entry.timestamp)}`, "", entry.summary, "");
+                break;
+            case "branch_summary":
+                out.push(`## 分支摘要 · ${time(entry.timestamp)}`, "", entry.summary, "");
+                break;
+            case "custom_message":
+                if (entry.display) {
+                    out.push(`## ${entry.customType} · ${time(entry.timestamp)}`, "");
+                    out.push(contentText(entry.content), "");
+                }
+                break;
+            case "model_change":
+                out.push(`_切换模型：${entry.provider}/${entry.modelId}${entry.channel !== undefined ? `@${entry.channel}` : ""}_`, "");
+                break;
+            default:
+                break;
+        }
+    }
+    const usage = usageTotals(entries);
+    out.push("## 用量", "", "| 请求 | 输入 | 输出 | 缓存读 | 缓存写 | 费用 |", "| ---: | ---: | ---: | ---: | ---: | ---: |", `| ${usage.requests} | ${usage.input} | ${usage.output} | ${usage.cacheRead} | ${usage.cacheWrite} | ${usage.cost !== undefined ? `$${usage.cost.toFixed(4)}` : "—"} |`, "");
+    return redactSecrets(out.join("\n"));
+}
+export function renderJson(input, branch) {
+    const entries = selectEntries(input, branch);
+    const selected = new Set(entries.map((e) => e.id));
+    const name = sessionName(input.entries);
+    const session = {
+        id: input.header.id,
+        cwd: input.header.cwd,
+        createdAt: input.header.timestamp,
+        agent: input.header.agent,
+    };
+    if (name !== undefined)
+        session["name"] = name;
+    if (input.header.parentSession !== undefined)
+        session["parentSession"] = input.header.parentSession;
+    const doc = {
+        format: "ama.session-export",
+        version: 1,
+        session,
+        branch,
+        leafId: input.leaf,
+        userMessages: numberUserMessages(input.entries)
+            .filter((u) => selected.has(u.entryId))
+            .map((u) => ({ n: u.n, entryId: u.entryId })),
+        usage: usageTotals(entries),
+        entries,
+    };
+    return JSON.stringify(redactValue(doc), null, 2) + "\n";
+}
+export function renderJsonl(input, branch) {
+    const lines = [input.header, ...selectEntries(input, branch)].map((line) => JSON.stringify(redactValue(line)));
+    return lines.join("\n") + "\n";
+}
+export function renderExport(input, format, branch) {
+    switch (format) {
+        case "md":
+            return renderMarkdown(input, branch);
+        case "json":
+            return renderJson(input, branch);
+        case "jsonl":
+            return renderJsonl(input, branch);
+    }
+}

package/dist/session/redact.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 导出前的机密脱敏（`ama sessions export`）。[W4-D]
+ *
+ * 只认「形态」：常见 key / token 前缀（sk-…、sk-ant-…、ghp_…、github_pat_…、xox?-…、AIza…、
+ * AKIA…、npm_…）、JWT、`Bearer` / `Basic` 凭据、PEM 私钥块，以及 `apiKey` / `secret` / `token` /
+ * `password` / `authorization` 之后紧跟 `:` 或 `=` 的值。命中的部分换成 `[REDACTED]`
+ * （键名与 Bearer 之类的前缀保留，便于读者知道那里原来有什么）。宁可多遮，不做熵判断。
+ */
+export declare const REDACTED = "[REDACTED]";
+export declare function redactSecrets(text: string): string;
+/**
+ * 深拷贝并对全部字符串值脱敏；键名像机密（如 `apiKey`、`authToken`）的字符串值整段遮掉；
+ * 图片块的 base64 `data` 原样保留（不会是机密，替换会弄坏图片）。
+ */
+export declare function redactValue<T>(value: T): T;

package/dist/session/redact.js

@@ -0,0 +1,55 @@
+/**
+ * 导出前的机密脱敏（`ama sessions export`）。[W4-D]
+ *
+ * 只认「形态」：常见 key / token 前缀（sk-…、sk-ant-…、ghp_…、github_pat_…、xox?-…、AIza…、
+ * AKIA…、npm_…）、JWT、`Bearer` / `Basic` 凭据、PEM 私钥块，以及 `apiKey` / `secret` / `token` /
+ * `password` / `authorization` 之后紧跟 `:` 或 `=` 的值。命中的部分换成 `[REDACTED]`
+ * （键名与 Bearer 之类的前缀保留，便于读者知道那里原来有什么）。宁可多遮，不做熵判断。
+ */
+export const REDACTED = "[REDACTED]";
+const TOKEN_PATTERNS = [
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+    /\bsk-[A-Za-z0-9_-]{16,}/g,
+    /\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})/g,
+    /\bxox[abprs]-[A-Za-z0-9-]{10,}/g,
+    /\bAIza[0-9A-Za-z_-]{30,}/g,
+    /\bAKIA[0-9A-Z]{16}\b/g,
+    /\bnpm_[A-Za-z0-9]{30,}/g,
+    /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g,
+];
+const SCHEME = /\b(Bearer|Basic)(\s+)[A-Za-z0-9._~+/=-]{12,}/g;
+const ASSIGNMENT = /\b([A-Za-z0-9_-]*(?:api[_-]?key|apikey|secret|token|password|passwd|authorization))(["']?\s*[:=]\s*["']?)([^\s"',;}{)]{8,})/gi;
+export function redactSecrets(text) {
+    let out = text;
+    for (const pattern of TOKEN_PATTERNS)
+        out = out.replace(pattern, REDACTED);
+    out = out.replace(SCHEME, (_m, scheme, space) => `${scheme}${space}${REDACTED}`);
+    out = out.replace(ASSIGNMENT, (match, key, sep, value) => value === REDACTED || value.startsWith(REDACTED) ? match : `${key}${sep}${REDACTED}`);
+    return out;
+}
+const SECRET_KEY = /(?:api[_-]?key|apikey|secret|token|password|passwd|authorization)$/i;
+/**
+ * 深拷贝并对全部字符串值脱敏；键名像机密（如 `apiKey`、`authToken`）的字符串值整段遮掉；
+ * 图片块的 base64 `data` 原样保留（不会是机密，替换会弄坏图片）。
+ */
+export function redactValue(value) {
+    if (typeof value === "string")
+        return redactSecrets(value);
+    if (Array.isArray(value))
+        return value.map((item) => redactValue(item));
+    if (typeof value === "object" && value !== null) {
+        const record = value;
+        const image = record["type"] === "image";
+        const out = {};
+        for (const [key, item] of Object.entries(record)) {
+            if (image && key === "data")
+                out[key] = item;
+            else if (typeof item === "string" && item.length >= 8 && SECRET_KEY.test(key))
+                out[key] = REDACTED;
+            else
+                out[key] = redactValue(item);
+        }
+        return out;
+    }
+    return value;
+}

package/dist/session/reuse.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 会话复用：用户消息编号与 `--from <id>[#n]`。[W4-D]
+ *
+ * - 编号 = 文件里第几条 `role: "user"` 的消息（1 起，含 steer / followUp / host 注入），与分支无关、
+ *   只追加所以稳定；`ama sessions show` 列出，`ama sessions search` 的命中也给出同样的编号。
+ * - `--from <id>`（不带 `#n`）取文件里最后一条用户消息。
+ * - 取出的是那条消息的文本（多个文本块用空行连接）与图片块。
+ */
+import type { ImageBlock } from "../ai/types.js";
+import type { SessionEntry } from "./types.js";
+export interface NumberedUserMessage {
+    n: number;
+    entryId: string;
+    timestamp: string;
+    text: string;
+    images: ImageBlock[];
+    origin?: string;
+}
+/** 内容 → 纯文本（文本块用空行连接；不含图片）。 */
+export declare function contentText(content: unknown): string;
+export declare function contentImages(content: unknown): ImageBlock[];
+export declare function numberUserMessages(entries: readonly SessionEntry[]): NumberedUserMessage[];
+/** `abc123#4` → `{ id: "abc123", n: 4 }`；`abc123` → `{ id }`。 */
+export declare function parseFromSpec(spec: string): {
+    id: string;
+    n?: number;
+};
+export interface FromMessage extends NumberedUserMessage {
+    sessionId: string;
+    file: string;
+}
+/** 在会话目录里找 `--from` 指向的用户消息；找不到会话 → session_not_found，编号越界 → 用法错误。 */
+export declare function resolveFromMessage(root: string, spec: string, cwd?: string): FromMessage;

package/dist/session/reuse.js

@@ -0,0 +1,86 @@
+/**
+ * 会话复用：用户消息编号与 `--from <id>[#n]`。[W4-D]
+ *
+ * - 编号 = 文件里第几条 `role: "user"` 的消息（1 起，含 steer / followUp / host 注入），与分支无关、
+ *   只追加所以稳定；`ama sessions show` 列出，`ama sessions search` 的命中也给出同样的编号。
+ * - `--from <id>`（不带 `#n`）取文件里最后一条用户消息。
+ * - 取出的是那条消息的文本（多个文本块用空行连接）与图片块。
+ */
+import { AmaError } from "../errors.js";
+import { findSessionFileReadOnly, readSessionReadOnly } from "./scan.js";
+/** 内容 → 纯文本（文本块用空行连接；不含图片）。 */
+export function contentText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .filter((block) => typeof block === "object" &&
+        block !== null &&
+        block.type === "text" &&
+        typeof block.text === "string")
+        .map((block) => block.text)
+        .join("\n\n");
+}
+export function contentImages(content) {
+    if (!Array.isArray(content))
+        return [];
+    return content.filter((block) => typeof block === "object" &&
+        block !== null &&
+        block.type === "image" &&
+        typeof block.data === "string");
+}
+export function numberUserMessages(entries) {
+    const out = [];
+    for (const entry of entries) {
+        if (entry.type !== "message" || entry.message.role !== "user")
+            continue;
+        const message = entry.message;
+        const item = {
+            n: out.length + 1,
+            entryId: entry.id,
+            timestamp: entry.timestamp,
+            text: contentText(message.content),
+            images: contentImages(message.content),
+        };
+        if (typeof message.origin === "string")
+            item.origin = message.origin;
+        out.push(item);
+    }
+    return out;
+}
+/** `abc123#4` → `{ id: "abc123", n: 4 }`；`abc123` → `{ id }`。 */
+export function parseFromSpec(spec) {
+    const at = spec.lastIndexOf("#");
+    if (at < 0) {
+        if (spec.trim() === "")
+            throw new AmaError("invalid_arguments", "--from 需要会话 id", { exitCode: 2 });
+        return { id: spec };
+    }
+    const id = spec.slice(0, at);
+    const raw = spec.slice(at + 1);
+    const n = Number(raw);
+    if (id === "" || !/^\d+$/.test(raw) || n < 1) {
+        throw new AmaError("invalid_arguments", `--from 应为 <会话 id> 或 <会话 id>#<编号>（收到 ${spec}）`, {
+            exitCode: 2,
+        });
+    }
+    return { id, n };
+}
+/** 在会话目录里找 `--from` 指向的用户消息；找不到会话 → session_not_found，编号越界 → 用法错误。 */
+export function resolveFromMessage(root, spec, cwd) {
+    const { id, n } = parseFromSpec(spec);
+    const file = findSessionFileReadOnly(root, id, cwd);
+    const session = readSessionReadOnly(file);
+    const messages = numberUserMessages(session.entries);
+    if (messages.length === 0) {
+        throw new AmaError("invalid_arguments", `会话 ${session.header.id} 没有用户消息`, {
+            exitCode: 2,
+        });
+    }
+    const picked = n === undefined ? messages.at(-1) : messages[n - 1];
+    if (picked === undefined) {
+        throw new AmaError("invalid_arguments", `会话 ${session.header.id} 只有 ${messages.length} 条用户消息（收到 #${n}）`, { exitCode: 2 });
+    }
+    return { ...picked, sessionId: session.header.id, file };
+}

package/dist/session/scan.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 会话目录的只读扫描（`ama stats`、`ama sessions search|export`、`--from`）。[W4-D]
+ *
+ * 与 store.ts / manager.ts 的区别：这里**从不加锁、不修复、不写文件**——正在运行的会话也能读。
+ * - `sessionFilesInScope`：按 cwd（只看它的编码子目录）或全部子目录（跳过 `.trash`）列文件，最新在前；
+ * - `forEachLine`：按行回调（不先 split 出整个数组）；
+ * - `lineType`：ama 写入的行以 `{"type":"…"` 开头（manager 的 append 把 type 放在第一个键），
+ *   据此不解析就能跳过不需要的行；其它程序写的行退回 JSON.parse；
+ * - `readSessionReadOnly`：头 + 条目 + 叶子（同 migrate.ts 的规则），末尾半行忽略、中间坏行抛错。
+ */
+import { type MigratedSession } from "./migrate.js";
+import type { SessionLine } from "./types.js";
+/** 根目录下全部 cwd 子目录（不含 trash）。 */
+export declare function sessionSubdirs(root: string): string[];
+/** 范围内的会话文件：给 cwd 只看该目录，否则全部；按文件名（创建时间）倒序。 */
+export declare function sessionFilesInScope(root: string, cwd?: string): string[];
+/** 按 id 或唯一前缀找会话文件；本 cwd 目录优先（同 compose-store 的规则，但只读、不 import 组装根）。 */
+export declare function findSessionFileReadOnly(root: string, id: string, cwd?: string): string;
+/**
+ * 逐行回调（不含行尾 `\n` / `\r`，跳过空行）；`last` 表示文件最后一行且没有换行结尾
+ * （可能是写入中途的半行）。回调返回 false 提前结束。
+ */
+export declare function forEachLine(file: string, visit: (line: string, index: number, last: boolean) => boolean | void): void;
+/** ama 写的行：不解析就取出 type（与消息的 role，若紧随其后）；不是这种形状时 undefined。 */
+export declare function lineType(line: string): {
+    type: string;
+    role?: string;
+} | undefined;
+/** 解析一行；失败时：末尾半行 → undefined，其它 → 抛 session_corrupt。 */
+export declare function parseLine(file: string, line: string, index: number, last: boolean): SessionLine | undefined;
+/** 只读读取整个会话（不加锁、不修复）：头、全部条目、叶子 id。 */
+export declare function readSessionReadOnly(file: string): MigratedSession & {
+    leaf: string | null;
+};

package/dist/session/scan.js

@@ -0,0 +1,140 @@
+/**
+ * 会话目录的只读扫描（`ama stats`、`ama sessions search|export`、`--from`）。[W4-D]
+ *
+ * 与 store.ts / manager.ts 的区别：这里**从不加锁、不修复、不写文件**——正在运行的会话也能读。
+ * - `sessionFilesInScope`：按 cwd（只看它的编码子目录）或全部子目录（跳过 `.trash`）列文件，最新在前；
+ * - `forEachLine`：按行回调（不先 split 出整个数组）；
+ * - `lineType`：ama 写入的行以 `{"type":"…"` 开头（manager 的 append 把 type 放在第一个键），
+ *   据此不解析就能跳过不需要的行；其它程序写的行退回 JSON.parse；
+ * - `readSessionReadOnly`：头 + 条目 + 叶子（同 migrate.ts 的规则），末尾半行忽略、中间坏行抛错。
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { AmaError } from "../errors.js";
+import { migrateSessionLines } from "./migrate.js";
+import { SESSION_FILE_SUFFIX, TRASH_DIR_NAME, listSessionFiles, sessionDirForCwd, sessionIdFromFileName, } from "./store.js";
+/** 根目录下全部 cwd 子目录（不含 trash）。 */
+export function sessionSubdirs(root) {
+    if (!existsSync(root))
+        return [];
+    return readdirSync(root)
+        .filter((name) => name !== TRASH_DIR_NAME)
+        .map((name) => join(root, name))
+        .filter((dir) => {
+        try {
+            return statSync(dir).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** 范围内的会话文件：给 cwd 只看该目录，否则全部；按文件名（创建时间）倒序。 */
+export function sessionFilesInScope(root, cwd) {
+    const dirs = cwd === undefined ? sessionSubdirs(root) : [sessionDirForCwd(root, cwd)];
+    const files = dirs.flatMap((dir) => listSessionFiles(dir));
+    return files.sort((a, b) => basename(b).localeCompare(basename(a)));
+}
+/** 按 id 或唯一前缀找会话文件；本 cwd 目录优先（同 compose-store 的规则，但只读、不 import 组装根）。 */
+export function findSessionFileReadOnly(root, id, cwd) {
+    const dirs = cwd === undefined
+        ? sessionSubdirs(root)
+        : [sessionDirForCwd(root, cwd), ...sessionSubdirs(root)];
+    const seen = new Set();
+    const prefix = [];
+    for (const dir of dirs) {
+        for (const file of listSessionFiles(dir)) {
+            if (seen.has(file))
+                continue;
+            seen.add(file);
+            const fileId = sessionIdFromFileName(file);
+            if (fileId === id)
+                return file;
+            if (fileId?.startsWith(id) === true)
+                prefix.push(file);
+        }
+    }
+    if (prefix.length > 1) {
+        const ids = prefix.map((f) => sessionIdFromFileName(f) ?? f).slice(0, 10);
+        throw new AmaError("invalid_arguments", `会话 id 前缀 ${id} 不唯一，候选：${ids.join(", ")}`, {
+            exitCode: 5,
+        });
+    }
+    const [file] = prefix;
+    if (file === undefined)
+        throw new AmaError("session_not_found", `会话不存在：${id}`, { exitCode: 5 });
+    return file;
+}
+/**
+ * 逐行回调（不含行尾 `\n` / `\r`，跳过空行）；`last` 表示文件最后一行且没有换行结尾
+ * （可能是写入中途的半行）。回调返回 false 提前结束。
+ */
+export function forEachLine(file, visit) {
+    const text = readFileSync(file, "utf8");
+    let start = 0;
+    let index = 0;
+    while (start < text.length) {
+        let end = text.indexOf("\n", start);
+        const last = end === -1;
+        if (last)
+            end = text.length;
+        let line = text.slice(start, end);
+        if (line.endsWith("\r"))
+            line = line.slice(0, -1);
+        start = end + 1;
+        if (line.trim() === "")
+            continue;
+        if (visit(line, index++, last) === false)
+            return;
+    }
+}
+const TYPE_PREFIX = '{"type":"';
+/** ama 写的行：不解析就取出 type（与消息的 role，若紧随其后）；不是这种形状时 undefined。 */
+export function lineType(line) {
+    if (!line.startsWith(TYPE_PREFIX))
+        return undefined;
+    const end = line.indexOf('"', TYPE_PREFIX.length);
+    if (end < 0)
+        return undefined;
+    const type = line.slice(TYPE_PREFIX.length, end);
+    if (type !== "message")
+        return { type };
+    const rolePrefix = ',"message":{"role":"';
+    if (!line.startsWith(rolePrefix, end + 1))
+        return { type };
+    const roleStart = end + 1 + rolePrefix.length;
+    const roleEnd = line.indexOf('"', roleStart);
+    return roleEnd < 0 ? { type } : { type, role: line.slice(roleStart, roleEnd) };
+}
+/** 解析一行；失败时：末尾半行 → undefined，其它 → 抛 session_corrupt。 */
+export function parseLine(file, line, index, last) {
+    try {
+        return JSON.parse(line);
+    }
+    catch (error) {
+        if (last)
+            return undefined;
+        throw new AmaError("session_corrupt", `${file}:${index + 1}: invalid JSON line`, {
+            cause: error,
+        });
+    }
+}
+/** 只读读取整个会话（不加锁、不修复）：头、全部条目、叶子 id。 */
+export function readSessionReadOnly(file) {
+    const lines = [];
+    try {
+        forEachLine(file, (line, index, last) => {
+            const parsed = parseLine(file, line, index, last);
+            if (parsed !== undefined)
+                lines.push(parsed);
+        });
+    }
+    catch (error) {
+        if (error instanceof AmaError)
+            throw error;
+        throw new AmaError("session_not_found", `cannot read session file ${file}`, { cause: error });
+    }
+    const migrated = migrateSessionLines(lines, file);
+    const leaf = migrated.leafId !== undefined ? migrated.leafId : (migrated.entries.at(-1)?.id ?? null);
+    return { ...migrated, leaf };
+}

package/dist/session/search.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 跨会话全文检索（`ama sessions search`）。[W4-D]
+ *
+ * - 模式：普通关键词（不区分大小写的子串）或 `/正则/标志`；
+ * - 检索的文本：user = 文本块；assistant = 文本块 + 工具调用（`名字 参数 JSON`）；tool = 工具结果文本。
+ *   思考块、system、custom 不检索；
+ * - 关键词不含 `"`、`\` 与控制字符时，先在原始行上做子串预筛（JSON 只转义这些字符，中文原样），
+ *   不命中的行不解析；正则没法预筛，逐行解析消息行；
+ * - 每条命中带：会话 id、条目时间、项目（头的 cwd）、角色、条目序号（文件里第几条条目，1 起）、
+ *   user 的消息编号（同 `sessions show` / `--from`）、片段与命中区间（展示层负责高亮）。
+ * - 文件按创建时间倒序（最新在前），文件内按条目顺序；到 limit 停。
+ */
+export type SearchRole = "user" | "assistant" | "tool";
+export interface SearchHit {
+    sessionId: string;
+    file: string;
+    cwd: string;
+    timestamp: string;
+    role: SearchRole;
+    /** 文件里第几条条目（1 起，不含头与 leaf 行）。 */
+    entryIndex: number;
+    entryId: string;
+    /** user 的消息编号。 */
+    userN?: number;
+    snippet: string;
+    /** snippet 里的命中区间 `[start, end)`。 */
+    ranges: Array<[number, number]>;
+}
+export interface SearchQuery {
+    /** 返回 `[start, end)` 区间；没有命中返回空数组。 */
+    match(text: string): Array<[number, number]>;
+    /** 原始行一定不含时返回 false（可跳过解析）；不确定返回 true。 */
+    mayContain(line: string): boolean;
+}
+/** `/re/flags` → 正则；其它 → 不区分大小写的子串。非法正则抛 SyntaxError。 */
+export declare function compileQuery(pattern: string): SearchQuery;
+/** 命中附近的单行片段（空白压平），区间换算到片段坐标。 */
+export declare function makeSnippet(text: string, ranges: ReadonlyArray<[number, number]>, context?: number): {
+    snippet: string;
+    ranges: Array<[number, number]>;
+};
+export interface SearchOptions {
+    roles?: ReadonlySet<SearchRole>;
+    /** ISO 时间下限（含）；比较条目 timestamp。 */
+    sinceIso?: string;
+    limit: number;
+}
+/** 在一批文件里检索；返回命中（最多 limit 条）与是否到了上限（可能还有更多）。 */
+export declare function searchSessions(files: readonly string[], query: SearchQuery, options: SearchOptions): {
+    hits: SearchHit[];
+    truncated: boolean;
+};