@armadra/agent 0.0.0-stage → 0.3.0

package/dist/session/projection.js

@@ -0,0 +1,184 @@
+/**
+ * 投影（设计 §8、§9）：活动分支 → 进上下文的消息。[B2]
+ *
+ * - `buildContextEntries(branch)`：若路径上有 compaction，取最新一条：先放 compaction，再放
+ *   `firstKeptEntryId` 到 compaction 之间的非 system 条目，再放 compaction 之后的条目。
+ * - `buildProjection(branch)`：对上一步的条目套用 `context_edit`（同一目标在活动分支上最新一条赢；
+ *   `null` 剔除，字符串只换内容、保留角色与元数据），并把每个条目映射为 `AgentMessage`。
+ *   有 compaction 时，compaction 之前的全部 system 消息折成一条完整的 system 检查点放在最前
+ *   （会话条目里不另存检查点，重放即可得到）。
+ * - `buildContext(branch)`：投影消息 + 路径上最近的模型 / 思考级别选择。
+ */
+function parseTime(iso) {
+    const value = Date.parse(iso);
+    return Number.isFinite(value) ? value : 0;
+}
+/**
+ * 条目 → 上下文消息；不进上下文的条目返回 undefined（model_change、label、custom、
+ * 第三波的 `usage` 条目等）。
+ */
+export function entryToMessage(entry) {
+    switch (entry.type) {
+        case "message":
+            return entry.message;
+        case "custom_message": {
+            const message = {
+                role: "custom",
+                customType: entry.customType,
+                content: entry.content,
+                display: entry.display,
+                timestamp: parseTime(entry.timestamp),
+            };
+            if (entry.details !== undefined)
+                message.details = entry.details;
+            return message;
+        }
+        case "branch_summary":
+            return {
+                role: "branchSummary",
+                summary: entry.summary,
+                fromId: entry.fromId,
+                timestamp: parseTime(entry.timestamp),
+            };
+        case "compaction":
+            return {
+                role: "compactionSummary",
+                summary: entry.summary,
+                tokensBefore: entry.tokensBefore,
+                timestamp: parseTime(entry.timestamp),
+            };
+        case "usage":
+        default:
+            return undefined;
+    }
+}
+function isSystemEntry(entry) {
+    return entry.type === "message" && entry.message.role === "system";
+}
+function latestCompactionIndex(branch) {
+    for (let i = branch.length - 1; i >= 0; i--)
+        if (branch[i]?.type === "compaction")
+            return i;
+    return -1;
+}
+export function buildContextEntries(branch) {
+    const at = latestCompactionIndex(branch);
+    if (at < 0)
+        return [...branch];
+    const compaction = branch[at];
+    const keptStart = branch.findIndex((entry) => entry.id === compaction.firstKeptEntryId);
+    const kept = keptStart >= 0 && keptStart < at
+        ? branch.slice(keptStart, at).filter((entry) => !isSystemEntry(entry))
+        : [];
+    return [compaction, ...kept, ...branch.slice(at + 1)];
+}
+/** 活动分支上每个目标最新的 context_edit。 */
+export function collectContextEdits(branch) {
+    const edits = new Map();
+    for (const entry of branch)
+        if (entry.type === "context_edit")
+            edits.set(entry.targetId, entry);
+    return edits;
+}
+/** 用替换文本换掉消息内容，保留角色与元数据。 */
+export function applyReplacement(message, text) {
+    switch (message.role) {
+        case "user":
+        case "toolResult":
+        case "custom":
+            return { ...message, content: text };
+        case "assistant": {
+            const replaced = { ...message, content: [{ type: "text", text }] };
+            return replaced;
+        }
+        case "compactionSummary":
+        case "branchSummary":
+            return { ...message, summary: text };
+        case "system":
+            return message;
+    }
+}
+/** 依次应用转录里的 system 消息（首条全量，之后是补丁）；没有 system 消息 → undefined。 */
+export function replaySystem(messages) {
+    let found = false;
+    const sections = new Map();
+    const tools = new Map();
+    for (const message of messages) {
+        if (message.role !== "system")
+            continue;
+        found = true;
+        for (const [name, text] of Object.entries(message.sections)) {
+            if (text === null)
+                sections.delete(name);
+            else
+                sections.set(name, text);
+        }
+        for (const name of message.toolsRemoved ?? [])
+            tools.delete(name);
+        for (const tool of message.toolsAdded ?? []) {
+            tools.delete(tool.name);
+            tools.set(tool.name, tool);
+        }
+    }
+    if (!found)
+        return undefined;
+    return { sections: Object.fromEntries(sections), tools: [...tools.values()] };
+}
+/** 把重放结果写成一条完整的 system 消息。 */
+export function systemCheckpoint(state, timestamp) {
+    const message = { role: "system", sections: { ...state.sections }, timestamp };
+    if (state.tools.length > 0)
+        message.toolsAdded = state.tools.map((tool) => ({ ...tool }));
+    return message;
+}
+// ---------------------------------------------------------------------------
+// 投影
+// ---------------------------------------------------------------------------
+export function buildProjection(branch) {
+    const edits = collectContextEdits(branch);
+    const at = latestCompactionIndex(branch);
+    const compaction = at >= 0 ? branch[at] : undefined;
+    const items = [];
+    if (compaction !== undefined) {
+        const before = [];
+        for (const entry of branch.slice(0, at)) {
+            if (entry.type === "message" && entry.message.role === "system")
+                before.push(entry.message);
+        }
+        const state = replaySystem(before);
+        if (state !== undefined) {
+            items.push({
+                entry: compaction,
+                message: systemCheckpoint(state, parseTime(compaction.timestamp)),
+            });
+        }
+    }
+    for (const entry of buildContextEntries(branch)) {
+        let message = entryToMessage(entry);
+        if (message === undefined)
+            continue;
+        const edit = edits.get(entry.id);
+        if (edit !== undefined) {
+            if (edit.replacement === null)
+                continue;
+            message = applyReplacement(message, edit.replacement);
+        }
+        items.push({ entry, message });
+    }
+    return { items, messages: items.map((item) => item.message), compaction };
+}
+export function buildContext(branch) {
+    let model;
+    let thinkingLevel;
+    for (const entry of branch) {
+        if (entry.type === "model_change")
+            model = {
+                provider: entry.provider,
+                id: entry.modelId,
+                ...(entry.channel !== undefined ? { channel: entry.channel } : {}),
+            };
+        else if (entry.type === "thinking_level_change")
+            thinkingLevel = entry.thinkingLevel;
+    }
+    return { messages: buildProjection(branch).messages, model, thinkingLevel };
+}

