agent-trellis 0.19.0 → 0.21.0

package/dist/evolve/importHistory.js

@@ -0,0 +1,239 @@
+/**
+ * 历史数据导入与幂等回填(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 中是不同记录,跨记录关联留待适配器后续细化。
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { eraseSecrets } from "./erase.js";
+import { appendSignalLines, signalFilePath } from "./recorder.js";
+import { evolveStateDir } from "./stateDir.js";
+/** 源不可解析(不存在/不可读/不匹配任何适配器):整批零写入收口。 */
+export class ImportSourceError extends Error {
+    path;
+    constructor(path, reason) {
+        super(`历史源 ${path} 无法导入:${reason}`);
+        this.name = "ImportSourceError";
+        this.path = path;
+    }
+}
+function parseTimestamp(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const ms = Date.parse(raw);
+    return Number.isNaN(ms) ? null : ms;
+}
+/** 首个 tool_use 块的工具名(一条记录一元数据;多工具块取首个)。 */
+function firstToolName(record) {
+    const message = record.message;
+    const content = (message?.content ?? record.content);
+    if (Array.isArray(content)) {
+        for (const block of content) {
+            const b = block;
+            if (b.type === "tool_use" && typeof b.name === "string")
+                return b.name;
+            if (b.type === "tool_result" && typeof b.name === "string")
+                return b.name;
+        }
+    }
+    if (typeof record.tool === "string")
+        return record.tool;
+    if (typeof record.tool_name === "string")
+        return record.tool_name;
+    return null;
+}
+/** 记录自带的错误指示(顶层或内容块的 is_error);无指示为 null。 */
+function errorIndicator(record) {
+    let seen = typeof record.is_error === "boolean" ? record.is_error : null;
+    const message = record.message;
+    const content = (message?.content ?? record.content);
+    if (Array.isArray(content)) {
+        for (const block of content) {
+            const b = block;
+            if (typeof b.is_error === "boolean")
+                seen = seen === true || b.is_error;
+        }
+    }
+    return seen;
+}
+/** 首个适配器:Claude Code 会话 transcript(JSONL)。 */
+export const claudeCodeJsonlAdapter = {
+    name: "claude-code-jsonl",
+    sniff(path) {
+        if (!path.endsWith(".jsonl"))
+            return false;
+        try {
+            const first = readFileSync(path, "utf-8")
+                .split("\n")
+                .find((line) => line.trim() !== "");
+            if (first === undefined)
+                return false;
+            const record = JSON.parse(first);
+            return (typeof record === "object" &&
+                record !== null &&
+                ("type" in record || "sessionId" in record || "timestamp" in record || "uuid" in record));
+        }
+        catch {
+            return false;
+        }
+    },
+    extract(path) {
+        const text = readFileSync(path, "utf-8");
+        const stem = basename(path).replace(/\.jsonl$/, "");
+        const entries = [];
+        let badLines = 0;
+        let skippedNoTool = 0;
+        text.split("\n").forEach((line, index) => {
+            const trimmed = line.trim();
+            if (trimmed === "")
+                return;
+            let record;
+            try {
+                record = JSON.parse(trimmed);
+            }
+            catch {
+                badLines += 1;
+                return;
+            }
+            if (typeof record !== "object" || record === null) {
+                badLines += 1;
+                return;
+            }
+            const rec = record;
+            const tool = firstToolName(rec);
+            if (tool === null) {
+                skippedNoTool += 1;
+                return;
+            }
+            const isError = errorIndicator(rec);
+            entries.push({
+                lineNo: index + 1,
+                entry: {
+                    timestampMs: parseTimestamp(rec.timestamp),
+                    agent: null,
+                    session: stem,
+                    tool,
+                    durationMs: null,
+                    result: isError === null ? null : isError ? "error" : "ok",
+                },
+            });
+        });
+        return { entries, badLines, skippedNoTool };
+    },
+};
+/** 已注册适配器(按序 sniff;契约先行,更多源后置)。 */
+export const HISTORY_ADAPTERS = [claudeCodeJsonlAdapter];
+/** 台账文件路径(按源内容摘要命名;内容变 = 新源)。 */
+export function importLedgerPath(homeDir, digest) {
+    return join(evolveStateDir(homeDir), "imports", `${digest}.json`);
+}
+/**
+ * 整批导入:先对全部源 sniff + extract 校验(任何源不可解析即抛
+ * `ImportSourceError`,零写入),后一次性写信号与台账(台账最后记账,
+ * 中断重跑安全:未记账则重导,提案去重兜底)。不触发任何作业。
+ */
+export function importHistory(options) {
+    const now = options.now ?? Date.now;
+    const layer = options.workspaceRoot === undefined ? { kind: "global" } : { kind: "workspace", root: options.workspaceRoot };
+    const prepared = [];
+    const seenDigests = new Set();
+    const duplicates = new Map();
+    for (const path of options.paths) {
+        let content;
+        try {
+            content = readFileSync(path, "utf-8");
+        }
+        catch (err) {
+            throw new ImportSourceError(path, `不可读(${err instanceof Error ? err.message : String(err)})`);
+        }
+        const digest = createHash("sha256").update(content).digest("hex");
+        if (seenDigests.has(digest) || existsSync(importLedgerPath(options.homeDir, digest))) {
+            duplicates.set(path, {
+                path,
+                sourceDigest: digest,
+                entries: 0,
+                badLines: 0,
+                skippedNoTool: 0,
+                duplicate: true,
+            });
+            continue;
+        }
+        const adapter = HISTORY_ADAPTERS.find((candidate) => candidate.sniff(path));
+        if (adapter === undefined) {
+            throw new ImportSourceError(path, "不匹配任何已注册适配器(当前支持 Claude Code 会话 JSONL)");
+        }
+        seenDigests.add(digest);
+        prepared.push({ path, digest, extracted: adapter.extract(path) });
+    }
+    // ---- 阶段 2:写入(信号批量 append,台账最后记账) ----
+    const nowMs = now();
+    const allSignals = [];
+    const sources = [];
+    for (const item of prepared) {
+        const signals = [];
+        for (const { lineNo, entry } of item.extracted.entries) {
+            signals.push({
+                kind: "tool-call",
+                source: "history-import",
+                stableId: `import:${item.digest.slice(0, 12)}:${lineNo}`,
+                collectedAt: nowMs,
+                layer,
+                ts: entry.timestampMs ?? nowMs,
+                agent: eraseSecrets(entry.agent ?? "claude-code"),
+                session: eraseSecrets(entry.session ?? basename(item.path).replace(/\.jsonl$/, "")),
+                provider: eraseSecrets("claude-code"),
+                tool: eraseSecrets(entry.tool ?? "unknown"),
+                durationMs: entry.durationMs ?? 0,
+                result: entry.result ?? "ok",
+            });
+        }
+        allSignals.push(...signals);
+        sources.push({
+            path: item.path,
+            sourceDigest: item.digest,
+            entries: signals.length,
+            badLines: item.extracted.badLines,
+            skippedNoTool: item.extracted.skippedNoTool,
+            duplicate: false,
+        });
+    }
+    let signalFile = null;
+    if (allSignals.length > 0) {
+        signalFile = signalFilePath(options.homeDir, nowMs);
+        appendSignalLines(signalFile, allSignals);
+    }
+    for (const source of sources) {
+        const ledgerPath = importLedgerPath(options.homeDir, source.sourceDigest);
+        mkdirSync(dirname(ledgerPath), { recursive: true, mode: 0o700 });
+        writeFileSync(ledgerPath, `${JSON.stringify({
+            sourceDigest: source.sourceDigest,
+            entries: source.entries,
+            importedAtMs: nowMs,
+            layer,
+        }, null, 2)}\n`, { mode: 0o600 });
+    }
+    return {
+        sources: [...sources, ...duplicates.values()],
+        written: allSignals.length,
+        signalFile,
+    };
+}

