@armadra/agent 0.0.0-stage → 0.2.1

package/dist/sdk.js

@@ -0,0 +1,195 @@
+/**
+ * SDK（设计 §13.1、实施计划 §1.3 C2）。[B6]
+ *
+ * - `createRuntime(options)`：与 CLI 同一条启动序列（bootstrap 第 3–14 步 + 组装根），读用户级 /
+ *   项目级配置、AGENTS.md、Skill、hooks.json、auth.json；不进入任何模式。参数可以写成字段，
+ *   也可以直接给 `argv`（与 `ama` 命令行同语法）。
+ * - `createAgentSession(options)`：不读文件系统配置的轻量装配——内存会话（或传入的
+ *   SessionManager）、选定的工具、规则与回调审批，直接返回 `AgentSessionImpl`
+ *   （含 `addTool / updateSystem / navigate` 等扩展方法）。
+ *
+ * 两者共用组装根（cli/compose*.ts），审批链、系统提示装配、工具预设与缓存行为与 CLI 一致。
+ */
+import { resolve } from "node:path";
+import { ProviderRegistry } from "./ai/providers/registry.js";
+import { parseArgs } from "./cli/args.js";
+import { bootstrap } from "./cli/bootstrap.js";
+import { withExtraProviders } from "./cli/compose-providers.js";
+import { composeSession, emptyComposeState } from "./cli/compose-session.js";
+import { buildRules, createRuntimeDeps, createTools } from "./cli/compose.js";
+import { pickDefaultModel } from "./cli/default-model.js";
+import { findContextFiles } from "./config/context-files.js";
+import { DEFAULT_CONFIG, mergeConfig } from "./config/merge.js";
+import { resolveConfigDir, resolveDataDir } from "./config/paths.js";
+import { AmaError } from "./errors.js";
+import { hooksFromConfig } from "./hooks/config.js";
+import { HookDispatcher } from "./hooks/dispatcher.js";
+import { AgentEventBus } from "./host/api-impl.js";
+import { PermissionPipeline } from "./permissions/pipeline.js";
+import { SessionManager } from "./session/manager.js";
+import { discoverSkills } from "./skills/discover.js";
+import { PresetToolRegistry } from "./tools/presets.js";
+export async function createRuntime(options = {}) {
+    const parsed = parseArgs(options.argv ?? []);
+    if (parsed.kind !== "run")
+        throw new AmaError("invalid_arguments", "createRuntime 不接受子命令");
+    const args = parsed.args;
+    if (options.model !== undefined)
+        args.model = options.model;
+    if (options.thinkingLevel !== undefined)
+        args.thinking = options.thinkingLevel;
+    if (options.permissionMode !== undefined)
+        args.permissionMode = options.permissionMode;
+    if (options.toolsPreset !== undefined)
+        args.toolsPreset = options.toolsPreset;
+    if (options.trust !== undefined)
+        args.trust = options.trust;
+    if (options.sessionDir !== undefined)
+        args.sessionDir = options.sessionDir;
+    if (options.profile !== undefined)
+        args.profile = options.profile;
+    if (options.unattended === true)
+        args.print = true;
+    const env = options.env ?? process.env;
+    const io = {
+        stdout: () => undefined,
+        stderr: options.stderr ?? ((text) => void process.stderr.write(text)),
+        stdinIsTTY: false,
+        stdoutIsTTY: false,
+        env,
+        cwd: options.cwd ?? process.cwd(),
+        readStdin: async () => "",
+    };
+    return bootstrap(args, createRuntimeDeps({ env, ...options.compose }), io);
+}
+function keyOptions(auth) {
+    switch (auth?.kind) {
+        case undefined:
+            return {};
+        case "file":
+            return { authFile: auth.path, userAuthFile: null, useEnv: false };
+        case "env":
+            return { userAuthFile: null, useEnv: true };
+        case "inline":
+            return { configKeys: auth.keys, userAuthFile: null, useEnv: false };
+        case "none":
+            return { userAuthFile: null, useEnv: false };
+    }
+}
+export async function createAgentSession(options = {}) {
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const warn = options.onWarning ?? (() => undefined);
+    let config = mergeConfig(DEFAULT_CONFIG, options.config);
+    if (options.toolsPreset !== undefined)
+        config = mergeConfig(config, { tools: { preset: options.toolsPreset } });
+    const providers = new ProviderRegistry({
+        config: withExtraProviders(config, options.providers),
+        apis: options.apis,
+        includeFake: true,
+        keys: keyOptions(options.auth),
+        onWarning: warn,
+    });
+    const ref = typeof options.model === "object"
+        ? `${options.model.provider}/${options.model.id}`
+        : (options.model ?? config.defaultModel);
+    let choice;
+    if (ref !== undefined) {
+        const found = providers.findModel(ref);
+        if (!found.ok)
+            throw new AmaError("model_not_found", `模型不存在：${ref}`, { detail: found.candidates });
+        choice = found;
+    }
+    else {
+        choice = await pickDefaultModel(providers);
+        if (choice === undefined)
+            throw new AmaError("no_api_key", "没有可用模型：传 model，或配置任一供应商的 key");
+    }
+    const state = emptyComposeState();
+    let tools;
+    if (options.tools === undefined || options.tools === "default") {
+        tools = createTools({ config, cwd, mode: "line" }, { extraTools: options.extraTools ?? [] }, state);
+    }
+    else {
+        tools = new PresetToolRegistry();
+        for (const tool of options.tools === "none" ? [] : options.tools)
+            tools.register(tool, "sdk");
+        for (const tool of options.extraTools ?? [])
+            tools.register(tool, "sdk");
+    }
+    for (const name of options.disableTools ?? [])
+        tools.disable(name);
+    const mode = options.permission?.mode ?? config.permission?.mode ?? "default";
+    const rules = buildRules([
+        ...(options.permission?.allow ?? []).map((raw) => ({
+            effect: "allow",
+            raw,
+            source: "sdk",
+        })),
+        ...(options.permission?.deny ?? []).map((raw) => ({
+            effect: "deny",
+            raw,
+            source: "sdk",
+        })),
+    ], config.permission?.builtinDeny, warn);
+    const permission = new PermissionPipeline({ mode, rules, cwd });
+    const manager = options.sessionManager ?? SessionManager.inMemory(cwd);
+    let session;
+    const hooks = new HookDispatcher({
+        hooks: options.hooks === undefined || options.hooks === false ? [] : hooksFromConfig(options.hooks),
+        context: () => ({
+            sessionId: manager.id,
+            cwd,
+            model: session?.state.model ?? { provider: choice.model.provider, id: choice.model.id },
+            permissionMode: permission.mode,
+            depth: 0,
+        }),
+        onWarning: warn,
+    });
+    const configDir = resolveConfigDir();
+    if (options.skillDirs !== undefined && options.skillDirs.length > 0) {
+        const sources = options.skillDirs.map((dir) => ({
+            dir: resolve(cwd, dir),
+            scope: "cli",
+            requiresTrust: false,
+        }));
+        const found = await discoverSkills(sources, { trusted: true });
+        state.skills = found.skills;
+        found.warnings.forEach((w) => warn(w));
+    }
+    const context = options.contextFiles === true ? findContextFiles({ cwd, configDir }) : undefined;
+    const ask = options.permission?.ask;
+    const assembly = {
+        mode: options.unattended === true ? "print" : "line",
+        paths: { configDir, dataDir: resolveDataDir(), sessionDir: manager.directory() ?? cwd, cwd },
+        config,
+        trust: { trusted: true, source: "default" },
+        resources: {
+            contextFiles: context?.files.map((f) => ({ path: f.path, content: f.content })) ?? [],
+            skills: state.skills.map((s) => ({
+                name: s.name,
+                description: s.description,
+                location: s.location,
+            })),
+            prompts: [],
+            instructions: [],
+        },
+        providers,
+        model: choice.model,
+        provider: choice.provider,
+        thinkingLevel: options.thinkingLevel ?? config.thinkingLevel ?? "medium",
+        sessionManager: manager,
+        source: manager.entries().length > 0 ? "resume" : "startup",
+        hooks,
+        permission,
+        tools,
+        events: new AgentEventBus(),
+        host: { handle: undefined, broker: () => undefined, instructions: options.instructions ?? [] },
+        uiBroker: () => (ask === undefined ? undefined : { ask }),
+        onSessionReplaced: () => undefined,
+        sessionStartContext: () => undefined,
+        unattended: options.unattended === true,
+        warn,
+    };
+    session = composeSession(assembly, state, { log: options.log ?? (() => undefined) });
+    return session;
+}

