agent-trellis 0.19.0 → 0.21.0

package/dist/evolve/recorder.d.ts

@@ -0,0 +1,68 @@
+/**
+ * gateway 进程内信号 recorder(trellis-evolve 任务 11.1)。
+ *
+ * 订阅托管事件总线(8.3),把事件元数据写入信号存储:
+ *   - 字段白名单:事件对象本身只有 metadata(8.2 类型层强制),写入侧
+ *     再按 Signal 信封逐字段拷贝,载荷载体永远不入库;
+ *   - secrets 擦除:所有字符串字段写入前经 eraseSecrets;
+ *   - 层归属:session_start 事件的 workspaceRoot 派生——该会话内全部
+ *     信号归属该 workspace 层,无归属记全局层;
+ *   - 按进程分文件、只追加:每个 gateway 进程一个
+ *     `signals/<pid>-<startMs>.jsonl`,进程内并发会话写同一文件
+ *     (单次 append 合并当轮缓冲,逐行 JSON),跨进程各写各文件,无全局锁;
+ *   - 异步落盘(review-fixes ❌4):`handle` 只入内存队列,事件循环内
+ *     批量落盘,热路径(工具调用事件)不碰磁盘;会话边界事件
+ *     (session_start/session_end)同步收口——边界事件正是触发判定的
+ *     运行点(补偿判定/会话结束判定),判定必须看得到含当前边界事件
+ *     在内的全部已记录信号;`flush()` 供测试与收尾。信号非审计级
+ *     (读取侧坏行容错同源),崩溃丢当轮缓冲可接受;
+ *   - off 零副作用:`enabled()` 为 false 时连目录与文件都不创建。
+ */
+import type { HostEvent } from "../host/hostEvents.js";
+import type { Signal } from "./types.js";
+export interface SignalRecorderOptions {
+    homeDir: string;
+    /** 级别开关(off 或 workspace 覆盖为 off 时返回 false)。缺省恒开。 */
+    enabled?: () => boolean;
+    /** 采集时间源(测试注入固定时钟);缺省 Date.now。 */
+    now?: () => number;
+}
+export interface SignalRecorder {
+    /** 本进程的信号文件路径(首写前文件不存在)。 */
+    readonly filePath: string;
+    /** 事件总线订阅者形态;返回值忽略(写入为队列化批量落盘)。 */
+    handle(event: HostEvent): void;
+    /** 立即落盘当轮缓冲(测试与收尾用;平时 setImmediate 批量落盘)。 */
+    flush(): void;
+}
+/** 进化自身活动的 agent 标识(作业/探针会话以此自称)。 */
+export declare const EVOLVE_SELF_AGENT = "trellis-evolve";
+/** 进化自身活动的会话标识前缀(11.5 的作业会话命名约定)。 */
+export declare const EVOLVE_SELF_SESSION_PREFIX = "evolve-job-";
+/** 防自激(11.3):进化系统自身的调用/编辑不进信号——否则作业会把自己
+ * 的活动记成信号、再触发下一轮作业。识别靠自身标识约定;编辑面本身不经
+ * 事件总线,结构上就不产生信号。 */
+export declare function isEvolveSelfActivity(event: HostEvent): boolean;
+export declare function createSignalRecorder(options: SignalRecorderOptions): SignalRecorder;
+/** 本进程的信号文件路径(按进程分文件;首写前文件不存在)。 */
+export declare function signalFilePath(homeDir: string, startMs: number): string;
+/** 只追加一行信号(单行 JSON;JSON.stringify 转义字符串内换行,行边界
+ * 天然成立;新建文件 0600——信号含 workspace 路径等机器信息,不收世界
+ * 可读)。11.2 的用户纠正上报走本单行入口;recorder 经批量入口
+ * `appendSignalLines`(同一写入路径)。 */
+export declare function appendSignalLine(filePath: string, signal: Signal): void;
+/** 批量只追加(同一 turn 的信号合并为一次 append;recorder 异步落盘用)。 */
+export declare function appendSignalLines(filePath: string, signals: readonly Signal[]): void;
+/**
+ * 读回一个信号文件的全部记录(测试与作业评估用;文件不存在返回空)。
+ * 容错:崩溃撕行(最后一次 append 只写了一部分)跳过该行继续——信号
+ * 不是审计级数据(对照 archive 的严格带行号抛错),一行损坏不应瘫痪
+ * 触发器/作业整条链。
+ */
+export declare function readSignals(filePath: string): Signal[];
+/**
+ * 合并读回全部进程信号文件里 `collectedAt > sinceMs`(null = 全部)的
+ * 记录(11.5 作业评估用;与 `trigger` 的 countPendingSignals 同一目录
+ * 遍历约定)。读取零副作用:不建目录、不排序语义(按文件名+行序)。
+ */
+export declare function readAllSignals(homeDir: string, sinceMs: number | null): Signal[];