package/dist/session/store.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 会话文件的磁盘层（设计 §8）：目录编码、文件名、JSONL 读写、原子追加、单写者锁、trash。[B2]
+ *
+ * - 位置 `<sessionsRoot>/<编码 cwd>/<ISO>_<uuid>.jsonl`；编码 cwd = 去首分隔符、`/ \ :` 换 `-`。
+ * - 只追加：每条记录一行 JSON + LF，用 O_APPEND 写（单写者由锁保证）。
+ * - 打开时若末行是半行（进程在写入中途崩溃），截掉半行再继续追加；中间行损坏 → session_corrupt。
+ * - 锁：`<file>.lock`（O_EXCL 创建，内容为 pid）；持锁进程已不在 → 视为陈旧锁并接管。
+ * - prune：移到 `<sessionsRoot>/.trash/`，文件名前缀删除时间；`purgeTrash` 清理超过 7 天的。
+ */
+import type { SessionLine } from "./types.js";
+export declare const SESSION_FILE_SUFFIX = ".jsonl";
+export declare const TRASH_DIR_NAME = ".trash";
+export declare const TRASH_RETENTION_MS: number;
+/** 去首分隔符，`/ \ :` 换 `-`。 */
+export declare function encodeCwd(cwd: string): string;
+export declare function sessionDirForCwd(sessionsRoot: string, cwd: string): string;
+/** `2026-10-02T05-23-11-123Z_<id>.jsonl`（ISO 里的 `:` 与 `.` 换 `-`，Windows 可用）。 */
+export declare function sessionFileName(date: Date, id: string): string;
+/** 从文件名取会话 id（不符合命名时 undefined）。 */
+export declare function sessionIdFromFileName(file: string): string | undefined;
+export interface ReadResult {
+    lines: SessionLine[];
+    /** 末尾半行被截掉时为 true。 */
+    repairedTail: boolean;
+}
+/**
+ * 读并解析 JSONL。`repair: true` 时把末尾半行从文件里截掉（只截最后一行，且只在它无法解析时）。
+ */
+export declare function readSessionLines(file: string, options?: {
+    repair?: boolean;
+}): ReadResult;
+/** 追加若干行（一次 write，O_APPEND）。 */
+export declare function appendLines(file: string, lines: readonly SessionLine[]): void;
+/** 新建文件：先写临时文件再 rename，避免出现只有半个头的文件。 */
+export declare function writeNewSessionFile(file: string, lines: readonly SessionLine[]): void;
+export interface SessionLock {
+    readonly path: string;
+    release(): void;
+}
+/** 单写者锁。同一进程内对同一文件重复加锁也视为冲突。 */
+export declare function acquireLock(file: string): SessionLock;
+/** 目录下的会话文件（按文件名倒序 = 最新在前）。 */
+export declare function listSessionFiles(dir: string): string[];
+/** 移到 `<sessionsRoot>/.trash/<删除时间毫秒>__<编码目录>__<文件名>`，返回新路径。 */
+export declare function trashSession(file: string, sessionsRoot: string, now?: number): string;
+/** 删除 trash 中超过保留期的文件，返回删除的路径。 */
+export declare function purgeTrash(sessionsRoot: string, now?: number, retentionMs?: number): string[];