package/dist/evolve/jobMain.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 一次性 detached 作业入口(trellis-evolve 任务 11.5)。
+ *
+ * 契约:argv = [--hold-ms N] [--trigger event|manual|chain] <homeDir>。
+ * `--hold-ms`(持有锁 N 毫秒后再收尾,供集成测试观察"作业运行中"的锁
+ * 状态;生产不传,作业即时完成)。`--trigger` 记录触发来源入 job-run
+ * 档案(缺省 event;chain 为补跑链起,run-backfill D3)。锁由作业自身
+ * 持有(拉起方 spawn 前只做活锁检查,本入口再权威抢一次以防并发双拉起
+ * 竞态,抢不到立即退出、不做任何工作、不排队)。壳语义(抢锁/释放、
+ * job-run 落档含 trigger 字段、错误收口)在 `jobShell.js`——`trellis
+ * evolve run` 前台手动触发走同一壳(D1 不另写执行路径)。作业体是
+ * rule-based 治理流水的一次运行:`runEvolveJob`(信号 → rule-based
+ * 提案 → 机械校验 → L1 前闸 → 风险/采纳门 → 应用 → lesson,14.1 的
+ * fixture E2E 同链)。引擎内核(packages/evolve-engine 的
+ * schedule/recursion/proposer/selection/judge)golden 锚定但生产未经
+ * 此消费,待 L2/探针任务集接入。级别 off/observe 时作业体零副作用早退。
+ *
+ * 注意:本文件是入口脚本,被 import 时顶层即执行;测试只应 spawn 它,
+ * 不应 import(需要锁原语请从 `trigger.js` 取,作业壳从 `jobShell.js`
+ * 取,作业体从 `jobRun.js` 取)。
+ */
+export {};

