agent-trellis 0.19.0 → 0.21.0

package/dist/evolve/extension.js

@@ -0,0 +1,63 @@
+/**
+ * 进化订阅者型扩展的 `activate` 包装(design 8.1 定案的装载契约;trees
+ * 11.1/11.5 的生产接线)。
+ *
+ * 装载契约:模块导出 `activate(ctx)` 返回 `{ providers?, subscribers? }`,
+ * 由 `~/.trellis/mcp/extensions.yaml` 的清单条目(进化启用命令写入)
+ * 指向本模块;gateway 启动时动态 import 并装载。契约的结构形状与
+ * `src/lib/hostExtensions.ts` 的 `HostExtension*` 一致——import 边界
+ * (10.3)不允许 `src/evolve/` 引 `src/lib/*`,这里以结构类型对接,
+ * 由装载集成测试证明形状兼容。
+ *
+ * 订阅者按级别(activate 时解析,本进程恒定——gateway 按会话拉起):
+ *   - `off`:零订阅者(结构上零副作用;清单条目本应在置 off 时被移除,
+ *     此处是防御)。
+ *   - `observe` 及以上:recorder(事件 → 信号,enabled 恒真——级别已判)。
+ *   - `propose`/`auto-A`:另有触发器订阅者(会话结束判定拉起作业、会话
+ *     启动补偿判定)。observe 是"只采集信号",不拉起作业。
+ */
+import { fileURLToPath } from "node:url";
+import { loadEvolveLevelPolicy, resolveEvolveLevel } from "../host/levels.js";
+import { createSignalRecorder } from "./recorder.js";
+import { maybeLaunchOnSessionEnd, maybeLaunchOnSessionStart } from "./trigger.js";
+/** 清单条目 id(进化启用命令写入 `~/.trellis/mcp/extensions.yaml` 用)。 */
+export const EVOLVE_EXTENSION_ID = "evolve";
+function levelAt(context) {
+    const policy = loadEvolveLevelPolicy(context.homeDir);
+    return resolveEvolveLevel(policy, {
+        agent: context.agent,
+        workspaceRoot: context.workspaceRoot,
+    });
+}
+export function activate(context) {
+    const level = levelAt(context);
+    if (level === "off")
+        return {};
+    const recorder = createSignalRecorder({
+        homeDir: context.homeDir,
+        enabled: () => true,
+    });
+    const subscribers = [recorder.handle];
+    if (level !== "observe") {
+        const policy = loadEvolveLevelPolicy(context.homeDir);
+        const options = {
+            homeDir: context.homeDir,
+            enabled: () => true,
+            ...(policy.trigger !== undefined ? { limits: policy.trigger } : {}),
+        };
+        subscribers.push((event) => {
+            if (event.kind === "session_end")
+                maybeLaunchOnSessionEnd(options);
+            else if (event.kind === "session_start")
+                maybeLaunchOnSessionStart(options);
+        });
+    }
+    return { subscribers };
+}
+/**
+ * 清单条目的 `load` 模块说明符:本模块的绝对路径(dist 的 .js;经 tsx
+ * 直跑源码时为 .ts,动态 import 都能吃)。进化启用命令写清单时取此值。
+ */
+export function evolveExtensionLoadSpecifier() {
+    return fileURLToPath(import.meta.url);
+}

package/dist/evolve/gate.d.ts

