@mickorz/opencode-agentic-workflow 0.3.0

package/dist/metrics/collector.js

@@ -0,0 +1,246 @@
+/**
+ * MetricsCollector（P2.6）—— 纯事件总线消费者
+ *
+ *   EventBus ─→ MetricsCollector ─→ snapshot（内存聚合，随时可查）
+ *
+ * 设计约束（与 P2.4 一脉相承）：
+ *   - 零侵入：不改动 agent()/sequence()/verify() 等原语的任何逻辑，
+ *     只订阅事件流；token/cost 经 agent.completed 事件透传（数据源是
+ *     宿主 executor 提取的 AgentResult.usage/costUSD）。
+ *   - 只聚合、不采样：计数与求和，不保存明细（明细在 journal/trace）。
+ *   - 按 workflowId / 模型维度聚合；单 run 的明细数据以 journal 为准
+ *     （journal 有每步时间戳与状态，run 级 rollup 未来可由 store 派生）。
+ */
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { getEventBus } from "../observability/events.js";
+function emptyDuration() {
+    return { count: 0, totalMs: 0, minMs: Number.POSITIVE_INFINITY, maxMs: 0, lastMs: 0 };
+}
+function recordDuration(stats, ms) {
+    stats.count += 1;
+    stats.totalMs += ms;
+    stats.minMs = Math.min(stats.minMs, ms);
+    stats.maxMs = Math.max(stats.maxMs, ms);
+    stats.lastMs = ms;
+}
+function emptyTokens() {
+    return { input: 0, output: 0, reasoning: 0, cacheRead: 0, cacheWrite: 0 };
+}
+function addTokens(target, usage) {
+    target.input += usage.input;
+    target.output += usage.output;
+    target.reasoning += usage.reasoning;
+    target.cacheRead += usage.cache.read;
+    target.cacheWrite += usage.cache.write;
+}
+function emptySnapshot() {
+    return {
+        since: Date.now(),
+        updatedAt: 0,
+        agents: {
+            calls: 0,
+            failed: 0,
+            duration: emptyDuration(),
+            tokens: emptyTokens(),
+            costUSD: 0,
+            byModel: {},
+        },
+        workflows: {},
+        steps: { completed: 0, failed: 0, totalMs: 0 },
+        checks: { total: 0, passed: 0 },
+        verifies: { total: 0, passed: 0, reviewerPassed: 0, reviewerTotal: 0 },
+        checkpoints: { waiting: 0, approved: 0, rejected: 0 },
+    };
+}
+export class MetricsCollector {
+    bus;
+    unsubscribe;
+    state = emptySnapshot();
+    /** 订阅指定 bus（缺省全局 bus） */
+    constructor(bus = getEventBus()) {
+        this.bus = bus;
+        this.unsubscribe = bus.subscribe((event) => this.handle(event));
+    }
+    workflowStats(id) {
+        let stats = this.state.workflows[id];
+        if (!stats) {
+            stats = { started: 0, completed: 0, failed: 0, duration: emptyDuration() };
+            this.state.workflows[id] = stats;
+        }
+        return stats;
+    }
+    handle(event) {
+        const s = this.state;
+        s.updatedAt = event.time;
+        switch (event.type) {
+            case "agent.started":
+                break;
+            case "agent.completed": {
+                s.agents.calls += 1;
+                recordDuration(s.agents.duration, event.durationMs);
+                if (event.usage)
+                    addTokens(s.agents.tokens, event.usage);
+                if (typeof event.costUSD === "number")
+                    s.agents.costUSD += event.costUSD;
+                if (event.model || event.usage) {
+                    const key = event.model ?? "(unknown)";
+                    let model = s.agents.byModel[key];
+                    if (!model) {
+                        model = { calls: 0, tokens: emptyTokens(), costUSD: 0 };
+                        s.agents.byModel[key] = model;
+                    }
+                    model.calls += 1;
+                    if (event.usage)
+                        addTokens(model.tokens, event.usage);
+                    if (typeof event.costUSD === "number")
+                        model.costUSD += event.costUSD;
+                }
+                break;
+            }
+            case "agent.failed":
+                s.agents.failed += 1;
+                break;
+            case "workflow.started": {
+                const wf = this.workflowStats(event.workflowId);
+                wf.started += 1;
+                break;
+            }
+            case "workflow.completed": {
+                const wf = this.workflowStats(event.workflowId);
+                wf.completed += 1;
+                recordDuration(wf.duration, event.durationMs);
+                break;
+            }
+            case "workflow.failed": {
+                const wf = this.workflowStats(event.workflowId);
+                wf.failed += 1;
+                break;
+            }
+            case "step.completed":
+                s.steps.completed += 1;
+                s.steps.totalMs += event.durationMs;
+                break;
+            case "step.failed":
+                s.steps.failed += 1;
+                break;
+            case "check.completed":
+                s.checks.total += 1;
+                if (event.ok)
+                    s.checks.passed += 1;
+                break;
+            case "verify.completed":
+                s.verifies.total += 1;
+                if (event.passed)
+                    s.verifies.passed += 1;
+                s.verifies.reviewerPassed += event.passedCount;
+                s.verifies.reviewerTotal += event.totalCount;
+                break;
+            case "checkpoint.waiting":
+                s.checkpoints.waiting += 1;
+                break;
+            case "checkpoint.completed":
+                if (event.approved)
+                    s.checkpoints.approved += 1;
+                else
+                    s.checkpoints.rejected += 1;
+                break;
+            default:
+                break;
+        }
+    }
+    /** 当前聚合快照（深拷贝，调用方修改不影响内部状态） */
+    snapshot() {
+        return JSON.parse(JSON.stringify(this.state));
+    }
+    /** 清零重新收集 */
+    reset() {
+        this.state = emptySnapshot();
+    }
+    /** 停止订阅 */
+    dispose() {
+        this.unsubscribe();
+    }
+    /**
+     * 快照落盘：workflow 结束（completed/failed）时把当前聚合写到 <file>。
+     * 写失败只记录日志，绝不影响 workflow（观测设施不能成为故障源）。
+     */
+    subscribeFileSink(file) {
+        this.bus.subscribe((event) => {
+            if (event.type !== "workflow.completed" && event.type !== "workflow.failed")
+                return;
+            const snapshot = this.snapshot();
+            void (async () => {
+                try {
+                    await fs.mkdir(path.dirname(file), { recursive: true });
+                    await fs.writeFile(file, JSON.stringify({ ...snapshot, writtenAt: Date.now() }, null, 2), "utf8");
+                }
+                catch (error) {
+                    console.log(`[agentic-workflow] metrics sink write failed: ` +
+                        `${error instanceof Error ? error.message : String(error)}`);
+                }
+            })();
+        });
+    }
+}
+function fmtMs(ms) {
+    if (ms >= 60_000)
+        return `${(ms / 60_000).toFixed(1)}min`;
+    if (ms >= 1_000)
+        return `${(ms / 1_000).toFixed(1)}s`;
+    return `${ms}ms`;
+}
+function fmtTokens(n) {
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(2)}M`;
+    if (n >= 1_000)
+        return `${(n / 1_000).toFixed(1)}k`;
+    return String(n);
+}
+function fmtDurationLine(d) {
+    if (d.count === 0)
+        return "n/a";
+    const min = Number.isFinite(d.minMs) ? fmtMs(d.minMs) : "-";
+    return `avg ${fmtMs(Math.round(d.totalMs / d.count))} / min ${min} / max ${fmtMs(d.maxMs)} (n=${d.count})`;
+}
+/** 人读快照（工具返回文本用） */
+export function formatMetrics(m) {
+    const a = m.agents;
+    const lines = [];
+    lines.push(`# Workflow Metrics（自 ${new Date(m.since).toISOString()} 起）`);
+    lines.push("");
+    lines.push("## Agents");
+    lines.push(`- 调用 ${a.calls} 次（失败 ${a.failed}）`);
+    lines.push(`- 耗时：${fmtDurationLine(a.duration)}`);
+    lines.push(`- tokens：in ${fmtTokens(a.tokens.input)} / out ${fmtTokens(a.tokens.output)} / ` +
+        `reasoning ${fmtTokens(a.tokens.reasoning)} / cache r ${fmtTokens(a.tokens.cacheRead)} w ${fmtTokens(a.tokens.cacheWrite)}`);
+    lines.push(`- 成本：$${a.costUSD.toFixed(4)}`);
+    if (Object.keys(a.byModel).length > 0) {
+        lines.push("- 按模型：");
+        for (const [model, stats] of Object.entries(a.byModel)) {
+            lines.push(`  - ${model}: ${stats.calls} 次, in ${fmtTokens(stats.tokens.input)} / ` +
+                `out ${fmtTokens(stats.tokens.output)}, $${stats.costUSD.toFixed(4)}`);
+        }
+    }
+    lines.push("");
+    lines.push("## Workflows");
+    const wfEntries = Object.entries(m.workflows);
+    if (wfEntries.length === 0) {
+        lines.push("- （无）");
+    }
+    else {
+        for (const [id, wf] of wfEntries) {
+            lines.push(`- ${id}: started ${wf.started} / completed ${wf.completed} / failed ${wf.failed}; ` +
+                `耗时 ${fmtDurationLine(wf.duration)}`);
+        }
+    }
+    lines.push("");
+    lines.push("## 质量门");
+    lines.push(`- check: ${m.checks.passed}/${m.checks.total} 通过` +
+        (m.checks.total > 0 ? "" : "（无）"));
+    lines.push(`- verify: ${m.verifies.passed}/${m.verifies.total} 次（reviewer ${m.verifies.reviewerPassed}/${m.verifies.reviewerTotal}）`);
+    lines.push(`- checkpoint: ${m.checkpoints.approved} 批准 / ${m.checkpoints.rejected} 拒绝`);
+    lines.push(`- steps: ${m.steps.completed} 完成 / ${m.steps.failed} 失败（累计 ${fmtMs(m.steps.totalMs)}）`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=collector.js.map

package/dist/metrics/collector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.js","sourceRoot":"","sources":["../../src/metrics/collector.ts"],"names":[],"mappings":"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"}

package/dist/observability/events.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Workflow 事件总线（P2.4 observability 地基）
+ *
+ * phase() 从 metadata 升级为事件源：所有核心原语（agent/check/verify/checkpoint/
+ * sequence/workflow）在关键节点派发结构化事件，后续 TUI、metrics、debug、
+ * trace 文件全部消费这一套事件流。
+ *
+ * 设计原则：
+ *   - 事件小而可序列化（JSON-safe），便于落盘与跨进程传输
+ *   - 派发同步、fan-out；handler 抛错被隔离（监听器绝不能破坏 workflow 本身）
+ *   - 全局默认 bus 可替换（setEventBus），测试/宿主可注入自己的 bus
+ */
+import type { TokenUsage } from "../runtime/executor.js";
+export interface WorkflowEventBase {
+    /** epoch ms */
+    time: number;
+}
+export type WorkflowEvent = WorkflowEventBase & ({
+    type: "workflow.started";
+    workflowId: string;
+    args?: Record<string, unknown>;
+} | {
+    type: "workflow.completed";
+    workflowId: string;
+    durationMs: number;
+} | {
+    type: "workflow.failed";
+    workflowId: string;
+    error: string;
+} | {
+    type: "phase.started";
+    name: string;
+} | {
+    type: "agent.started";
+    promptPreview: string;
+} | {
+    type: "agent.completed";
+    durationMs: number;
+    outputLength: number;
+    /** token 用量（宿主能提供时；metrics 消费） */
+    usage?: TokenUsage;
+    /** 美元成本（宿主直接给出时） */
+    costUSD?: number;
+    /** 实际使用的模型 "providerID/id" */
+    model?: string;
+} | {
+    type: "agent.failed";
+    durationMs: number;
+    error: string;
+} | {
+    type: "check.completed";
+    label: string;
+    ok: boolean;
+} | {
+    type: "verify.completed";
+    label: string;
+    passed: boolean;
+    passedCount: number;
+    totalCount: number;
+} | {
+    type: "checkpoint.waiting";
+    label: string;
+    message: string;
+} | {
+    type: "checkpoint.completed";
+    label: string;
+    approved: boolean;
+} | {
+    type: "step.started";
+    index: number;
+} | {
+    type: "step.completed";
+    index: number;
+    durationMs: number;
+} | {
+    type: "step.failed";
+    index: number;
+    error: string;
+});
+/** 派发用入参（无需填 time，emitEvent 自动补） */
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+export type EventInput = DistributiveOmit<WorkflowEvent, "time">;
+export type EventHandler = (event: WorkflowEvent) => void;
+export interface EventBus {
+    dispatch(event: WorkflowEvent): void;
+    /** 返回取消订阅函数 */
+    subscribe(handler: EventHandler): () => void;
+}
+/** 进程内同步 fan-out 事件总线（默认实现） */
+export declare function createEventBus(): EventBus;
+/** 替换全局 bus（测试/宿主注入） */
+export declare function setEventBus(bus: EventBus): void;
+/** 当前全局 bus */
+export declare function getEventBus(): EventBus;
+/** 派发事件（自动补 time） */
+export declare function emitEvent(event: EventInput): void;
+/** prompt 摘要（事件保持小而可序列化） */
+export declare function preview(text: string, max?: number): string;
+export {};

package/dist/observability/events.js

@@ -0,0 +1,55 @@
+/**
+ * Workflow 事件总线（P2.4 observability 地基）
+ *
+ * phase() 从 metadata 升级为事件源：所有核心原语（agent/check/verify/checkpoint/
+ * sequence/workflow）在关键节点派发结构化事件，后续 TUI、metrics、debug、
+ * trace 文件全部消费这一套事件流。
+ *
+ * 设计原则：
+ *   - 事件小而可序列化（JSON-safe），便于落盘与跨进程传输
+ *   - 派发同步、fan-out；handler 抛错被隔离（监听器绝不能破坏 workflow 本身）
+ *   - 全局默认 bus 可替换（setEventBus），测试/宿主可注入自己的 bus
+ */
+/** 进程内同步 fan-out 事件总线（默认实现） */
+export function createEventBus() {
+    const handlers = new Set();
+    return {
+        dispatch(event) {
+            for (const handler of handlers) {
+                try {
+                    handler(event);
+                }
+                catch (error) {
+                    // 监听器异常隔离：只记录，绝不影响 workflow
+                    console.log(`[agentic-workflow] event handler failed on ${event.type}: ` +
+                        `${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+        },
+        subscribe(handler) {
+            handlers.add(handler);
+            return () => {
+                handlers.delete(handler);
+            };
+        },
+    };
+}
+let currentBus = createEventBus();
+/** 替换全局 bus（测试/宿主注入） */
+export function setEventBus(bus) {
+    currentBus = bus;
+}
+/** 当前全局 bus */
+export function getEventBus() {
+    return currentBus;
+}
+/** 派发事件（自动补 time） */
+export function emitEvent(event) {
+    currentBus.dispatch({ ...event, time: Date.now() });
+}
+/** prompt 摘要（事件保持小而可序列化） */
+export function preview(text, max = 80) {
+    const collapsed = text.replace(/\s+/g, " ").trim();
+    return collapsed.length <= max ? collapsed : `${collapsed.slice(0, max)}…`;
+}
+//# sourceMappingURL=events.js.map

package/dist/observability/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/observability/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAuDH,+BAA+B;AAC/B,MAAM,UAAU,cAAc;IAC5B,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAgB,CAAA;IACxC,OAAO;QACL,QAAQ,CAAC,KAAoB;YAC3B,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;gBAC/B,IAAI,CAAC;oBACH,OAAO,CAAC,KAAK,CAAC,CAAA;gBAChB,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,4BAA4B;oBAC5B,OAAO,CAAC,GAAG,CACT,8CAA8C,KAAK,CAAC,IAAI,IAAI;wBAC1D,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAC9D,CAAA;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QACD,SAAS,CAAC,OAAqB;YAC7B,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;YACrB,OAAO,GAAG,EAAE;gBACV,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;YAC1B,CAAC,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED,IAAI,UAAU,GAAa,cAAc,EAAE,CAAA;AAE3C,wBAAwB;AACxB,MAAM,UAAU,WAAW,CAAC,GAAa;IACvC,UAAU,GAAG,GAAG,CAAA;AAClB,CAAC;AAED,eAAe;AACf,MAAM,UAAU,WAAW;IACzB,OAAO,UAAU,CAAA;AACnB,CAAC;AAED,qBAAqB;AACrB,MAAM,UAAU,SAAS,CAAC,KAAiB;IACzC,UAAU,CAAC,QAAQ,CAAC,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,EAAmB,CAAC,CAAA;AACtE,CAAC;AAED,4BAA4B;AAC5B,MAAM,UAAU,OAAO,CAAC,IAAY,EAAE,GAAG,GAAG,EAAE;IAC5C,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAA;IAClD,OAAO,SAAS,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAA;AAC5E,CAAC"}

package/dist/observability/observe.d.ts

@@ -0,0 +1,7 @@
+/**
+ * observeWorkflow —— workflow 级事件包装器（P2.4）
+ *
+ * 包住任意 async workflow 函数，派发 workflow.started / completed / failed。
+ * 嵌套调用会产生嵌套事件流（P2 单 workflow 场景不依赖强制去重）。
+ */
+export declare function observeWorkflow<T>(workflowId: string, fn: () => Promise<T>, args?: Record<string, unknown>): Promise<T>;

package/dist/observability/observe.js

@@ -0,0 +1,29 @@
+/**
+ * observeWorkflow —— workflow 级事件包装器（P2.4）
+ *
+ * 包住任意 async workflow 函数，派发 workflow.started / completed / failed。
+ * 嵌套调用会产生嵌套事件流（P2 单 workflow 场景不依赖强制去重）。
+ */
+import { emitEvent } from "./events.js";
+export async function observeWorkflow(workflowId, fn, args) {
+    emitEvent({ type: "workflow.started", workflowId, args });
+    const startedAt = Date.now();
+    try {
+        const result = await fn();
+        emitEvent({
+            type: "workflow.completed",
+            workflowId,
+            durationMs: Date.now() - startedAt,
+        });
+        return result;
+    }
+    catch (error) {
+        emitEvent({
+            type: "workflow.failed",
+            workflowId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        throw error;
+    }
+}
+//# sourceMappingURL=observe.js.map

package/dist/observability/observe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.js","sourceRoot":"","sources":["../../src/observability/observe.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAEvC,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,UAAkB,EAClB,EAAoB,EACpB,IAA8B;IAE9B,SAAS,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAA;IACzD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;IAC5B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,EAAE,EAAE,CAAA;QACzB,SAAS,CAAC;YACR,IAAI,EAAE,oBAAoB;YAC1B,UAAU;YACV,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;SACnC,CAAC,CAAA;QACF,OAAO,MAAM,CAAA;IACf,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,SAAS,CAAC;YACR,IAAI,EAAE,iBAAiB;YACvB,UAAU;YACV,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAC9D,CAAC,CAAA;QACF,MAAM,KAAK,CAAA;IACb,CAAC;AACH,CAAC"}

package/dist/observability/trace.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Execution Trace（P2.4）
+ *
+ * - createTraceCollector: 订阅 bus，收集事件流为内存数组（debug/断言/测试）
+ * - createFileTraceSink: 订阅 bus，逐事件追加 JSONL 文件（持久化观测）
+ *
+ * 事件已保证 JSON-safe（见 events.ts），可直接序列化。
+ */
+import { type EventBus, type WorkflowEvent } from "./events.js";
+export interface TraceCollector {
+    /** 收集到的事件快照（只读） */
+    readonly events: readonly WorkflowEvent[];
+    /** 停止收集 */
+    stop(): void;
+}
+/** 内存 trace 收集器（测试/调试用） */
+export declare function createTraceCollector(bus?: EventBus): TraceCollector;
+export interface TraceSink {
+    /** 停止订阅并落盘收尾 */
+    stop(): void;
+}
+/**
+ * JSONL 文件 trace sink：每事件一行追加写入。
+ * 写失败只记录（观测链路绝不影响 workflow 主链路）。
+ */
+export declare function createFileTraceSink(file: string, bus?: EventBus): TraceSink;

package/dist/observability/trace.js

@@ -0,0 +1,52 @@
+/**
+ * Execution Trace（P2.4）
+ *
+ * - createTraceCollector: 订阅 bus，收集事件流为内存数组（debug/断言/测试）
+ * - createFileTraceSink: 订阅 bus，逐事件追加 JSONL 文件（持久化观测）
+ *
+ * 事件已保证 JSON-safe（见 events.ts），可直接序列化。
+ */
+import { appendFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { getEventBus } from "./events.js";
+/** 内存 trace 收集器（测试/调试用） */
+export function createTraceCollector(bus) {
+    const events = [];
+    const off = (bus ?? getEventBus()).subscribe((event) => {
+        events.push(event);
+    });
+    return {
+        get events() {
+            return events;
+        },
+        stop: off,
+    };
+}
+/**
+ * JSONL 文件 trace sink：每事件一行追加写入。
+ * 写失败只记录（观测链路绝不影响 workflow 主链路）。
+ */
+export function createFileTraceSink(file, bus) {
+    const target = bus ?? getEventBus();
+    let directory = path.dirname(file);
+    let pending = Promise.resolve();
+    const off = target.subscribe((event) => {
+        // 串行化追加，避免行交错
+        pending = pending
+            .then(async () => {
+            await mkdir(directory, { recursive: true });
+            await appendFile(file, JSON.stringify(event) + "\n", "utf8");
+        })
+            .catch((error) => {
+            console.log(`[agentic-workflow] trace sink write failed: ` +
+                `${error instanceof Error ? error.message : String(error)}`);
+        });
+    });
+    return {
+        stop() {
+            off();
+            directory = directory; // no-op，保持引用形状稳定
+        },
+    };
+}
+//# sourceMappingURL=trace.js.map

package/dist/observability/trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../src/observability/trace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,IAAI,MAAM,WAAW,CAAA;AAE5B,OAAO,EAAE,WAAW,EAAqC,MAAM,aAAa,CAAA;AAS5E,2BAA2B;AAC3B,MAAM,UAAU,oBAAoB,CAAC,GAAc;IACjD,MAAM,MAAM,GAAoB,EAAE,CAAA;IAClC,MAAM,GAAG,GAAG,CAAC,GAAG,IAAI,WAAW,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;QACrD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACpB,CAAC,CAAC,CAAA;IACF,OAAO;QACL,IAAI,MAAM;YACR,OAAO,MAAM,CAAA;QACf,CAAC;QACD,IAAI,EAAE,GAAG;KACV,CAAA;AACH,CAAC;AAOD;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY,EAAE,GAAc;IAC9D,MAAM,MAAM,GAAG,GAAG,IAAI,WAAW,EAAE,CAAA;IACnC,IAAI,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,IAAI,OAAO,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAA;IAE9C,MAAM,GAAG,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;QACrC,cAAc;QACd,OAAO,GAAG,OAAO;aACd,IAAI,CAAC,KAAK,IAAI,EAAE;YACf,MAAM,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;YAC3C,MAAM,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAA;QAC9D,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YACxB,OAAO,CAAC,GAAG,CACT,8CAA8C;gBAC5C,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAC9D,CAAA;QACH,CAAC,CAAC,CAAA;IACN,CAAC,CAAC,CAAA;IAEF,OAAO;QACL,IAAI;YACF,GAAG,EAAE,CAAA;YACL,SAAS,GAAG,SAAS,CAAA,CAAC,iBAAiB;QACzC,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/plugin/checkpoint-rpc.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Checkpoint RPC 契约（P2.3，server 与 TUI 双形态共享）
+ *
+ * 流向：
+ *   server workflow -> checkpoint() -> InteractiveCheckpointGate
+ *     --emit--> rpc.agentic-workflow.requested { requestId, label, message }
+ *     <--call-- TUI: ui.dialog.confirm -> rpc "reply" { requestId, approved, reason? }
+ *
+ * 事件经 OpenCode 事件流广播（V2EventRpc），TUI 侧 ctx.data.on 订阅；
+ * 应答经 client.rpc(...)（或 rpc.call）回到 server 侧注册的 handler。
+ */
+export declare const CheckpointRpc: {
+    readonly id: "agentic-workflow";
+    readonly methods: {
+        /** TUI -> server：应答审批请求 */
+        readonly reply: {
+            readonly input: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly requestId: {
+                        readonly type: "string";
+                    };
+                    readonly approved: {
+                        readonly type: "boolean";
+                    };
+                    readonly reason: {
+                        readonly type: "string";
+                    };
+                };
+                readonly required: readonly ["requestId", "approved"];
+                readonly additionalProperties: false;
+            };
+            readonly output: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly ok: {
+                        readonly type: "boolean";
+                    };
+                };
+                readonly required: readonly ["ok"];
+                readonly additionalProperties: false;
+            };
+        };
+    };
+    readonly events: {
+        /** server -> TUI：审批请求 */
+        readonly requested: {
+            readonly schema: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly requestId: {
+                        readonly type: "string";
+                    };
+                    readonly label: {
+                        readonly type: "string";
+                    };
+                    readonly message: {
+                        readonly type: "string";
+                    };
+                };
+                readonly required: readonly ["requestId", "label", "message"];
+                readonly additionalProperties: false;
+            };
+        };
+    };
+};
+/** TUI 订阅用的事件名（字面量类型，保证 data.on 类型匹配；与 CheckpointRpc.id 的一致性由单测保证） */
+export declare const CHECKPOINT_REQUESTED_EVENT: "rpc.agentic-workflow.requested";
+/** 解析 TUI 应答（handler 入参为 unknown，需手动收窄） */
+export declare function parseCheckpointReply(input: unknown): {
+    requestId: string;
+    approved: boolean;
+    reason?: string;
+} | undefined;