package/dist/evolve/jobMain.js

@@ -0,0 +1,52 @@
+/**
+ * 一次性 detached 作业入口(trellis-evolve 任务 11.5)。
+ *
+ * 契约:argv = [--hold-ms N] [--trigger event|manual|chain] <homeDir>。
+ * `--hold-ms`(持有锁 N 毫秒后再收尾,供集成测试观察"作业运行中"的锁
+ * 状态;生产不传,作业即时完成)。`--trigger` 记录触发来源入 job-run
+ * 档案(缺省 event;chain 为补跑链起,run-backfill D3)。锁由作业自身
+ * 持有(拉起方 spawn 前只做活锁检查,本入口再权威抢一次以防并发双拉起
+ * 竞态,抢不到立即退出、不做任何工作、不排队)。壳语义(抢锁/释放、
+ * job-run 落档含 trigger 字段、错误收口)在 `jobShell.js`——`trellis
+ * evolve run` 前台手动触发走同一壳(D1 不另写执行路径)。作业体是
+ * rule-based 治理流水的一次运行:`runEvolveJob`(信号 → rule-based
+ * 提案 → 机械校验 → L1 前闸 → 风险/采纳门 → 应用 → lesson,14.1 的
+ * fixture E2E 同链)。引擎内核(packages/evolve-engine 的
+ * schedule/recursion/proposer/selection/judge)golden 锚定但生产未经
+ * 此消费,待 L2/探针任务集接入。级别 off/observe 时作业体零副作用早退。
+ *
+ * 注意:本文件是入口脚本,被 import 时顶层即执行;测试只应 spawn 它,
+ * 不应 import(需要锁原语请从 `trigger.js` 取,作业壳从 `jobShell.js`
+ * 取,作业体从 `jobRun.js` 取)。
+ */
+import { runJobShell } from "./jobShell.js";
+const TRIGGER_KINDS = ["event", "manual", "chain"];
+const argv = process.argv.slice(2);
+let holdMs = 0;
+const holdIdx = argv.indexOf("--hold-ms");
+if (holdIdx !== -1) {
+    holdMs = Number(argv[holdIdx + 1] ?? 0);
+    argv.splice(holdIdx, 2);
+}
+let trigger = "event";
+const triggerIdx = argv.indexOf("--trigger");
+if (triggerIdx !== -1) {
+    const raw = argv[triggerIdx + 1];
+    if (raw === undefined || !TRIGGER_KINDS.includes(raw)) {
+        console.error(`jobMain: --trigger 必须是 ${TRIGGER_KINDS.join(" | ")}`);
+        process.exit(2);
+    }
+    trigger = raw;
+    argv.splice(triggerIdx, 2);
+}
+const homeDir = argv[argv.length - 1];
+if (homeDir === undefined || homeDir === "") {
+    console.error("jobMain: 用法 node jobMain.js [--hold-ms N] [--trigger event|manual|chain] <homeDir>");
+    process.exit(2);
+}
+const result = await runJobShell(homeDir, { trigger, holdMs });
+if (result.status === "error") {
+    console.error(`jobMain: 作业体失败:${result.message}`);
+    process.exitCode = 1;
+}
+// lock-busy:静默退出 0(竞态窗口已有作业在跑,不排队)。