package/dist/session/store.js

@@ -0,0 +1,210 @@
+/**
+ * 会话文件的磁盘层（设计 §8）：目录编码、文件名、JSONL 读写、原子追加、单写者锁、trash。[B2]
+ *
+ * - 位置 `<sessionsRoot>/<编码 cwd>/<ISO>_<uuid>.jsonl`；编码 cwd = 去首分隔符、`/ \ :` 换 `-`。
+ * - 只追加：每条记录一行 JSON + LF，用 O_APPEND 写（单写者由锁保证）。
+ * - 打开时若末行是半行（进程在写入中途崩溃），截掉半行再继续追加；中间行损坏 → session_corrupt。
+ * - 锁：`<file>.lock`（O_EXCL 创建，内容为 pid）；持锁进程已不在 → 视为陈旧锁并接管。
+ * - prune：移到 `<sessionsRoot>/.trash/`，文件名前缀删除时间；`purgeTrash` 清理超过 7 天的。
+ */
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, truncateSync, writeFileSync, writeSync, } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { AmaError } from "../errors.js";
+export const SESSION_FILE_SUFFIX = ".jsonl";
+export const TRASH_DIR_NAME = ".trash";
+export const TRASH_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+/** 去首分隔符，`/ \ :` 换 `-`。 */
+export function encodeCwd(cwd) {
+    return cwd.replace(/^[/\\]+/, "").replace(/[/\\:]/g, "-");
+}
+export function sessionDirForCwd(sessionsRoot, cwd) {
+    return join(sessionsRoot, encodeCwd(cwd));
+}
+/** `2026-10-02T05-23-11-123Z_<id>.jsonl`（ISO 里的 `:` 与 `.` 换 `-`，Windows 可用）。 */
+export function sessionFileName(date, id) {
+    return `${date.toISOString().replace(/[:.]/g, "-")}_${id}${SESSION_FILE_SUFFIX}`;
+}
+/** 从文件名取会话 id（不符合命名时 undefined）。 */
+export function sessionIdFromFileName(file) {
+    const name = basename(file);
+    if (!name.endsWith(SESSION_FILE_SUFFIX))
+        return undefined;
+    const stem = name.slice(0, -SESSION_FILE_SUFFIX.length);
+    const at = stem.indexOf("_");
+    return at < 0 ? undefined : stem.slice(at + 1);
+}
+/**
+ * 读并解析 JSONL。`repair: true` 时把末尾半行从文件里截掉（只截最后一行，且只在它无法解析时）。
+ */
+export function readSessionLines(file, options = {}) {
+    let text;
+    try {
+        text = readFileSync(file, "utf8");
+    }
+    catch (error) {
+        throw new AmaError("session_not_found", `cannot read session file ${file}`, { cause: error });
+    }
+    const rawLines = text.split("\n");
+    const endsWithNewline = text.endsWith("\n");
+    if (endsWithNewline)
+        rawLines.pop();
+    const lines = [];
+    let repairedTail = false;
+    for (let i = 0; i < rawLines.length; i++) {
+        const raw = (rawLines[i] ?? "").replace(/\r$/, "");
+        if (raw.trim() === "")
+            continue;
+        try {
+            lines.push(JSON.parse(raw));
+        }
+        catch (error) {
+            const isLast = i === rawLines.length - 1;
+            if (isLast && !endsWithNewline) {
+                repairedTail = true;
+                if (options.repair === true) {
+                    const keep = Buffer.byteLength(rawLines.slice(0, i).join("\n"), "utf8") + (i > 0 ? 1 : 0);
+                    truncateSync(file, keep);
+                }
+                break;
+            }
+            throw new AmaError("session_corrupt", `${file}:${i + 1}: invalid JSON line`, {
+                cause: error,
+            });
+        }
+    }
+    if (!repairedTail && !endsWithNewline && text.length > 0 && options.repair === true) {
+        // 最后一行完整但缺 LF：补上，保证后续追加另起一行。
+        appendRaw(file, "\n");
+    }
+    return { lines, repairedTail };
+}
+function appendRaw(file, text) {
+    const fd = openSync(file, "a");
+    try {
+        writeSync(fd, text);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** 追加若干行（一次 write，O_APPEND）。 */
+export function appendLines(file, lines) {
+    if (lines.length === 0)
+        return;
+    appendRaw(file, lines.map((line) => JSON.stringify(line)).join("\n") + "\n");
+}
+/** 新建文件：先写临时文件再 rename，避免出现只有半个头的文件。 */
+export function writeNewSessionFile(file, lines) {
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    if (existsSync(file)) {
+        throw new AmaError("session_exists", `session file already exists: ${file}`);
+    }
+    const tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, lines.map((line) => JSON.stringify(line)).join("\n") + "\n", { mode: 0o600 });
+    renameSync(tmp, file);
+}
+// ---------------------------------------------------------------------------
+// 锁
+// ---------------------------------------------------------------------------
+const heldLocks = new Set();
+let exitHandlerInstalled = false;
+function installExitHandler() {
+    if (exitHandlerInstalled)
+        return;
+    exitHandlerInstalled = true;
+    process.once("exit", () => {
+        for (const lock of heldLocks)
+            rmSync(lock, { force: true });
+    });
+}
+function pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/** 单写者锁。同一进程内对同一文件重复加锁也视为冲突。 */
+export function acquireLock(file) {
+    const path = `${file}.lock`;
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const fd = openSync(path, "wx", 0o600);
+            writeSync(fd, String(process.pid));
+            closeSync(fd);
+            heldLocks.add(path);
+            installExitHandler();
+            let released = false;
+            return {
+                path,
+                release() {
+                    if (released)
+                        return;
+                    released = true;
+                    heldLocks.delete(path);
+                    rmSync(path, { force: true });
+                },
+            };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            let owner = Number.NaN;
+            try {
+                owner = Number.parseInt(readFileSync(path, "utf8").trim(), 10);
+            }
+            catch {
+                // 读不到当作陈旧
+            }
+            const stale = heldLocks.has(path) ? false : !pidAlive(owner) || owner === process.pid;
+            if (!stale || attempt > 0) {
+                throw new AmaError("session_locked", `session file is in use by pid ${owner}: ${file}`);
+            }
+            rmSync(path, { force: true });
+        }
+    }
+    throw new AmaError("session_locked", `cannot lock session file ${file}`);
+}
+// ---------------------------------------------------------------------------
+// 列表与 trash
+// ---------------------------------------------------------------------------
+/** 目录下的会话文件（按文件名倒序 = 最新在前）。 */
+export function listSessionFiles(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((name) => name.endsWith(SESSION_FILE_SUFFIX))
+        .sort()
+        .reverse()
+        .map((name) => join(dir, name));
+}
+/** 移到 `<sessionsRoot>/.trash/<删除时间毫秒>__<编码目录>__<文件名>`，返回新路径。 */
+export function trashSession(file, sessionsRoot, now = Date.now()) {
+    const trash = join(sessionsRoot, TRASH_DIR_NAME);
+    mkdirSync(trash, { recursive: true, mode: 0o700 });
+    const target = join(trash, `${now}__${basename(dirname(file))}__${basename(file)}`);
+    renameSync(file, target);
+    rmSync(`${file}.lock`, { force: true });
+    return target;
+}
+/** 删除 trash 中超过保留期的文件，返回删除的路径。 */
+export function purgeTrash(sessionsRoot, now = Date.now(), retentionMs = TRASH_RETENTION_MS) {
+    const trash = join(sessionsRoot, TRASH_DIR_NAME);
+    if (!existsSync(trash))
+        return [];
+    const removed = [];
+    for (const name of readdirSync(trash)) {
+        const full = join(trash, name);
+        const stamp = Number.parseInt(name.split("__")[0] ?? "", 10);
+        const deletedAt = Number.isFinite(stamp) ? stamp : statSync(full).mtimeMs;
+        if (now - deletedAt > retentionMs) {
+            rmSync(full, { force: true });
+            removed.push(full);
+        }
+    }
+    return removed;
+}