package/dist/evolve/recorder.js

@@ -0,0 +1,169 @@
+/**
+ * gateway 进程内信号 recorder(trellis-evolve 任务 11.1)。
+ *
+ * 订阅托管事件总线(8.3),把事件元数据写入信号存储:
+ *   - 字段白名单:事件对象本身只有 metadata(8.2 类型层强制),写入侧
+ *     再按 Signal 信封逐字段拷贝,载荷载体永远不入库;
+ *   - secrets 擦除:所有字符串字段写入前经 eraseSecrets;
+ *   - 层归属:session_start 事件的 workspaceRoot 派生——该会话内全部
+ *     信号归属该 workspace 层,无归属记全局层;
+ *   - 按进程分文件、只追加:每个 gateway 进程一个
+ *     `signals/<pid>-<startMs>.jsonl`,进程内并发会话写同一文件
+ *     (单次 append 合并当轮缓冲,逐行 JSON),跨进程各写各文件,无全局锁;
+ *   - 异步落盘(review-fixes ❌4):`handle` 只入内存队列,事件循环内
+ *     批量落盘,热路径(工具调用事件)不碰磁盘;会话边界事件
+ *     (session_start/session_end)同步收口——边界事件正是触发判定的
+ *     运行点(补偿判定/会话结束判定),判定必须看得到含当前边界事件
+ *     在内的全部已记录信号;`flush()` 供测试与收尾。信号非审计级
+ *     (读取侧坏行容错同源),崩溃丢当轮缓冲可接受;
+ *   - off 零副作用:`enabled()` 为 false 时连目录与文件都不创建。
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { eraseSecrets } from "./erase.js";
+import { evolveStateDir } from "./stateDir.js";
+/** 进化自身活动的 agent 标识(作业/探针会话以此自称)。 */
+export const EVOLVE_SELF_AGENT = "trellis-evolve";
+/** 进化自身活动的会话标识前缀(11.5 的作业会话命名约定)。 */
+export const EVOLVE_SELF_SESSION_PREFIX = "evolve-job-";
+/** 防自激(11.3):进化系统自身的调用/编辑不进信号——否则作业会把自己
+ * 的活动记成信号、再触发下一轮作业。识别靠自身标识约定;编辑面本身不经
+ * 事件总线,结构上就不产生信号。 */
+export function isEvolveSelfActivity(event) {
+    return event.agent === EVOLVE_SELF_AGENT || event.session.startsWith(EVOLVE_SELF_SESSION_PREFIX);
+}
+export function createSignalRecorder(options) {
+    const now = options.now ?? Date.now;
+    const enabled = options.enabled ?? (() => true);
+    const filePath = signalFilePath(options.homeDir, now());
+    const layerBySession = new Map();
+    function layerFor(event) {
+        if (event.kind === "session_start") {
+            const layer = event.workspaceRoot === null ? { kind: "global" } : { kind: "workspace", root: event.workspaceRoot };
+            layerBySession.set(event.session, layer);
+            return layer;
+        }
+        return layerBySession.get(event.session) ?? { kind: "global" };
+    }
+    function toSignal(event) {
+        const common = {
+            source: "gateway-event",
+            stableId: null,
+            collectedAt: now(),
+            layer: layerFor(event),
+        };
+        const identity = {
+            ts: event.ts,
+            agent: eraseSecrets(event.agent),
+            session: eraseSecrets(event.session),
+        };
+        switch (event.kind) {
+            case "tool_call":
+                return {
+                    ...common,
+                    ...identity,
+                    kind: "tool-call",
+                    provider: eraseSecrets(event.provider),
+                    tool: eraseSecrets(event.tool),
+                    durationMs: event.durationMs,
+                    result: event.result,
+                };
+            case "session_start":
+                return { ...common, ...identity, kind: "session-start" };
+            case "session_end":
+                return { ...common, ...identity, kind: "session-end" };
+        }
+    }
+    // 队列化批量落盘:handle 只入队,一个事件循环 turn 内合并为一次 append
+    // (热路径不碰磁盘)。会话边界事件在边界同步收口——边界事件正是触发
+    // 判定的运行点(订阅者顺序在 recorder 之后),判定读盘时必须看得到含
+    // 本事件在内的全部信号;其余事件靠 setImmediate 合并。
+    const pending = [];
+    let flushScheduled = false;
+    function flush() {
+        flushScheduled = false;
+        if (pending.length === 0)
+            return;
+        const batch = pending.splice(0, pending.length);
+        appendSignalLines(filePath, batch);
+    }
+    return {
+        filePath,
+        handle(event) {
+            if (!enabled())
+                return;
+            if (isEvolveSelfActivity(event))
+                return;
+            pending.push(toSignal(event));
+            if (event.kind === "session_end" || event.kind === "session_start") {
+                flush();
+                return;
+            }
+            if (!flushScheduled) {
+                flushScheduled = true;
+                setImmediate(flush);
+            }
+        },
+        flush,
+    };
+}
+/** 本进程的信号文件路径(按进程分文件;首写前文件不存在)。 */
+export function signalFilePath(homeDir, startMs) {
+    return join(evolveStateDir(homeDir), "signals", `${process.pid}-${startMs}.jsonl`);
+}
+/** 只追加一行信号(单行 JSON;JSON.stringify 转义字符串内换行,行边界
+ * 天然成立;新建文件 0600——信号含 workspace 路径等机器信息,不收世界
+ * 可读)。11.2 的用户纠正上报走本单行入口;recorder 经批量入口
+ * `appendSignalLines`(同一写入路径)。 */
+export function appendSignalLine(filePath, signal) {
+    appendSignalLines(filePath, [signal]);
+}
+/** 批量只追加(同一 turn 的信号合并为一次 append;recorder 异步落盘用)。 */
+export function appendSignalLines(filePath, signals) {
+    if (signals.length === 0)
+        return;
+    mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+    appendFileSync(filePath, signals.map((signal) => JSON.stringify(signal) + "\n").join(""), { mode: 0o600 });
+}
+/**
+ * 读回一个信号文件的全部记录(测试与作业评估用;文件不存在返回空)。
+ * 容错:崩溃撕行(最后一次 append 只写了一部分)跳过该行继续——信号
+ * 不是审计级数据(对照 archive 的严格带行号抛错),一行损坏不应瘫痪
+ * 触发器/作业整条链。
+ */
+export function readSignals(filePath) {
+    if (!existsSync(filePath))
+        return [];
+    const signals = [];
+    for (const line of readFileSync(filePath, "utf-8").split("\n")) {
+        if (line === "")
+            continue;
+        try {
+            signals.push(JSON.parse(line));
+        }
+        catch {
+            // 坏行跳过(见头注释)。
+        }
+    }
+    return signals;
+}
+/**
+ * 合并读回全部进程信号文件里 `collectedAt > sinceMs`(null = 全部)的
+ * 记录(11.5 作业评估用;与 `trigger` 的 countPendingSignals 同一目录
+ * 遍历约定)。读取零副作用:不建目录、不排序语义(按文件名+行序)。
+ */
+export function readAllSignals(homeDir, sinceMs) {
+    const dir = join(evolveStateDir(homeDir), "signals");
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const name of readdirSync(dir).sort()) {
+        if (!name.endsWith(".jsonl"))
+            continue;
+        for (const signal of readSignals(join(dir, name))) {
+            if (sinceMs === null || signal.collectedAt > sinceMs)
+                out.push(signal);
+        }
+    }
+    return out;
+}