@@ -0,0 +1,95 @@
+/**
+ * L1 doctor-oracle 前闸(trellis-evolve 任务 12.1)。
+ *
+ * 两副职责:
+ *
+ * 1. **提案类域分派**:仅 `L1_CONFIG_KINDS` 白名单内的配置类提案进入
+ *    提案通道;内容类提案本期不产出(等 L2 选择器执行落地)。design D8
+ *    "L1 适用域的判定由 L4 治理层按 kind 白名单执行"——本模块就是该判定
+ *    点,12.2 的机械校验对提案 kind 的准入与此同源。
+ * 2. **确定性候选 verdict 差集**:对真实 baseline 与 staging 候选各运行
+ *    一组结构化检查(doctor findings、`sync --check`、secrets audit),
+ *    按 (稳定 id, 层归属) 集合差判定。在 L1 适用域内该差集是**唯一
+ *    verdict**,配置类提案不运行引擎评分链。
+ *
+ * 可采纳判据(design D8,从严):无新条目 ∧ 全部目标条目被消除 ∧ 其余
+ * 条目不变(未声明的消除也算变化)。目标条目 = 提案 evidence 中
+ * `doctor-finding` 链接的 `findingId`(即 CheckEntry.id);`Proposal.target`
+ * 本身是被编辑面的锚点(spec:"目标为某 MCP server auth 块"、"目标路径
+ * 位于某仓库的 .agents/ 内"),不是检查条目——两者职责分开,本闸只消费
+ * findingId。目标条目不在 baseline 时"无法确认修复",按不采纳收口。
+ *
+ * staging 复现层分裂:`createStaging` 拷 scratch 全局 HOME + 临时
+ * workspace root(墓碑生效),提案 edits 由本模块把真实面绝对路径重定位
+ * 到 scratch(越界不采纳);baseline 与候选都带 `logicalWorkspaceRoot`
+ * 归一化,条目比较键含层归属(`workspace(<root>)` 与全局不混)。
+ *
+ * 失败收口(Risks 8):staging/应用/测量任何意外错误一律"不采纳",
+ * 测量结果记 `unknown`(空条目集,绝不表示为零分或通过);域外提案同样
+ * 不采纳。全部判定都写入运行档案(kind `"verdict"`,含 baseline 与
+ * candidate 两份完整测量)。
+ */
+import type { EvidenceLink, Proposal, Verdict, VerdictEntry } from "./types.js";
+import { type ApplyEditsOptions, type ApplyEditsResult, type CheckResult, type CreateStagingOptions, type RunChecksOptions, type Staging } from "../host/index.js";
+/** 档案 kind:一次 L1 verdict(两份完整测量 + 判定原因)。 */
+export declare const VERDICT_ARCHIVE_KIND = "verdict";
+/**
+ * L1 适用域:配置类 kind 白名单(design D8)。名单内提案进入提案通道,
+ * L1 差集作唯一 verdict;名单外(含内容类——skill/记忆/指令正文等)本
+ * 期不产出提案,等 L2 选择器执行落地。命名与 12.2 rule-based/editor
+ * 提案的产出侧保持一致。
+ */
+export declare const L1_CONFIG_KINDS: ReadonlySet<string>;
+export interface ProposalDomainDispatch {
+    readonly domain: "config" | "content";
+    /** 仅配置类进入提案通道;内容类本期不产出。 */
+    readonly entersProposalChannel: boolean;
+    readonly note: string;
+}
+/** 提案类域分派:白名单内 = 配置类(进通道),其余 = 内容类(不产出)。 */
+export declare function dispatchProposalDomain(kind: string): ProposalDomainDispatch;
+/**
+ * 条目比较键:(稳定 id, 层归属)。"条目 SHALL 带着层归属参与比较"——
+ * 同一 id 在全局层与 workspace 层是两条不同记录,不互相抵消。
+ */
+export declare function entryKey(entry: VerdictEntry): string;
+export interface VerdictDiff {
+    /** 候选有、baseline 没有(引入的回归)。 */
+    readonly introduced: VerdictEntry[];
+    /** baseline 有、候选没有(被消除的条目)。 */
+    readonly resolved: VerdictEntry[];
+}
+/** 按 (id, layer) 做集合差;message 不参与比较(host/checks.ts 契约)。 */
+export declare function diffVerdictEntries(baseline: readonly VerdictEntry[], candidate: readonly VerdictEntry[]): VerdictDiff;
+/** 提案 evidence 中的目标条目(evidence 的 doctor-finding.findingId
+ * 即 CheckEntry.id;`Proposal.target` 是编辑面锚点,不在此列)。 */
+export declare function doctorFindingTargetIds(evidence: readonly EvidenceLink[]): string[];
+export interface EvaluateL1Options {
+    /** 真实面 HOME(档案也写在这里的 `~/.trellis/evolve/`)。 */
+    readonly homeDir: string;
+    /** 被测上下文的 workspace root;缺省/null = 纯全局上下文。 */
+    readonly workspaceRoot?: string | null;
+    readonly proposal: Proposal;
+    /** 注入缝(场景测试的强制报错收口);缺省走 host 真实实现。 */
+    readonly runChecksFn?: (options: RunChecksOptions) => Promise<CheckResult>;
+    readonly createStagingFn?: (options: CreateStagingOptions) => Staging;
+    readonly applyEditsFn?: (options: ApplyEditsOptions) => Promise<ApplyEditsResult>;
+    /** 时间源(毫秒);缺省 Date.now(档案打戳)。 */
+    readonly now?: () => number;
+}
+export interface L1GateResult {
+    readonly decision: "acceptable" | "not-acceptable";
+    readonly reason: string;
+    readonly domain: "config" | "content";
+    readonly verdict: Verdict;
+    readonly targetIds: readonly string[];
+    /** 引入的新条目(不可采纳时入档)。 */
+    readonly introduced: readonly VerdictEntry[];
+    readonly resolvedIds: readonly string[];
+}
+/**
+ * L1 前闸完整判定:域分派 → staging 副本(层分裂复现)→ edits 重定位并
+ * 应用 → baseline/候选各跑三组结构化检查 → (id, layer) 差集 → 判定并
+ * 入档。任何意外错误按"不采纳"收口、测量记 unknown;不吞掉入档写失败。
+ */
+export declare function evaluateL1Proposal(options: EvaluateL1Options): Promise<L1GateResult>;