package/dist/session/tree.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 会话条目树（设计 §8）：按 id 索引、根 → 叶子路径、公共祖先、树形视图。[B2]
+ *
+ * 条目以 parentId 串成树；多根是允许的（`setLeaf(null)` 后再追加）。所有函数都是纯函数，
+ * 输入是文件顺序的条目数组。
+ */
+import type { SessionEntry, SessionTreeNode } from "./types.js";
+export type EntryIndex = ReadonlyMap<string, SessionEntry>;
+export declare function indexEntries(entries: readonly SessionEntry[]): Map<string, SessionEntry>;
+/** 根 → leafId 的路径（含 leaf）；leafId 为 null 或找不到时返回空数组。遇环即停。 */
+export declare function pathToRoot(index: EntryIndex, leafId: string | null): SessionEntry[];
+/** 两个叶子的最深公共祖先 id（无公共祖先 → null）。 */
+export declare function commonAncestor(index: EntryIndex, a: string | null, b: string | null): string | null;
+/** 从 `fromId`（不含）往上直到 `ancestorId`（不含）的条目，从旧到新。 */
+export declare function entriesBetween(index: EntryIndex, ancestorId: string | null, fromId: string | null): SessionEntry[];
+/** label 条目：同一目标最新一条赢；label 缺省 = 清除。 */
+export declare function collectLabels(entries: readonly SessionEntry[]): Map<string, string>;
+/** 文件顺序建树；孤儿（parentId 指向不存在的条目）当作根。 */
+export declare function buildTree(entries: readonly SessionEntry[]): SessionTreeNode[];
+/** 叶子条目（没有子条目的）id，文件顺序。 */
+export declare function leafIds(entries: readonly SessionEntry[]): string[];