package/dist/evolve/report.d.ts

@@ -0,0 +1,26 @@
+/**
+ * agent 可调用的用户纠正上报入口(trellis-evolve 任务 11.2)。
+ *
+ * 内容级信号不从事件流捞(8.2 白名单的必然推论,见 design 9.4①):用户
+ * 纠正文本一律走本入口显式上报。文本写入前过 secrets 擦除;原始文本不
+ * 入库;层归属由调用方观察到的 workspace root 派生,root 本身不独立入库
+ * (只随 layer 保留)。与 recorder 共用按进程分文件的只追加写入路径。
+ */
+import type { UserCorrectionSignal } from "./types.js";
+/** 本进程用户纠正上报所写的信号文件路径。 */
+export declare function userCorrectionFilePath(homeDir: string): string;
+export interface UserCorrectionReport {
+    homeDir: string;
+    agent: string;
+    session: string;
+    /** 用户纠正文本原文;写入前擦除,原始文本不入库。 */
+    text: string;
+    /** 会话观察到的 workspace root;null/缺省记全局层。 */
+    workspaceRoot?: string | null;
+    /** 级别开关(off 返回 null 且不写入)。缺省恒开。 */
+    enabled?: () => boolean;
+    /** 采集时间源(测试注入固定时钟);缺省 Date.now。 */
+    now?: () => number;
+}
+/** 上报一条用户纠正;返回写入的信号,off 时返回 null。 */
+export declare function reportUserCorrection(report: UserCorrectionReport): UserCorrectionSignal | null;