package/dist/session/manager.d.ts

@@ -0,0 +1,70 @@
+/**
+ * SessionManager（设计 §8、§11.1 第 7 / 16 步）：JSONL 条目树的读写与叶子管理。[B2]
+ *
+ * - `inMemory(cwd)`：从不落盘。
+ * - `create(dir, cwd)`：**延迟落盘**——`append()` 先记在内存，直到 `flush()`（AgentSession 在
+ *   首次模型请求前调用）才建文件、写头与已缓存条目、加锁；之后每次 `append()` 立即追加一行。
+ * - `open(file)`：读文件（修复末尾半行）、校验版本、加锁；叶子 = 文件中最后一条条目，
+ *   若其后还有 `leaf` 行（`/tree` 换叶子落盘，第三波 A7）则取最后一条 leaf 行。
+ * - `setLeaf(id)`：已落盘时追加一行 `leaf{id, timestamp}`；延迟会话在 `flush()` 时补写。
+ * - `fork(entryId)`：复制 root → entryId 的分支到新文件（头的 parentSession 指回本文件），
+ *   不复制 leaf 行。
+ * - `close()`：释放锁；之后的 append 抛错。
+ */
+import type { SessionEntry, SessionEntryInput, SessionHeader, SessionListItem, SessionManagerApi, SessionTreeNode } from "./types.js";
+export interface SessionManagerOptions {
+    /** 测试注入时钟。 */
+    now?: () => Date;
+    /** 头里的 parentSession。 */
+    parentSession?: string;
+    /** 指定会话 id（`--session-id`）。 */
+    id?: string;
+}
+export declare class SessionManager implements SessionManagerApi {
+    readonly id: string;
+    readonly cwd: string;
+    private readonly _header;
+    private readonly _entries;
+    private readonly index;
+    private leaf;
+    private storage;
+    private closed;
+    private readonly now;
+    private constructor();
+    private static newHeader;
+    static inMemory(cwd: string, options?: SessionManagerOptions): SessionManager;
+    /** `dir` 是会话文件所在目录（通常是 `sessionDirForCwd(sessionsRoot, cwd)`）。 */
+    static create(dir: string, cwd: string, options?: SessionManagerOptions): SessionManager;
+    static createForCwd(sessionsRoot: string, cwd: string, options?: SessionManagerOptions): SessionManager;
+    static open(file: string, options?: {
+        now?: () => Date;
+    }): SessionManager;
+    /** `--continue`：本目录最近一条；没有则新建（延迟落盘）。 */
+    static continueRecent(dir: string, cwd: string): SessionManager;
+    /** 只读列出目录下的会话（最新在前）；损坏的文件跳过。 */
+    static list(dir: string): SessionListItem[];
+    file(): string | undefined;
+    header(): SessionHeader;
+    entries(): readonly SessionEntry[];
+    getEntry(id: string): SessionEntry | undefined;
+    leafId(): string | null;
+    append(input: SessionEntryInput): SessionEntry;
+    setLeaf(id: string | null): void;
+    private leafLine;
+    branch(leafId?: string | null): SessionEntry[];
+    getEntries(since?: string): {
+        entries: SessionEntry[];
+        leafId: string | null;
+    };
+    getTree(): SessionTreeNode[];
+    name(): string | undefined;
+    setName(name: string): void;
+    fork(entryId: string): SessionManager;
+    /** 延迟会话：建文件、写头与缓存条目、加锁。返回文件路径（内存会话为 undefined）。幂等。 */
+    flush(): string | undefined;
+    isPersisted(): boolean;
+    isInMemory(): boolean;
+    /** 会话文件所在目录（内存会话 undefined）。 */
+    directory(): string | undefined;
+    close(): void;
+}