package/dist/evolve/jobRun.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 一次性作业的作业体(trellis-evolve 任务 11.5;14.1 fixture E2E 的流水
+ * 在此落地为生产入口)。作业体是下述 rule-based 治理流水;引擎内核
+ * (packages/evolve-engine 的 schedule/recursion/proposer/selection/judge)
+ * golden 锚定但生产未经此消费,待 L2/探针任务集接入(review-fixes 纠偏
+ * 旧注"作业即运行移植引擎"的名不副实)。
+ *
+ * 流水(顺序即依赖,与 fixtureE2e 同链):
+ *   0. 级别闸:没有任何 propose/auto-A 设置 → 零副作用返回(触发器只在
+ *      propose+ 拉起;这里是直接 spawn 的防御)。
+ *   1. 可选源探测(11.3):agent-bridge 缺席记 unavailable,不失败。
+ *   2. 信号合并(自上次作业的信号合并时刻以来;首次为全部,11.5"未
+ *      消费"语义)。
+ *   3. 检查发现:全局 + 信号层归属出现过/级别策略声明过的 workspace,
+ *      各自 `runChecks`(L1 的 doctor oracle)。观察面即发现面——只有
+ *      进过信号/策略的 workspace 会被扫描(与"信号是观察记录"一致)。
+ *   4. 提案草稿:rule-based 通道——`proposeFromSignals` 的信号对齐路径
+ *      ∪ 当前发现直接 `ruleBasedProposal`(同一内核、提案 id 同源
+ *      `rule-<findingId>` 天然去重;已入 pending 的跳过)。editor/spawn
+ *      通道(design D7)在 `runDelegatedCall` 就绪前不在作业里拉真实
+ *      CLI 会话,见 `ProposalChannelAvailability` 注释。
+ *   5. 逐草稿治理:域分派(配置类才进通道)→ 机械校验(无 editor 不
+ *      重试)→ L1 前闸(verdict 差集,唯一 verdict)→ 风险分类(不采信
+ *      自报)→ 采纳门(A 仅 auto-A 且闸通过自动采纳并通知;B 永远待批)。
+ *      草稿的提案/采纳级别按其目标层解析(workspace > default;agent
+ *      粒度只闸观察与触发,不进提案产出——提案的来源 agent 不可考,
+ *      发现是 doctor 检查面而非 agent 行为)。
+ *   6. 应用阶段(12.5):全部已批准未应用的编辑在同一备份会话写入;
+ *      按 delivery 分类对原生渲染 agent 触发同步(host 门面 `triggerRenderSync`)。
+ *   7. lesson(12.6):本次应用的每条提案蒸馏一条 lesson;记忆启用走
+ *      记忆管道,否则只留档案(skipped 不是 failed)。
+ *
+ * 每步都只经 `src/host/*` 门面与本目录模块(边界 10.3);无模型调用、
+ * 不 spawn 真实 agent CLI。摘要返回给 jobMain 并入 job-run 档案。
+ */
+import type { CheckEntry } from "../host/index.js";
+import { type EvolveLevelPolicy } from "../host/index.js";
+import { type AgentEffectiveness, type ApplyAgent } from "./apply.js";
+import { type EvaluateL1Options, type L1GateResult } from "./gate.js";
+import { type OptionalSourceProbe } from "./sources.js";
+import type { Proposal, Signal } from "./types.js";
+/** 草稿来源的输入面(proposeFn 注入缝的契约)。 */
+export interface ProposeInput {
+    readonly homeDir: string;
+    readonly signals: readonly Signal[];
+    readonly findings: readonly CheckEntry[];
+    readonly now: () => number;
+}
+export interface RunEvolveJobOptions {
+    /** 时间源(毫秒);缺省 Date.now(测试注入固定时钟)。 */
+    readonly now?: () => number;
+    /** 草稿来源注入缝(测试直达治理层);缺省 rule-based 通道组装。 */
+    readonly proposeFn?: (input: ProposeInput) => readonly Proposal[];
+    /** L1 前闸注入缝(与 `EvaluateL1Options` 自带缝同风格);缺省真实闸。 */
+    readonly evaluateL1Fn?: (options: EvaluateL1Options) => Promise<L1GateResult>;
+    /** 应用阶段的 agent 分类(测试传空避开真实同步);缺省按 delivery 分类。 */
+    readonly applyAgents?: readonly ApplyAgent[];
+    /** 原生渲染同步触发缝;缺省 host `triggerRenderSync`。 */
+    readonly triggerSync?: () => Promise<{
+        exitCode: number;
+    }>;
+}
+export interface EvolveJobSummary {
+    readonly signalsConsidered: number;
+    readonly findingsConsidered: number;
+    readonly draftCount: number;
+    readonly enqueuedIds: string[];
+    readonly autoAdoptedIds: string[];
+    readonly discarded: readonly {
+        readonly id: string;
+        readonly code: string;
+        readonly reason: string;
+    }[];
+    readonly skippedNotes: readonly string[];
+    readonly applied: {
+        readonly runId: string | null;
+        readonly appliedProposalIds: readonly string[];
+        readonly syncExitCode: number | null;
+        /** 同步触发失败文本(收口为效果文本);无为 null。 */
+        readonly syncError: string | null;
+        /** 逐 agent 生效时点(review-fixes ❌3:随 job-run 档案入档)。 */
+        readonly effects: readonly AgentEffectiveness[];
+    };
+    readonly lessonIds: string[];
+    readonly notices: string[];
+    readonly optionalSources: readonly OptionalSourceProbe[];
+    /** 信号合并时刻(步骤 2 的 now());job-run 档案据此推进消费水位线,
+     * 作业运行期间到达的信号下次仍被消费。级别闸早退为 null(未合并)。 */
+    readonly signalsMergedAtMs: number | null;
+}
+/** 作业级闸:任一粒度出现 propose/auto-A 才值得运行(observe 只采集)。
+ * `trellis evolve run` 的早退判定与作业体同源(1.3)。 */
+export declare function anyProposalLevel(policy: EvolveLevelPolicy): boolean;
+export declare function runEvolveJob(homeDir: string, options?: RunEvolveJobOptions): Promise<EvolveJobSummary>;