package/dist/evolve/report.js

@@ -0,0 +1,37 @@
+/**
+ * agent 可调用的用户纠正上报入口(trellis-evolve 任务 11.2)。
+ *
+ * 内容级信号不从事件流捞(8.2 白名单的必然推论,见 design 9.4①):用户
+ * 纠正文本一律走本入口显式上报。文本写入前过 secrets 擦除;原始文本不
+ * 入库;层归属由调用方观察到的 workspace root 派生,root 本身不独立入库
+ * (只随 layer 保留)。与 recorder 共用按进程分文件的只追加写入路径。
+ */
+import { eraseSecrets } from "./erase.js";
+import { appendSignalLine, signalFilePath } from "./recorder.js";
+/** 与 recorder 同款"按进程分文件":进程内所有上报进同一文件。 */
+const PROCESS_START_MS = Date.now();
+/** 本进程用户纠正上报所写的信号文件路径。 */
+export function userCorrectionFilePath(homeDir) {
+    return signalFilePath(homeDir, PROCESS_START_MS);
+}
+/** 上报一条用户纠正;返回写入的信号,off 时返回 null。 */
+export function reportUserCorrection(report) {
+    if (report.enabled !== undefined && !report.enabled())
+        return null;
+    const now = report.now ?? Date.now;
+    const signal = {
+        kind: "user-correction",
+        source: "agent-report",
+        stableId: null,
+        collectedAt: now(),
+        layer: report.workspaceRoot == null
+            ? { kind: "global" }
+            : { kind: "workspace", root: report.workspaceRoot },
+        ts: now(),
+        agent: eraseSecrets(report.agent),
+        session: eraseSecrets(report.session),
+        text: eraseSecrets(report.text),
+    };
+    appendSignalLine(userCorrectionFilePath(report.homeDir), signal);
+    return signal;
+}