package/dist/session/manager.js

@@ -0,0 +1,278 @@
+/**
+ * SessionManager（设计 §8、§11.1 第 7 / 16 步）：JSONL 条目树的读写与叶子管理。[B2]
+ *
+ * - `inMemory(cwd)`：从不落盘。
+ * - `create(dir, cwd)`：**延迟落盘**——`append()` 先记在内存，直到 `flush()`（AgentSession 在
+ *   首次模型请求前调用）才建文件、写头与已缓存条目、加锁；之后每次 `append()` 立即追加一行。
+ * - `open(file)`：读文件（修复末尾半行）、校验版本、加锁；叶子 = 文件中最后一条条目，
+ *   若其后还有 `leaf` 行（`/tree` 换叶子落盘，第三波 A7）则取最后一条 leaf 行。
+ * - `setLeaf(id)`：已落盘时追加一行 `leaf{id, timestamp}`；延迟会话在 `flush()` 时补写。
+ * - `fork(entryId)`：复制 root → entryId 的分支到新文件（头的 parentSession 指回本文件），
+ *   不复制 leaf 行。
+ * - `close()`：释放锁；之后的 append 抛错。
+ */
+import { randomBytes, randomUUID } from "node:crypto";
+import { statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { AmaError } from "../errors.js";
+import { AMA_VERSION } from "../version.js";
+import { migrateSessionLines } from "./migrate.js";
+import { acquireLock, appendLines, listSessionFiles, readSessionLines, sessionDirForCwd, sessionFileName, writeNewSessionFile, } from "./store.js";
+import { buildTree, indexEntries, pathToRoot } from "./tree.js";
+import { SESSION_FORMAT_VERSION } from "./types.js";
+function newEntryId(taken) {
+    for (;;) {
+        const id = randomBytes(4).toString("hex");
+        if (!taken.has(id))
+            return id;
+    }
+}
+export class SessionManager {
+    id;
+    cwd;
+    _header;
+    _entries;
+    index;
+    leaf;
+    storage;
+    closed = false;
+    now;
+    constructor(header, entries, storage, now, leafId) {
+        this._header = header;
+        this.id = header.id;
+        this.cwd = header.cwd;
+        this._entries = entries;
+        this.index = indexEntries(entries);
+        const last = entries.at(-1)?.id ?? null;
+        this.leaf =
+            leafId === undefined || (leafId !== null && !this.index.has(leafId)) ? last : leafId;
+        this.storage = storage;
+        this.now = now;
+    }
+    static newHeader(cwd, options, now) {
+        const header = {
+            type: "session",
+            version: SESSION_FORMAT_VERSION,
+            id: options.id ?? randomUUID(),
+            timestamp: now.toISOString(),
+            cwd,
+            agent: { name: "ama", version: AMA_VERSION },
+        };
+        if (options.parentSession !== undefined)
+            header.parentSession = options.parentSession;
+        return header;
+    }
+    static inMemory(cwd, options = {}) {
+        const now = options.now ?? (() => new Date());
+        return new SessionManager(this.newHeader(cwd, options, now()), [], { kind: "memory" }, now);
+    }
+    /** `dir` 是会话文件所在目录（通常是 `sessionDirForCwd(sessionsRoot, cwd)`）。 */
+    static create(dir, cwd, options = {}) {
+        const now = options.now ?? (() => new Date());
+        return new SessionManager(this.newHeader(cwd, options, now()), [], { kind: "lazy", dir }, now);
+    }
+    static createForCwd(sessionsRoot, cwd, options = {}) {
+        return this.create(sessionDirForCwd(sessionsRoot, cwd), cwd, options);
+    }
+    static open(file, options = {}) {
+        const lock = acquireLock(file);
+        try {
+            const { lines } = readSessionLines(file, { repair: true });
+            const { header, entries, leafId } = migrateSessionLines(lines, file);
+            return new SessionManager(header, entries, { kind: "file", file, lock }, options.now ?? (() => new Date()), leafId);
+        }
+        catch (error) {
+            lock.release();
+            throw error;
+        }
+    }
+    /** `--continue`：本目录最近一条；没有则新建（延迟落盘）。 */
+    static continueRecent(dir, cwd) {
+        const [latest] = listSessionFiles(dir);
+        return latest === undefined ? this.create(dir, cwd) : this.open(latest);
+    }
+    /** 只读列出目录下的会话（最新在前）；损坏的文件跳过。 */
+    static list(dir) {
+        const items = [];
+        for (const file of listSessionFiles(dir)) {
+            try {
+                const { header, entries } = migrateSessionLines(readSessionLines(file).lines, file);
+                let name;
+                let firstPrompt;
+                let messageCount = 0;
+                for (const entry of entries) {
+                    if (entry.type === "session_info" && entry.name !== undefined)
+                        name = entry.name;
+                    if (entry.type !== "message" || entry.message.role === "system")
+                        continue;
+                    messageCount++;
+                    if (firstPrompt === undefined && entry.message.role === "user") {
+                        const { content } = entry.message;
+                        firstPrompt =
+                            typeof content === "string"
+                                ? content
+                                : content.map((block) => (block.type === "text" ? block.text : "")).join("");
+                    }
+                }
+                const item = {
+                    id: header.id,
+                    file,
+                    cwd: header.cwd,
+                    createdAt: header.timestamp,
+                    modifiedAt: statSync(file).mtime.toISOString(),
+                    messageCount,
+                };
+                if (name !== undefined)
+                    item.name = name;
+                if (firstPrompt !== undefined)
+                    item.firstPrompt = firstPrompt.slice(0, 200);
+                items.push(item);
+            }
+            catch {
+                // 损坏 / 不可读：列表里跳过（sessions show 会给出具体错误）
+            }
+        }
+        return items;
+    }
+    // -------------------------------------------------------------------------
+    // SessionManagerApi
+    // -------------------------------------------------------------------------
+    file() {
+        return this.storage.kind === "file" ? this.storage.file : undefined;
+    }
+    header() {
+        return this._header;
+    }
+    entries() {
+        return this._entries;
+    }
+    getEntry(id) {
+        return this.index.get(id);
+    }
+    leafId() {
+        return this.leaf;
+    }
+    append(input) {
+        if (this.closed)
+            throw new AmaError("session_closed", "session manager is closed");
+        const entry = {
+            ...input,
+            id: newEntryId(this.index),
+            parentId: this.leaf,
+            timestamp: this.now().toISOString(),
+        };
+        if (this.storage.kind === "file")
+            appendLines(this.storage.file, [entry]);
+        this._entries.push(entry);
+        this.index.set(entry.id, entry);
+        this.leaf = entry.id;
+        return entry;
+    }
+    setLeaf(id) {
+        if (id !== null && !this.index.has(id)) {
+            throw new AmaError("invalid_arguments", `no such session entry: ${id}`);
+        }
+        this.leaf = id;
+        if (this.storage.kind === "file")
+            appendLines(this.storage.file, [this.leafLine()]);
+    }
+    leafLine() {
+        return { type: "leaf", id: this.leaf, timestamp: this.now().toISOString() };
+    }
+    branch(leafId) {
+        return pathToRoot(this.index, leafId === undefined ? this.leaf : leafId);
+    }
+    getEntries(since) {
+        if (since === undefined)
+            return { entries: [...this._entries], leafId: this.leaf };
+        const at = this._entries.findIndex((entry) => entry.id === since);
+        return {
+            entries: at < 0 ? [...this._entries] : this._entries.slice(at + 1),
+            leafId: this.leaf,
+        };
+    }
+    getTree() {
+        return buildTree(this._entries);
+    }
+    name() {
+        let name;
+        for (const entry of this._entries)
+            if (entry.type === "session_info")
+                name = entry.name;
+        return name;
+    }
+    setName(name) {
+        this.append({ type: "session_info", name });
+    }
+    fork(entryId) {
+        if (!this.index.has(entryId)) {
+            throw new AmaError("invalid_arguments", `no such session entry: ${entryId}`);
+        }
+        const copied = this.branch(entryId).map((entry) => structuredClone(entry));
+        const options = { now: this.now };
+        const parentFile = this.file();
+        if (parentFile !== undefined)
+            options.parentSession = parentFile;
+        const header = SessionManager.newHeader(this.cwd, options, this.now());
+        let storage;
+        if (this.storage.kind === "memory")
+            storage = { kind: "memory" };
+        else if (this.storage.kind === "lazy")
+            storage = { kind: "lazy", dir: this.storage.dir };
+        else
+            storage = { kind: "lazy", dir: dirname(this.storage.file) };
+        const forked = new SessionManager(header, copied, storage, this.now);
+        if (parentFile !== undefined)
+            forked.flush();
+        return forked;
+    }
+    // -------------------------------------------------------------------------
+    // 落盘控制
+    // -------------------------------------------------------------------------
+    /** 延迟会话：建文件、写头与缓存条目、加锁。返回文件路径（内存会话为 undefined）。幂等。 */
+    flush() {
+        if (this.closed)
+            throw new AmaError("session_closed", "session manager is closed");
+        if (this.storage.kind === "memory")
+            return undefined;
+        if (this.storage.kind === "file")
+            return this.storage.file;
+        const file = join(this.storage.dir, sessionFileName(new Date(this._header.timestamp), this.id));
+        const moved = this.leaf !== (this._entries.at(-1)?.id ?? null);
+        writeNewSessionFile(file, [
+            this._header,
+            ...this._entries,
+            ...(moved ? [this.leafLine()] : []),
+        ]);
+        let lock;
+        try {
+            lock = acquireLock(file);
+        }
+        catch {
+            lock = undefined;
+        }
+        this.storage = { kind: "file", file, lock };
+        return file;
+    }
+    isPersisted() {
+        return this.storage.kind === "file";
+    }
+    isInMemory() {
+        return this.storage.kind === "memory";
+    }
+    /** 会话文件所在目录（内存会话 undefined）。 */
+    directory() {
+        if (this.storage.kind === "lazy")
+            return this.storage.dir;
+        if (this.storage.kind === "file")
+            return dirname(this.storage.file);
+        return undefined;
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.storage.kind === "file")
+            this.storage.lock?.release();
+    }
+}