package/dist/evolve/gate.js

@@ -0,0 +1,295 @@
+/**
+ * L1 doctor-oracle 前闸(trellis-evolve 任务 12.1)。
+ *
+ * 两副职责:
+ *
+ * 1. **提案类域分派**:仅 `L1_CONFIG_KINDS` 白名单内的配置类提案进入
+ *    提案通道;内容类提案本期不产出(等 L2 选择器执行落地)。design D8
+ *    "L1 适用域的判定由 L4 治理层按 kind 白名单执行"——本模块就是该判定
+ *    点,12.2 的机械校验对提案 kind 的准入与此同源。
+ * 2. **确定性候选 verdict 差集**:对真实 baseline 与 staging 候选各运行
+ *    一组结构化检查(doctor findings、`sync --check`、secrets audit),
+ *    按 (稳定 id, 层归属) 集合差判定。在 L1 适用域内该差集是**唯一
+ *    verdict**,配置类提案不运行引擎评分链。
+ *
+ * 可采纳判据(design D8,从严):无新条目 ∧ 全部目标条目被消除 ∧ 其余
+ * 条目不变(未声明的消除也算变化)。目标条目 = 提案 evidence 中
+ * `doctor-finding` 链接的 `findingId`(即 CheckEntry.id);`Proposal.target`
+ * 本身是被编辑面的锚点(spec:"目标为某 MCP server auth 块"、"目标路径
+ * 位于某仓库的 .agents/ 内"),不是检查条目——两者职责分开,本闸只消费
+ * findingId。目标条目不在 baseline 时"无法确认修复",按不采纳收口。
+ *
+ * staging 复现层分裂:`createStaging` 拷 scratch 全局 HOME + 临时
+ * workspace root(墓碑生效),提案 edits 由本模块把真实面绝对路径重定位
+ * 到 scratch(越界不采纳);baseline 与候选都带 `logicalWorkspaceRoot`
+ * 归一化,条目比较键含层归属(`workspace(<root>)` 与全局不混)。
+ *
+ * 失败收口(Risks 8):staging/应用/测量任何意外错误一律"不采纳",
+ * 测量结果记 `unknown`(空条目集,绝不表示为零分或通过);域外提案同样
+ * 不采纳。全部判定都写入运行档案(kind `"verdict"`,含 baseline 与
+ * candidate 两份完整测量)。
+ */
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { appendArchiveRecord } from "./archive.js";
+import { applyEdits, createStaging, runChecks, } from "../host/index.js";
+/** 档案 kind:一次 L1 verdict(两份完整测量 + 判定原因)。 */
+export const VERDICT_ARCHIVE_KIND = "verdict";
+/**
+ * L1 适用域:配置类 kind 白名单(design D8)。名单内提案进入提案通道,
+ * L1 差集作唯一 verdict;名单外(含内容类——skill/记忆/指令正文等)本
+ * 期不产出提案,等 L2 选择器执行落地。命名与 12.2 rule-based/editor
+ * 提案的产出侧保持一致。
+ */
+export const L1_CONFIG_KINDS = new Set([
+    /** workspace 层配置面修复(如 `.codex/config.toml` 解析错误)。 */
+    "workspace-config-fix",
+    /** MCP 定义/路由等配置面修复(凭据字面值在校验阶段硬拒)。 */
+    "mcp-config-fix",
+    /** 托管投递面漂移修复(sync 可见面)。 */
+    "sync-config-fix",
+    /** secrets 策略配置修复(变量名/拒绝模式,不含任何凭据值)。 */
+    "secrets-policy-fix",
+    /** OAuth 配置元数据修复(kind/owner/client 元数据,不含凭据)。 */
+    "oauth-config-fix",
+]);
+/** 提案类域分派:白名单内 = 配置类(进通道),其余 = 内容类(不产出)。 */
+export function dispatchProposalDomain(kind) {
+    if (L1_CONFIG_KINDS.has(kind)) {
+        return {
+            domain: "config",
+            entersProposalChannel: true,
+            note: `kind "${kind}" 属配置类,进入提案通道(L1 差集为唯一 verdict)`,
+        };
+    }
+    return {
+        domain: "content",
+        entersProposalChannel: false,
+        note: `kind "${kind}" 不在配置类白名单,本期不产出提案(等 L2 选择器执行落地)`,
+    };
+}
+/**
+ * 条目比较键:(稳定 id, 层归属)。"条目 SHALL 带着层归属参与比较"——
+ * 同一 id 在全局层与 workspace 层是两条不同记录,不互相抵消。
+ */
+export function entryKey(entry) {
+    const layerKey = entry.layer.kind === "global" ? "global" : `workspace(${entry.layer.root})`;
+    return `${entry.id} ${layerKey}`;
+}
+/** 按 (id, layer) 做集合差;message 不参与比较(host/checks.ts 契约)。 */
+export function diffVerdictEntries(baseline, candidate) {
+    const baselineKeys = new Set(baseline.map(entryKey));
+    const candidateKeys = new Set(candidate.map(entryKey));
+    return {
+        introduced: candidate.filter((entry) => !baselineKeys.has(entryKey(entry))),
+        resolved: baseline.filter((entry) => !candidateKeys.has(entryKey(entry))),
+    };
+}
+/** 提案 evidence 中的目标条目(evidence 的 doctor-finding.findingId
+ * 即 CheckEntry.id;`Proposal.target` 是编辑面锚点,不在此列)。 */
+export function doctorFindingTargetIds(evidence) {
+    return evidence
+        .filter((link) => link.kind === "doctor-finding")
+        .map((link) => link.findingId);
+}
+function unknownVerdict(layer) {
+    return { status: "unknown", layer, baseline: [], candidate: [] };
+}
+/** `path` 是否落在某个真实面根之下(不含根本身)。 */
+function isInsideRoots(path, roots) {
+    const resolved = resolve(path);
+    for (const root of roots) {
+        if (!root)
+            continue;
+        const rel = relative(resolve(root), resolved);
+        if (rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel))
+            return true;
+    }
+    return false;
+}
+/** 真实面绝对路径 → staging scratch 对应路径;越界抛错(不采纳)。
+ * workspace 根优先(可能嵌套在 HOME 下,与 checks 的归一化同序)。 */
+function relocateIntoStaging(path, ctx) {
+    const roots = [];
+    if (ctx.workspaceRoot && ctx.staging.workspaceRoot) {
+        roots.push({ real: ctx.workspaceRoot, scratch: ctx.staging.workspaceRoot });
+    }
+    roots.push({ real: ctx.homeDir, scratch: ctx.staging.homeDir });
+    const resolved = resolve(path);
+    for (const { real, scratch } of roots) {
+        if (!scratch)
+            continue;
+        const rel = relative(resolve(real), resolved);
+        if (rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel)) {
+            return join(scratch, rel);
+        }
+    }
+    throw new Error(`edit path escapes the measured surface: ${path}`);
+}
+/** 符号链接 target:落在真实面内才重定位到 scratch(链接不指向真实面);
+ * 相对路径与面外绝对路径保持原义(校验阶段的职责不在此)。 */
+function relocateTargetIfInside(target, ctx) {
+    if (!isAbsolute(target))
+        return target;
+    if (!isInsideRoots(target, [ctx.workspaceRoot, ctx.homeDir]))
+        return target;
+    return relocateIntoStaging(target, ctx);
+}
+function relocateEdits(edits, ctx) {
+    return edits.map((edit) => {
+        const path = relocateIntoStaging(edit.path, ctx);
+        switch (edit.op) {
+            case "write-file":
+            case "remove-symlink":
+                return { ...edit, path };
+            case "create-symlink":
+            case "repair-symlink":
+                return { ...edit, path, target: relocateTargetIfInside(edit.target, ctx) };
+        }
+    });
+}
+/**
+ * L1 前闸完整判定:域分派 → staging 副本(层分裂复现)→ edits 重定位并
+ * 应用 → baseline/候选各跑三组结构化检查 → (id, layer) 差集 → 判定并
+ * 入档。任何意外错误按"不采纳"收口、测量记 unknown;不吞掉入档写失败。
+ */
+export async function evaluateL1Proposal(options) {
+    const homeDir = options.homeDir;
+    const workspaceRoot = options.workspaceRoot ?? null;
+    const proposal = options.proposal;
+    const stamp = () => new Date((options.now ?? Date.now)());
+    const dispatch = dispatchProposalDomain(proposal.kind);
+    const settle = (outcome) => {
+        const result = {
+            decision: outcome.decision,
+            reason: outcome.reason,
+            domain: dispatch.domain,
+            verdict: outcome.verdict,
+            targetIds: outcome.targetIds,
+            introduced: outcome.introduced,
+            resolvedIds: outcome.resolvedIds,
+        };
+        // 两份 verdict 入档:baseline 与 candidate 完整条目集 + 判定原因。
+        appendArchiveRecord(homeDir, {
+            kind: VERDICT_ARCHIVE_KIND,
+            payload: {
+                proposalId: proposal.id,
+                kind: proposal.kind,
+                domain: dispatch.domain,
+                decision: outcome.decision,
+                reason: outcome.reason,
+                status: outcome.verdict.status,
+                layer: outcome.verdict.layer,
+                targetIds: outcome.targetIds,
+                introduced: outcome.introduced,
+                resolvedIds: outcome.resolvedIds,
+                baseline: outcome.verdict.baseline,
+                candidate: outcome.verdict.candidate,
+            },
+        }, stamp);
+        return result;
+    };
+    // 域分派:内容类本期不产出(等 L2)——不测量、不通过。
+    if (!dispatch.entersProposalChannel) {
+        return settle({
+            decision: "not-acceptable",
+            reason: dispatch.note,
+            verdict: unknownVerdict(proposal.layer),
+            targetIds: [],
+            introduced: [],
+            resolvedIds: [],
+        });
+    }
+    const targetIds = doctorFindingTargetIds(proposal.evidence);
+    if (targetIds.length === 0) {
+        return settle({
+            decision: "not-acceptable",
+            reason: "提案证据中没有 doctor-finding 目标条目,无法确认修复",
+            verdict: unknownVerdict(proposal.layer),
+            targetIds: [],
+            introduced: [],
+            resolvedIds: [],
+        });
+    }
+    const runChecksFn = options.runChecksFn ?? runChecks;
+    const createStagingFn = options.createStagingFn ?? createStaging;
+    const applyEditsFn = options.applyEditsFn ?? applyEdits;
+    let staging = null;
+    try {
+        staging = createStagingFn({ homeDir, workspaceRoot });
+        const edits = relocateEdits(proposal.edits, { homeDir, workspaceRoot, staging });
+        if (edits.length > 0) {
+            await applyEditsFn({ homeDir: staging.homeDir, edits, command: "evolve-l1-gate" });
+        }
+        // baseline:真实面;candidate:staging scratch。两侧都带
+        // logicalWorkspaceRoot 归一化,scratch 路径不进比较身份。
+        const baselineResult = await runChecksFn({
+            homeDir,
+            workspaceRoot,
+            logicalWorkspaceRoot: workspaceRoot,
+        });
+        const candidateResult = await runChecksFn({
+            homeDir: staging.homeDir,
+            workspaceRoot: staging.workspaceRoot,
+            logicalWorkspaceRoot: staging.logicalWorkspaceRoot,
+        });
+        const baseline = baselineResult.entries;
+        const candidate = candidateResult.entries;
+        const diff = diffVerdictEntries(baseline, candidate);
+        const targetIdSet = new Set(targetIds);
+        const baselineIds = new Set(baseline.map((entry) => entry.id));
+        const missingTargets = targetIds.filter((id) => !baselineIds.has(id));
+        const targetKeys = new Set(baseline.filter((entry) => targetIdSet.has(entry.id)).map(entryKey));
+        const resolvedKeys = new Set(diff.resolved.map(entryKey));
+        const resolvedIds = diff.resolved.map((entry) => entry.id);
+        const okVerdict = { status: "ok", layer: proposal.layer, baseline, candidate };
+        const common = { verdict: okVerdict, targetIds, introduced: diff.introduced, resolvedIds };
+        // 目标条目必须在 baseline 里——不在则"无法确认修复"。
+        if (missingTargets.length > 0) {
+            return settle({
+                ...common,
+                decision: "not-acceptable",
+                reason: `目标条目不在 baseline(${missingTargets.join(", ")}),无法确认修复`,
+            });
+        }
+        // 无新条目。
+        if (diff.introduced.length > 0) {
+            return settle({
+                ...common,
+                decision: "not-acceptable",
+                reason: `候选引入 ${diff.introduced.length} 个 baseline 中不存在的新条目`,
+            });
+        }
+        // 目标条目被消除 ∧ 其余不变(未声明的消除也算变化)。
+        const targetsAllResolved = [...targetKeys].every((key) => resolvedKeys.has(key));
+        const noExtraResolved = resolvedKeys.size === targetKeys.size && [...resolvedKeys].every((key) => targetKeys.has(key));
+        if (!targetsAllResolved) {
+            return settle({ ...common, decision: "not-acceptable", reason: "目标条目未被完全消除" });
+        }
+        if (!noExtraResolved) {
+            return settle({
+                ...common,
+                decision: "not-acceptable",
+                reason: "候选消除了未声明的条目,其余不满足不变约束",
+            });
+        }
+        return settle({
+            ...common,
+            decision: "acceptable",
+            reason: "候选消除全部目标条目,无新条目,其余不变",
+        });
+    }
+    catch (err) {
+        // Risks 8:意外错误一律不采纳,测量记 unknown,绝不表示为通过。
+        return settle({
+            decision: "not-acceptable",
+            reason: `测量/应用失败,按'不采纳'收口: ${err instanceof Error ? err.message : String(err)}`,
+            verdict: unknownVerdict(proposal.layer),
+            targetIds,
+            introduced: [],
+            resolvedIds: [],
+        });
+    }
+    finally {
+        staging?.dispose();
+    }
+}