package/dist/evolve/reportView.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 进化可视化聚合层(trellis-evolve-visualization 任务 1.1)。
+ *
+ * 单一计算源:从三个只读来源(~/.trellis/evolve/archive/records.jsonl、
+ * evolve/pending/*.json、evolve.yaml)聚合出 `EvolveReport`,CLI 的
+ * `evolve report` / `status --json` 与 GUI sidecar 路由只是它的渲染/传输
+ * 壳——绝不维护第二份独立计算(gui-sidecar-api 的"读视图镜像 CLI"规约)。
+ *
+ * 只读零副作用:本模块永不 mkdir/append/write;全部指标可从档案重算,
+ * 每条趋势指标带口径说明(spec"趋势指标只来自真实测量")。数值评分
+ * (0-100 健康分之类)一律不合成——分数轴等 L2 探针任务集落地后另行变更。
+ */
+import { type EditOp, type Level, type SurfaceLayer } from "../host/index.js";
+/** 时间线一环:阶段、时间戳(ISO)与可读说明。 */
+export interface TimelineStep {
+    readonly stage: "proposed" | "discarded" | "verdict" | "decision" | "applied" | "lesson";
+    readonly at: string;
+    readonly note: string;
+}
+/** 前后测量(来自 L1 verdict 档案;无 verdict 时为 null,不推断)。 */
+export interface ProposalMeasurement {
+    readonly decision: string;
+    readonly reason: string;
+    readonly targetIds: readonly string[];
+    readonly resolvedIds: readonly string[];
+    readonly introduced: readonly string[];
+}
+/** 一条提案的全生命周期追踪(缺口如实呈现,不伪造补齐)。 */
+export interface ProposalTrace {
+    readonly id: string;
+    readonly summary: string;
+    readonly kind: string;
+    readonly riskClass: string | null;
+    readonly layer: SurfaceLayer | null;
+    /** 终态:discarded(校验/L1 丢弃)/ pending / approved(待应用)/
+     *  rejected / applied(已应用)。 */
+    readonly status: "discarded" | "pending" | "approved" | "rejected" | "applied";
+    readonly chain: readonly TimelineStep[];
+    /** 最近一次 L1 测量;整条提案无 verdict 档案时 null。 */
+    readonly measurement: ProposalMeasurement | null;
+    readonly edits: readonly EditOp[];
+    /** 应用时的备份会话标识(可据此回滚);未应用为 null。 */
+    readonly backupRunId: string | null;
+    /** 蒸馏的 lesson id;无为 null。 */
+    readonly lessonId: string | null;
+}
+/** 趋势指标(全部可从档案重算;口径随数据导出)。 */
+export interface TrendMetric {
+    readonly id: string;
+    readonly label: string;
+    /** 数值指标;无测量时 null(GUI 显示"无测量记录"而非 0)。 */
+    readonly value: number | null;
+    /** 数据口径:由哪类档案记录聚得(可重算依据)。 */
+    readonly source: string;
+}
+/** 一次作业运行(job-run 档案)。 */
+export interface JobRunEntry {
+    readonly startedAt: string;
+    readonly endedAt: string | null;
+    readonly ok: boolean;
+    readonly error: string | null;
+    /** 触发来源(run-backfill D1);旧档案无字段视作 `event`。 */
+    readonly trigger: "event" | "manual" | "chain";
+    readonly summary: {
+        readonly signalsConsidered: number | null;
+        readonly enqueued: number | null;
+        readonly autoAdopted: number | null;
+    };
+}
+/** 可视化状态:未开启 / 已开启未运行 / 有运行历史。 */
+export type EvolveViewState = "not-enabled" | "enabled-idle" | "active";
+export interface EvolveReport {
+    readonly state: EvolveViewState;
+    readonly levels: {
+        readonly defaultLevel: Level | null;
+        readonly agents: Readonly<Record<string, Level>>;
+        readonly workspaces: Readonly<Record<string, Level>>;
+    };
+    readonly counts: {
+        readonly pending: number;
+        readonly approved: number;
+        readonly rejected: number;
+        /** 已批准但未应用(可经 `trellis evolve apply` 消化)。 */
+        readonly approvedUnapplied: number;
+    };
+    readonly timeline: readonly ProposalTrace[];
+    readonly trends: readonly TrendMetric[];
+    readonly jobRuns: readonly JobRunEntry[];
+    readonly notices: readonly string[];
+}
+/**
+ * 聚合进化报告(纯读)。timeline 按提案 id 关联 proposal / proposal-reject /
+ * verdict / proposal-decision / apply-run / lesson 档案;链上缺环如实标注,
+ * 不推断补齐。
+ */
+export declare function buildEvolveReport(homeDir: string): EvolveReport;