package/dist/session/migrate.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 会话文件版本兜底（设计 §1.2「v1 文件读取兜底（预留）」）。[B2]
+ *
+ * 当前格式版本 1。读入的首行必须是 `type: "session"` 的头：
+ * - version 1 → 原样返回条目；
+ * - 更高版本 → 拒绝（session_corrupt，提示升级 ama）；
+ * - 缺头 / 头损坏 / 条目缺 id → 拒绝，不猜测、不重写文件。
+ * - [W3-C1b] `leaf` 行（`/tree` 位置，第三波 A7）不是条目：不进 entries；最后一条 leaf 行若在
+ *   最后一条条目之后，作为 `leafId` 返回（之后又追加了条目则作废）。id 须为字符串或 null。
+ * 将来格式升级时在这里加「旧版本 → 当前」的内存迁移（文件只追加，不回写）。
+ */
+import type { SessionEntry, SessionHeader, SessionLine } from "./types.js";
+export interface MigratedSession {
+    header: SessionHeader;
+    entries: SessionEntry[];
+    /** 晚于最后一条条目的 leaf 行给出的叶子；没有则缺省（叶子 = 最后一条条目）。 */
+    leafId?: string | null;
+}
+export declare function migrateSessionLines(lines: readonly SessionLine[], file?: string): MigratedSession;