package/dist/session/tree.js

@@ -0,0 +1,88 @@
+/**
+ * 会话条目树（设计 §8）：按 id 索引、根 → 叶子路径、公共祖先、树形视图。[B2]
+ *
+ * 条目以 parentId 串成树；多根是允许的（`setLeaf(null)` 后再追加）。所有函数都是纯函数，
+ * 输入是文件顺序的条目数组。
+ */
+export function indexEntries(entries) {
+    const map = new Map();
+    for (const entry of entries)
+        map.set(entry.id, entry);
+    return map;
+}
+/** 根 → leafId 的路径（含 leaf）；leafId 为 null 或找不到时返回空数组。遇环即停。 */
+export function pathToRoot(index, leafId) {
+    const path = [];
+    const seen = new Set();
+    let current = leafId === null ? undefined : index.get(leafId);
+    while (current !== undefined && !seen.has(current.id)) {
+        seen.add(current.id);
+        path.push(current);
+        current = current.parentId === null ? undefined : index.get(current.parentId);
+    }
+    return path.reverse();
+}
+/** 两个叶子的最深公共祖先 id（无公共祖先 → null）。 */
+export function commonAncestor(index, a, b) {
+    const ancestorsOfA = new Set(pathToRoot(index, a).map((entry) => entry.id));
+    const pathB = pathToRoot(index, b);
+    for (let i = pathB.length - 1; i >= 0; i--) {
+        const entry = pathB[i];
+        if (entry !== undefined && ancestorsOfA.has(entry.id))
+            return entry.id;
+    }
+    return null;
+}
+/** 从 `fromId`（不含）往上直到 `ancestorId`（不含）的条目，从旧到新。 */
+export function entriesBetween(index, ancestorId, fromId) {
+    const path = pathToRoot(index, fromId);
+    if (ancestorId === null)
+        return path;
+    const at = path.findIndex((entry) => entry.id === ancestorId);
+    return at < 0 ? path : path.slice(at + 1);
+}
+/** label 条目：同一目标最新一条赢；label 缺省 = 清除。 */
+export function collectLabels(entries) {
+    const labels = new Map();
+    for (const entry of entries) {
+        if (entry.type !== "label")
+            continue;
+        if (entry.label === undefined || entry.label === "")
+            labels.delete(entry.targetId);
+        else
+            labels.set(entry.targetId, entry.label);
+    }
+    return labels;
+}
+/** 文件顺序建树；孤儿（parentId 指向不存在的条目）当作根。 */
+export function buildTree(entries) {
+    const labels = collectLabels(entries);
+    const nodes = new Map();
+    for (const entry of entries) {
+        const node = { entry, children: [] };
+        const label = labels.get(entry.id);
+        if (label !== undefined)
+            node.label = label;
+        nodes.set(entry.id, node);
+    }
+    const roots = [];
+    for (const entry of entries) {
+        const node = nodes.get(entry.id);
+        if (node === undefined)
+            continue;
+        const parent = entry.parentId === null ? undefined : nodes.get(entry.parentId);
+        if (parent === undefined || parent === node)
+            roots.push(node);
+        else
+            parent.children.push(node);
+    }
+    return roots;
+}
+/** 叶子条目（没有子条目的）id，文件顺序。 */
+export function leafIds(entries) {
+    const hasChild = new Set();
+    for (const entry of entries)
+        if (entry.parentId !== null)
+            hasChild.add(entry.parentId);
+    return entries.filter((entry) => !hasChild.has(entry.id)).map((entry) => entry.id);
+}