package/dist/evolve/importHistory.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 历史数据导入与幂等回填(trellis-evolve-run-backfill 任务 3.1/3.2)。
+ *
+ * 把用户**显式选定**的既有 session 数据回填为观察信号,供后续作业按
+ * 既有水位线消费。设计(D4):
+ *   - 适配器契约 `{ name, sniff, extract }`,首个适配器 `claude-code-jsonl`
+ *     (Claude Code 会话 transcript JSONL);
+ *   - 白名单元数据:timestamp / agent / 会话 / 工具名 / 耗时 / 结果类别 /
+ *     层归属 —— 入参、结果载体与自由文本正文一律不入库(与 recorder 的
+ *     字段白名单同一条线);所有字符串字段写入前经 `eraseSecrets`;
+ *   - 台账幂等:`evolve/imports/<sha256(内容)>.json` 记源摘要与已导条目
+ *     数,同一源重复导入为空操作;stableId `import:<digest 前 12 位>:<行号>`
+ *     确定性(重复导入/重复消费不产生重复信号或重复提案);
+ *   - 写入复用 recorder 的批量 append(0600/0700、并发安全);整批先
+ *     extract 校验、后写入,任何源不可解析即非零退出且零写入。
+ *
+ * 字段缺省语义(格式缺字段时):ImportedEntry 对应字段记 null —— 耗时
+ * 缺省 0(白名单无 unknown 态),结果类别缺省 "ok"(无错误指示),agent
+ * 缺省适配器常量 "claude-code",会话缺省源文件名(D4"会话 id=文件名")。
+ * 无工具名的记录(文本轮次等)不写为 tool-call 信号,计入 skippedNoTool。
+ * 结果类别按记录自带 is_error 归类(每条记录独立映射);tool_use 与其
+ * tool_result 在 transcript 中是不同记录,跨记录关联留待适配器后续细化。
+ */
+/** 导入条目的白名单元数据(缺字段缺 null;写入侧按文档化缺省补全)。 */
+export interface ImportedEntry {
+    readonly timestampMs: number | null;
+    readonly agent: string | null;
+    readonly session: string | null;
+    readonly tool: string | null;
+    readonly durationMs: number | null;
+    readonly result: "ok" | "error" | "timeout" | null;
+}
+export interface ExtractedEntry {
+    /** 源文件物理行号(1 起):stableId 序号,确定性不受过滤影响。 */
+    readonly lineNo: number;
+    readonly entry: ImportedEntry;
+}
+export interface ExtractResult {
+    readonly entries: readonly ExtractedEntry[];
+    /** 无法解析的坏行数(跳过计数,与读取侧容错同源)。 */
+    readonly badLines: number;
+    /** 无工具名的记录数(文本轮次等,不写为 tool-call 信号)。 */
+    readonly skippedNoTool: number;
+}
+/** 源适配器契约:sniff 判定形态,extract 抽白名单元数据(不写盘)。 */
+export interface HistoryAdapter {
+    readonly name: string;
+    sniff(path: string): boolean;
+    extract(path: string): ExtractResult;
+}
+/** 源不可解析(不存在/不可读/不匹配任何适配器):整批零写入收口。 */
+export declare class ImportSourceError extends Error {
+    readonly path: string;
+    constructor(path: string, reason: string);
+}
+/** 首个适配器:Claude Code 会话 transcript(JSONL)。 */
+export declare const claudeCodeJsonlAdapter: HistoryAdapter;
+/** 已注册适配器(按序 sniff;契约先行,更多源后置)。 */
+export declare const HISTORY_ADAPTERS: readonly HistoryAdapter[];
+export interface ImportHistoryOptions {
+    readonly homeDir: string;
+    /** 显式选定的源路径(仅此处理;不扫描目录、不自动发现)。 */
+    readonly paths: readonly string[];
+    /** `--workspace` 层归属;缺省全局层。 */
+    readonly workspaceRoot?: string;
+    /** 时间源(毫秒);缺省 Date.now(采集时刻与台账打戳)。 */
+    readonly now?: () => number;
+}
+export interface ImportedSourceResult {
+    readonly path: string;
+    readonly sourceDigest: string;
+    /** 本次写入条目数(已记账源为 0)。 */
+    readonly entries: number;
+    readonly badLines: number;
+    readonly skippedNoTool: number;
+    /** 已记账源(重复导入为空操作)。 */
+    readonly duplicate: boolean;
+}
+export interface ImportHistoryResult {
+    readonly sources: readonly ImportedSourceResult[];
+    readonly written: number;
+    readonly signalFile: string | null;
+}
+/** 台账文件路径(按源内容摘要命名;内容变 = 新源)。 */
+export declare function importLedgerPath(homeDir: string, digest: string): string;
+/**
+ * 整批导入:先对全部源 sniff + extract 校验(任何源不可解析即抛
+ * `ImportSourceError`,零写入),后一次性写信号与台账(台账最后记账,
+ * 中断重跑安全:未记账则重导,提案去重兜底)。不触发任何作业。
+ */
+export declare function importHistory(options: ImportHistoryOptions): ImportHistoryResult;