package/dist/session/migrate.js

@@ -0,0 +1,53 @@
+/**
+ * 会话文件版本兜底（设计 §1.2「v1 文件读取兜底（预留）」）。[B2]
+ *
+ * 当前格式版本 1。读入的首行必须是 `type: "session"` 的头：
+ * - version 1 → 原样返回条目；
+ * - 更高版本 → 拒绝（session_corrupt，提示升级 ama）；
+ * - 缺头 / 头损坏 / 条目缺 id → 拒绝，不猜测、不重写文件。
+ * - [W3-C1b] `leaf` 行（`/tree` 位置，第三波 A7）不是条目：不进 entries；最后一条 leaf 行若在
+ *   最后一条条目之后，作为 `leafId` 返回（之后又追加了条目则作废）。id 须为字符串或 null。
+ * 将来格式升级时在这里加「旧版本 → 当前」的内存迁移（文件只追加，不回写）。
+ */
+import { AmaError } from "../errors.js";
+import { SESSION_FORMAT_VERSION } from "./types.js";
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function migrateSessionLines(lines, file = "<memory>") {
+    const [first, ...rest] = lines;
+    if (!isObject(first) || first["type"] !== "session") {
+        throw new AmaError("session_corrupt", `${file}: missing session header`);
+    }
+    const version = first["version"];
+    if (version !== SESSION_FORMAT_VERSION) {
+        throw new AmaError("session_corrupt", `${file}: unsupported session format version ${String(version)} (this ama reads version ${SESSION_FORMAT_VERSION})`);
+    }
+    if (typeof first["id"] !== "string" || typeof first["cwd"] !== "string") {
+        throw new AmaError("session_corrupt", `${file}: malformed session header`);
+    }
+    const entries = [];
+    let leafId;
+    rest.forEach((line, i) => {
+        if (isObject(line) && line["type"] === "leaf") {
+            const id = line["id"];
+            if (id !== null && typeof id !== "string") {
+                throw new AmaError("session_corrupt", `${file}:${i + 2}: malformed leaf line`);
+            }
+            leafId = id;
+            return;
+        }
+        if (!isObject(line) || typeof line["id"] !== "string" || typeof line["type"] !== "string") {
+            throw new AmaError("session_corrupt", `${file}:${i + 2}: malformed entry`);
+        }
+        if (line["type"] === "session") {
+            throw new AmaError("session_corrupt", `${file}:${i + 2}: duplicate session header`);
+        }
+        entries.push(line);
+        leafId = undefined;
+    });
+    const result = { header: first, entries };
+    if (leafId !== undefined)
+        result.leafId = leafId;
+    return result;
+}

package/dist/session/projection.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 投影（设计 §8、§9）：活动分支 → 进上下文的消息。[B2]
+ *
+ * - `buildContextEntries(branch)`：若路径上有 compaction，取最新一条：先放 compaction，再放
+ *   `firstKeptEntryId` 到 compaction 之间的非 system 条目，再放 compaction 之后的条目。
+ * - `buildProjection(branch)`：对上一步的条目套用 `context_edit`（同一目标在活动分支上最新一条赢；
+ *   `null` 剔除，字符串只换内容、保留角色与元数据），并把每个条目映射为 `AgentMessage`。
+ *   有 compaction 时，compaction 之前的全部 system 消息折成一条完整的 system 检查点放在最前
+ *   （会话条目里不另存检查点，重放即可得到）。
+ * - `buildContext(branch)`：投影消息 + 路径上最近的模型 / 思考级别选择。
+ */
+import type { Message, ModelRef, ModelThinkingLevel, SystemMessage, ToolDecl } from "../ai/types.js";
+import type { AgentMessage, CompactionEntry, ContextEditEntry, SessionEntry } from "./types.js";
+export interface ContextItem {
+    /** 来源条目（system 检查点的来源是 compaction 条目）。 */
+    entry: SessionEntry;
+    message: AgentMessage;
+}
+export interface Projection {
+    items: ContextItem[];
+    messages: AgentMessage[];
+    /** 生效的最新 compaction。 */
+    compaction: CompactionEntry | undefined;
+}
+export interface ProjectedContext {
+    messages: AgentMessage[];
+    model: ModelRef | undefined;
+    thinkingLevel: ModelThinkingLevel | undefined;
+}
+/**
+ * 条目 → 上下文消息；不进上下文的条目返回 undefined（model_change、label、custom、
+ * 第三波的 `usage` 条目等）。
+ */
+export declare function entryToMessage(entry: SessionEntry): AgentMessage | undefined;
+export declare function buildContextEntries(branch: readonly SessionEntry[]): SessionEntry[];
+/** 活动分支上每个目标最新的 context_edit。 */
+export declare function collectContextEdits(branch: readonly SessionEntry[]): Map<string, ContextEditEntry>;
+/** 用替换文本换掉消息内容，保留角色与元数据。 */
+export declare function applyReplacement(message: AgentMessage, text: string): AgentMessage;
+export interface SystemState {
+    /** 节名 → 文本，按首次出现顺序。 */
+    sections: Record<string, string>;
+    tools: ToolDecl[];
+}
+/** 依次应用转录里的 system 消息（首条全量，之后是补丁）；没有 system 消息 → undefined。 */
+export declare function replaySystem(messages: Iterable<AgentMessage | Message>): SystemState | undefined;
+/** 把重放结果写成一条完整的 system 消息。 */
+export declare function systemCheckpoint(state: SystemState, timestamp: number): SystemMessage;
+export declare function buildProjection(branch: readonly SessionEntry[]): Projection;
+export declare function buildContext(branch: readonly SessionEntry[]): ProjectedContext;