@te-river/opencode-team-mode 1.7.1 → 1.7.3

package/dist/tm/ptc.js

@@ -1,865 +0,0 @@
-/**
- * tm_ptc_run — programmatic batch orchestration (M1–M3 all shipped).
- *
- * Design: .git/opencode-team/.../ptc-run/02-architect-ptc-run-design.md §2/§3/§4/§6.
- * M1 contract: args schema, the frozen `PtcEngine` seam, the StepGate failure
- * governance (error / call / time budgets, ≤1 retry on idempotent phases,
- * produced-output preservation), the five-state status enum, the char-pinned
- * aggregation summary, composite step numbers (`sXXXX.kNN`) and the
- * trajectory event shapes.
- * M2 engines: WorkerEngine (worker_threads + MessagePort RPC, env:{},
- * resourceLimits, hard `terminate()` wall-clock kill; bootstrap as a
- * build-time string), InlineVmEngine (node:vm runInNewContext fallback —
- * the script timeout kills pre-await synchronous busy-loops; a post-await
- * busy loop blocks the host event loop irrecoverably, documented —
- * prefer worker/auto), InlineSequentialEngine (M1 legacy, test-only).
- * staticPscan is wired as
- * the FIRST gate — banned tokens reject before any engine runs (in both
- * runPtc and the tool execute path).
- * M3 registration: tm/index merges tm_ptc_run into the `tools` map; since
- * v1.5.4 ALL SIX agents carry the allow (team included — CHANGELOG 1.5.4).
- *
- * Engine selection: TM_PTC_ENGINE=auto (default) | worker | inline.  auto
- * runs worker-first; an engine-error re-runs the WHOLE program on
- * InlineVmEngine (bridged calls are read-only, so a re-run is safe; the
- * fallback starts with fresh call/error budgets under the SAME wall-clock
- * deadline) and marks `degraded-engine` in the summary.
- *
- * Governance is REUSED, never forked (D6 lock): the inline bridge calls the
- * exact four exported pipelines (`buildPipelines`), so threshold offload,
- * P2/P3, R6 and handle/TTL semantics apply to every bridged call verbatim.
- * PTC is NOT a bypass layer.
- */
-import * as crypto from "node:crypto";
-import * as vm from "node:vm";
-import { estimateTokens, shouldOffload, shorten } from "./config.js";
-import { buildRef } from "./refs.js";
-import { detectContentType } from "./preview.js";
-import { tmError } from "./tools.js";
-// ---------- public contract types (frozen for M2's RPC surface) ----------
-/** The five PTC run statuses (design §2). */
-export const PTC_STATUS_VALUES = [
-    "ok",
-    "stopped-error-budget",
-    "stopped-call-budget",
-    "timeout",
-    "engine-error",
-];
-/** Bridge allow set — read-only; tm_ptc_run itself is excluded (no nesting). */
-export const BRIDGE_ALLOW = ["tm_read", "tm_grep", "tm_bash", "tm_fetch"];
-/** Phases safe to retry once (idempotent read-only bridges; design §4.2). */
-export const RETRYABLE_PHASES = ["client", "execute", "store"];
-/**
- * Clamp a caller-supplied budget against the resolved env ceiling.  Absent ->
- * the env ceiling; above the ceiling -> clamped DOWN (cannot loosen); below
- * the hard floor -> clamped UP to the floor.  Non-finite is ignored (ceiling).
- */
-function clampBudget(raw, ceiling, floor) {
-    const n = typeof raw === "number" ? raw : raw == null ? NaN : Number(raw);
-    if (!Number.isFinite(n))
-        return ceiling;
-    const i = Math.trunc(n);
-    if (i > ceiling)
-        return ceiling;
-    if (i < floor)
-        return floor;
-    return i;
-}
-export function resolvePtcBudgets(cfg, budgets) {
-    const b = budgets && typeof budgets === "object" ? budgets : {};
-    return {
-        maxCalls: clampBudget(b.max_calls, cfg.ptcMaxCalls, PTC_BUDGET_BOUNDS_FLOOR.maxCalls),
-        maxErrors: clampBudget(b.max_errors, cfg.ptcMaxErrors, PTC_BUDGET_BOUNDS_FLOOR.maxErrors),
-        timeoutMs: clampBudget(b.timeout_ms, cfg.ptcTimeoutMs, PTC_BUDGET_BOUNDS_FLOOR.timeoutMs),
-    };
-}
-// floors mirror config.ts PTC_BUDGET_BOUNDS (kept here so this module stays
-// self-contained for clamp tests without importing config internals).
-const PTC_BUDGET_BOUNDS_FLOOR = { maxCalls: 1, maxErrors: 1, timeoutMs: 5000 };
-// ---------- arg schema + validation ----------
-export const PTC_LABEL_MAX = 80;
-/**
- * Validate + normalize tm_ptc_run args.  `program` over the length cap is a
- * hard args error (a program cannot be meaningfully truncated); `label` over
- * 80 is truncated; `budgets` are clamped toward the env ceilings.
- */
-export function parsePtcArgs(raw, cfg) {
-    const a = raw ?? {};
-    const program = typeof a.program === "string" ? a.program : "";
-    if (!program.trim()) {
-        return { ok: false, error: tmError("tm_ptc_run", "args", "缺少 program 参数（async 函数体，可用 tm.read/tm.grep/tm.bash/tm.fetch）") };
-    }
-    if (program.length > cfg.ptcMaxProgramChars) {
-        return {
-            ok: false,
-            error: tmError("tm_ptc_run", "args", `program 超过长度上限 ${cfg.ptcMaxProgramChars} 字符（实际 ${program.length}）。请拆分批次或调高 TM_PTC_MAX_PROGRAM_CHARS。`),
-        };
-    }
-    let label = typeof a.label === "string" && a.label.trim() ? a.label.trim() : "ptc-run";
-    if (label.length > PTC_LABEL_MAX)
-        label = label.slice(0, PTC_LABEL_MAX);
-    const budgets = resolvePtcBudgets(cfg, a.budgets);
-    return { ok: true, args: { program, label, budgets } };
-}
-// ---------- static pre-scan (the FIRST gate: wired into runPtc + the tool) --
-/** Banned identifier tokens for the program source (auxiliary guard, not a
- *  security boundary — see design §3 trust model). */
-const PSCAN_PATTERNS = [
-    /\brequire\b/,
-    /\bimport\b/,
-    /\bprocess\b/,
-    /\bglobalThis\b/,
-    /\bDeno\b/,
-    /\bBun\b/,
-    /\bfs\b/,
-    /\bnet\b/,
-    /\bchild_process\b/,
-];
-/** Static scan of a program string — the FIRST gate: runPtc and
- *  buildPtcRunTool both reject a rejected program before any engine runs. */
-export function staticPscan(program) {
-    const tokens = [];
-    for (const re of PSCAN_PATTERNS) {
-        if (re.test(program))
-            tokens.push(re.source.replace(/\\b/g, "").replace(/\b/g, ""));
-    }
-    return { rejected: tokens.length > 0, tokens };
-}
-// ---------- the inline sequential engine (M1's only engine) ----------------
-class PtcStopSignal extends Error {
-    reason;
-    constructor(reason) {
-        super(`ptc-stop:${reason}`);
-        this.reason = reason;
-        this.name = "PtcStopSignal";
-    }
-}
-function makeFacade(bridge) {
-    const one = (tool) => (args) => bridge.call(tool, args && typeof args === "object" ? args : {});
-    return { read: one("tm_read"), grep: one("tm_grep"), bash: one("tm_bash"), fetch: one("tm_fetch") };
-}
-/** Best-effort line extraction from a program-side thrown error stack. */
-function extractLine(err) {
-    const s = err instanceof Error ? err.stack ?? "" : String(err ?? "");
-    const m = /:(\d+):/.exec(s);
-    if (m) {
-        const n = Number(m[1]);
-        if (Number.isFinite(n))
-            return n;
-    }
-    const m2 = /line[:#]?\s*(\d+)/i.exec(s);
-    return m2 ? Number(m2[1]) : undefined;
-}
-export class InlineSequentialEngine {
-    name = "inline";
-    async run(program, bridge, signal) {
-        // M1 legacy engine, kept test-only: the program runs as a trusted async
-        // function body on the MAIN thread — no sandbox, no timeout, and a
-        // post-await busy loop blocks the host event loop irrecoverably (same
-        // residual as InlineVmEngine).  Production runs WorkerEngine (auto
-        // default) or InlineVmEngine.
-        const AsyncFunction = Object.getPrototypeOf(async function () { }).constructor;
-        const tm = makeFacade(bridge);
-        let abortHandler;
-        const abortP = new Promise((_, rej) => {
-            // The driver only aborts on wall-clock timeout (budget stops flow through
-            // the gate as PtcStopSignal).  M2's worker engine adds terminate here.
-            abortHandler = () => rej(new PtcStopSignal("timeout"));
-            if (signal.aborted)
-                abortHandler();
-            else
-                signal.addEventListener("abort", abortHandler, { once: true });
-        });
-        try {
-            const fn = new AsyncFunction("tm", `"use strict";\n${program}`);
-            return await Promise.race([fn(tm), abortP]);
-        }
-        finally {
-            if (abortHandler)
-                signal.removeEventListener("abort", abortHandler);
-        }
-    }
-}
-// ---------- M2: worker engine (MessagePort RPC over worker_threads) ----------
-/**
- * Worker engine — runs the program in a dedicated `worker_threads.Worker`
- * with `env:{}` (process.env emptied), `resourceLimits`, and `terminate()`
- * for hard timeout kills.  The bootstrap source is a build-time template
- * string constant (zero runtime file IO, zero new deps, passes tsc).
- *
- * Probe result (P1, %TEMP%): ALL-GREEN on Node 24 / win32 — eval bootstrap,
- * postMessage bidirectional, terminate (9 ms), resourceLimits, env:{} all
- * verified.  Auto chain = worker-first, inline fallback.
- */
-export class WorkerEngine {
-    name = "worker";
-    async run(program, bridge, signal) {
-        const { Worker } = await import("node:worker_threads");
-        // Build the worker bootstrap source as a regular string (ts-safe).
-        // The worker receives {program, startDeadlineMs} via its first message,
-        // creates the tm facade, runs the program, and sends RPC call requests
-        // back to the driver which executes them through the gate bridge.
-        const src = [
-            '"use strict";',
-            'const { parentPort } = require("node:worker_threads");',
-            "parentPort.on(" + JSON.stringify("message") + ", async function onMsg(msg) {",
-            "  if (msg && msg.t === " + JSON.stringify("run") + ") {",
-            "    const program = msg.program;",
-            "    const AsyncFunction = Object.getPrototypeOf(async function(){}).constructor;",
-            "    const callMap = new Map();",
-            "    let nextId = 0;",
-            '    const one = function(tool) { return function(args) { return new Promise(function(resolve, reject) {',
-            "      const id = nextId++;",
-            "      callMap.set(id, { resolve: resolve, reject: reject });",
-            '      parentPort.postMessage({ t: "call", id: id, tool: tool, args: args || {} });',
-            "    }); }; };",
-            "    var tm = { read: one(" + JSON.stringify("tm_read") + "), grep: one(" + JSON.stringify("tm_grep") + "), bash: one(" + JSON.stringify("tm_bash") + "), fetch: one(" + JSON.stringify("tm_fetch") + ") };",
-            '    parentPort.on("message", function(inner) {',
-            '      if (inner && inner.t === "result" && callMap.has(inner.id)) {',
-            "        callMap.get(inner.id).resolve(inner.r);",
-            "        callMap.delete(inner.id);",
-            '      } else if (inner && inner.t === "abort") {',
-            "        for (const e of callMap.values()) e.reject(new Error(" + JSON.stringify("ptc-stop:") + " + inner.reason));",
-            "        callMap.clear();",
-            "      }",
-            "    });",
-            "    try {",
-            // strict-mode body, same as the inline engines (they prefix the program
-            // with "use strict"; the worker builds the body string here)
-            "      var body = " + JSON.stringify('"use strict";\n') + " + program;",
-            "      var fn = new AsyncFunction(" + JSON.stringify("tm") + ", body);",
-            "      var result = await fn(tm);",
-            '      parentPort.postMessage({ t: "done", result: result });',
-            "    } catch (err) {",
-            '      parentPort.postMessage({ t: "error", message: err instanceof Error ? err.message : String(err), stack: err instanceof Error ? err.stack : undefined });',
-            "    }",
-            "  }",
-            "});",
-        ].join("\n");
-        return new Promise((resolve, reject) => {
-            let settled = false;
-            const w = new Worker(src, {
-                eval: true,
-                env: {},
-                resourceLimits: { maxOldGenerationSizeMb: 128, maxYoungGenerationSizeMb: 16 },
-            });
-            function settle(fn) {
-                if (settled)
-                    return;
-                settled = true;
-                fn();
-            }
-            w.on("message", (msg) => {
-                if (!msg || settled)
-                    return;
-                if (msg.t === "done") {
-                    settle(() => {
-                        w.terminate();
-                        resolve(msg.result);
-                    });
-                }
-                else if (msg.t === "error") {
-                    settle(() => {
-                        w.terminate();
-                        const err = new Error(typeof msg.message === "string" ? msg.message : "worker error");
-                        if (typeof msg.stack === "string")
-                            err.stack = msg.stack;
-                        reject(err);
-                    });
-                }
-                else if (msg.t === "call") {
-                    // Driver executes the bridge call through the gate and replies.
-                    const req = msg;
-                    bridge
-                        .call(req.tool, req.args)
-                        .then((r) => {
-                        if (!settled) {
-                            w.postMessage({ t: "result", id: req.id, r });
-                        }
-                    })
-                        .catch(() => {
-                        if (!settled) {
-                            w.postMessage({
-                                t: "result",
-                                id: req.id,
-                                r: { ok: false, error: { tool: req.tool, phase: "execute", message: "bridge call failed" } },
-                            });
-                        }
-                    });
-                }
-            });
-            w.on("error", (err) => {
-                settle(() => reject(err instanceof Error ? err : new Error(String(err))));
-            });
-            // Wire signal abort → terminate the worker.
-            const onAbort = () => {
-                settle(() => {
-                    w.terminate().then(() => reject(new PtcStopSignal("timeout")));
-                });
-            };
-            if (signal.aborted)
-                onAbort();
-            else
-                signal.addEventListener("abort", onAbort, { once: true });
-            // Send the run request.
-            w.postMessage({ t: "run", program });
-        });
-    }
-}
-// ---------- M2: inline-vm fallback engine (node:vm with timeout) ----------
-/**
- * Inline-vm engine — runs the program inside `node:vm` via
- * `runInNewContext` with a script-level execution timeout.  Measured on
- * Node 24/win32: `compileFunction`'s `timeout` does NOT interrupt a busy
- * loop when the compiled function is invoked (the call blocks the main
- * thread forever), while the async-IIFE + `runInNewContext` shape DOES —
- * a synchronous busy loop before the first `await` is killed ("Script
- * execution timed out").
- *
- * KNOWN RESIDUAL RISK (design §3, declared): a busy loop AFTER the first
- * `await` runs in a microtask continuation that blocks the host event
- * loop — no timer can fire, so NOTHING reclaims the main thread.  This is
- * inherent to any main-thread execution (InlineSequentialEngine shares
- * it); the primary worker engine does not share it (`terminate()` runs on
- * a separate thread) — prefer worker/auto in production.
- */
-export class InlineVmEngine {
-    name = "inline";
-    /** Script execution timeout in ms (kills pre-await synchronous
-     *  busy-loops).  Injectable so tests can pin the kill fast. */
-    compileTimeoutMs;
-    constructor(compileTimeoutMs = 30_000) {
-        this.compileTimeoutMs = compileTimeoutMs;
-    }
-    async run(program, bridge, signal) {
-        const tm = makeFacade(bridge);
-        let abortHandler;
-        const abortP = new Promise((_, rej) => {
-            abortHandler = () => rej(new PtcStopSignal("timeout"));
-            if (signal.aborted)
-                abortHandler();
-            else
-                signal.addEventListener("abort", abortHandler, { once: true });
-        });
-        try {
-            // The async-IIFE is the program wrapper: `return` stays legal in the
-            // body, the `tm` facade rides the context globals, and the script's
-            // completion value IS the program's promise.  The timeout kills
-            // pre-await synchronous busy-loops (see the class doc).
-            const promise = vm.runInNewContext(`(async () => {\n"use strict";\n${program}\n})()`, { tm }, { timeout: this.compileTimeoutMs });
-            return await Promise.race([promise, abortP]);
-        }
-        finally {
-            if (abortHandler)
-                signal.removeEventListener("abort", abortHandler);
-        }
-    }
-}
-/**
- * Wrap a raw bridge with the StepGate.  Every call: enforce time/call budget
- * (throw a stop that unwinds the program), assign a composite step id
- * `parent.kNN`, retry ≤1 on idempotent phases, record + persist errors, and
- * trip the error budget.  The gate lives ONLY here (outside the engine), per
- * design §3 ("决策进代码").
- */
-export function createGateBridge(raw, parent, budgets, state, opts) {
-    const { now, deadlineAt, store } = opts;
-    const ptcTag = opts.trajectoryParent ?? parent;
-    let seq = 0;
-    const traj = (e) => store?.appendTrajectory(e);
-    return {
-        async call(tool, args) {
-            if (state.stopReason)
-                throw new PtcStopSignal(state.stopReason);
-            // time budget checked BEFORE the call so a run cannot start a call it
-            // has no time left for.
-            if (now() >= deadlineAt) {
-                state.stopReason = "timeout";
-                throw new PtcStopSignal("timeout");
-            }
-            // call budget: only `maxCalls` bridged calls may be dispatched.
-            if (state.calls >= budgets.maxCalls) {
-                state.stopReason = "call-budget";
-                throw new PtcStopSignal("call-budget");
-            }
-            state.calls++;
-            seq++;
-            const composite = `${parent}.k${String(seq).padStart(2, "0")}`;
-            traj({ tool, step_id: composite, event: "call", ptc: ptcTag });
-            const t0 = now();
-            let res = await raw.call(tool, args);
-            let retried = false;
-            if (!res.ok && RETRYABLE_PHASES.includes(res.error.phase)) {
-                retried = true;
-                state.retries++;
-                res = await raw.call(tool, args);
-            }
-            const ms = now() - t0;
-            if (res.ok) {
-                const { tokens, dest, ref } = describeOk(res.data);
-                state.steps.push({ n: seq, tool, ok: true, ms, tokens, dest, ref });
-                traj({
-                    tool,
-                    step_id: composite,
-                    event: "result",
-                    offloaded: Boolean(ref),
-                    tokens,
-                    ptc: ptcTag,
-                    ...(ref ? { ref } : {}),
-                });
-                return res;
-            }
-            // error path — full text persists to steps/sXXXX.kNN/ (design §4.1)
-            state.errors++;
-            const err = res.error;
-            let errorRef;
-            if (store) {
-                try {
-                    store.writeResult(composite, {
-                        tool,
-                        content: JSON.stringify({ error: err }, null, 2),
-                        tokens: estimateTokens(JSON.stringify(err)),
-                        contentType: "json",
-                        preview: shorten(err.message, 120),
-                        expireAt: Date.now() + 24 * 60 * 60 * 1000,
-                    });
-                    errorRef = buildRef(store.runId, composite);
-                }
-                catch {
-                    /* error persistence is best-effort; never mask the original error */
-                }
-            }
-            state.steps.push({
-                n: seq,
-                tool,
-                ok: false,
-                ms,
-                tokens: 0,
-                dest: "err",
-                phase: err.phase,
-                line: err.line,
-                retry: retried,
-                message: err.message,
-                errorRef,
-            });
-            traj({
-                tool,
-                step_id: composite,
-                event: "error",
-                phase: err.phase,
-                ...(typeof err.line === "number" ? { line: err.line } : {}),
-                retry: retried,
-                ptc: ptcTag,
-                ...(errorRef ? { ref: errorRef } : {}),
-            });
-            if (state.errors >= budgets.maxErrors) {
-                state.stopReason = "error-budget";
-                throw new PtcStopSignal("error-budget");
-            }
-            return res;
-        },
-    };
-}
-/** Describe an ok bridge result for the success table (inline vs handle). */
-function describeOk(data) {
-    if (data && typeof data === "object" && data.offloaded === true) {
-        const o = data;
-        const ref = typeof o.ref === "string" ? o.ref : null;
-        return {
-            tokens: typeof o.tokens === "number" ? o.tokens : 0,
-            dest: ref ? `ref:${shortRefCode(ref)}` : "ref",
-            ref,
-        };
-    }
-    const text = typeof data === "string" ? data : JSON.stringify(data ?? "");
-    return { tokens: estimateTokens(text), dest: "inline", ref: null };
-}
-/** Short display code for a ref: the `steps/<id>` step segment. */
-function shortRefCode(ref) {
-    const m = /\/steps\/([^/]+)\/result/.exec(ref);
-    return m ? m[1] : shorten(ref, 24);
-}
-/**
- * Select the PTC engine based on the TM_PTC_ENGINE mode.
- *  - "worker": WorkerEngine only (throws on failure → engine-error status).
- *  - "inline": InlineVmEngine only (vm timeout for sync busy-loops).
- *  - "auto" (default): try WorkerEngine first; on failure → InlineVmEngine
- *    with `degraded=true` (marked `degraded-engine` in the summary).
- *
- * Probe result (P1, %TEMP%): ALL-GREEN on Node 24/win32 — auto chain =
- * worker-first, inline fallback.  Design §3 table.
- */
-export function selectEngine(mode, bridge) {
-    if (mode === "inline") {
-        return { engine: new InlineVmEngine(), degraded: false };
-    }
-    if (mode === "worker") {
-        return { engine: new WorkerEngine(), degraded: false };
-    }
-    // auto: worker first.  Construction never throws (no spawn until run()),
-    // so this branch cannot fail — the REAL auto-degrade happens in runPtc,
-    // which re-runs the whole program on InlineVmEngine when a worker run
-    // returns engine-error (bridged calls are read-only, so a re-run is safe;
-    // the fallback run starts with fresh call/error budgets under the SAME
-    // wall-clock deadline).
-    return { engine: new WorkerEngine(), degraded: false };
-}
-export async function runPtc(o) {
-    const now = o.now ?? Date.now;
-    const start = now();
-    const deadlineAt = start + o.budgets.timeoutMs;
-    // M2: engine selection — explicit override or auto/worker/inline from config.
-    let engine;
-    let degraded = false;
-    if (o.engine) {
-        engine = o.engine;
-    }
-    else {
-        const sel = selectEngine(o.cfg.ptcEngine, o.bridge);
-        engine = sel.engine;
-        degraded = sel.degraded;
-    }
-    // M2: static pre-scan — reject programs with banned tokens before any
-    // engine runs.  Shape: engine-error with the pscan tokens listed.
-    // (Design §3: "辅助手段，声明不作安全边界".)
-    const pscan = staticPscan(o.program);
-    if (pscan.rejected) {
-        return {
-            label: o.label,
-            status: "engine-error",
-            steps: [],
-            okCount: 0,
-            errCount: 0,
-            retries: 0,
-            calls: 0,
-            ms: 0,
-            engine: engine.name,
-            degraded,
-            returnValue: undefined,
-            returned: false,
-            engineError: {
-                tool: "tm_ptc_run",
-                phase: "args",
-                message: `程序包含禁止标识符（${pscan.tokens.join(", ")}），已拒绝执行。`,
-            },
-            parentStepId: o.parentStepId,
-        };
-    }
-    // Auto-degrade: if the selected engine throws (not a PtcStopSignal),
-    // and we're in auto mode with no explicit override, retry with InlineVmEngine.
-    const tryRun = async (eng) => {
-        const state = { calls: 0, errors: 0, retries: 0, steps: [] };
-        const gate = createGateBridge(o.bridge, o.parentStepId, o.budgets, state, {
-            now,
-            deadlineAt,
-            store: o.store,
-        });
-        // parent call event (design §6)
-        o.store?.appendTrajectory({
-            tool: "tm_ptc_run",
-            step_id: o.parentStepId,
-            event: "call",
-            label: o.label,
-            program_sha256: crypto.createHash("sha256").update(o.program).digest("hex"),
-            budgets: o.budgets,
-        });
-        const ac = new AbortController();
-        const remaining = Math.max(0, deadlineAt - now());
-        const timer = setTimeout(() => ac.abort(), remaining);
-        let status;
-        let returnValue;
-        let returned = false;
-        let engineError;
-        try {
-            returnValue = await eng.run(o.program, gate, ac.signal);
-            returned = true;
-            status = state.stopReason ? mapStop(state.stopReason) : "ok";
-        }
-        catch (err) {
-            if (err instanceof PtcStopSignal) {
-                status = mapStop(err.reason);
-            }
-            else {
-                status = "engine-error";
-                const line = extractLine(err);
-                engineError = {
-                    tool: "tm_ptc_run",
-                    phase: "execute",
-                    message: err instanceof Error ? err.message : String(err ?? "engine error"),
-                    ...(line != null ? { line } : {}),
-                };
-            }
-        }
-        finally {
-            clearTimeout(timer);
-        }
-        const ms = now() - start;
-        const outcome = {
-            label: o.label,
-            status,
-            steps: state.steps,
-            okCount: state.steps.filter((s) => s.ok).length,
-            errCount: state.steps.filter((s) => !s.ok).length,
-            retries: state.retries,
-            calls: state.calls,
-            ms,
-            engine: eng.name,
-            degraded,
-            returnValue,
-            returned,
-            ...(engineError ? { engineError } : {}),
-            parentStepId: o.parentStepId,
-        };
-        o.store?.appendTrajectory({
-            tool: "tm_ptc_run",
-            step_id: o.parentStepId,
-            event: "finish",
-            status: outcome.status,
-            calls: outcome.calls,
-            errors: outcome.errCount,
-            retries: outcome.retries,
-            ms: outcome.ms,
-        });
-        return outcome;
-    };
-    // Auto mode: try worker first; on engine-error → degrade to inline.
-    if (!o.engine && o.cfg.ptcEngine === "auto" && engine.name === "worker") {
-        const result = await tryRun(engine);
-        if (result.status === "engine-error") {
-            // Degrade to inline-vm and re-run.
-            const inlineEngine = new InlineVmEngine();
-            const fallback = await tryRun(inlineEngine);
-            fallback.degraded = true;
-            fallback.engine = "inline";
-            return fallback;
-        }
-        return result;
-    }
-    return tryRun(engine);
-}
-function mapStop(reason) {
-    if (reason === "timeout")
-        return "timeout";
-    if (reason === "error-budget")
-        return "stopped-error-budget";
-    return "stopped-call-budget";
-}
-// ---------- aggregation summary (design §2 — char-pinned headers) ----------
-export const PTC_SUMMARY_HEADER = "PTC 摘要";
-export const PTC_OK_SECTION = "-- 成功分部（≤8 行，超出整表卸载）";
-export const PTC_OK_HEADER = " #  tool      ms   tokens  落点(inline|ref 短码)";
-export const PTC_ERR_SECTION = "-- 错误分部（全量错误已落 run store）";
-export const PTC_ERR_HEADER = " #  tool      phase      line  retry  message(截断)";
-export const PTC_RETURN_PREFIX = "返回值: ";
-export const PTC_ERRORFULL_PREFIX = "错误全文: ";
-const OK_ROWS_INLINE_MAX = 8;
-const RETURN_VALUE_MAX = 2000;
-function engineLabel(o) {
-    if (o.engine === "worker")
-        return "worker";
-    return o.degraded ? "inline(degraded)" : "inline";
-}
-/** Render the fixed-shape aggregation summary.  `offload` is used to route an
- *  oversized success/error table (or return value) to a run-store handle. */
-export function renderPtcSummary(o, offload) {
-    const lines = [];
-    lines.push(`${PTC_SUMMARY_HEADER} · ${o.label} · status=${o.status}`);
-    lines.push(`steps=${o.okCount + o.errCount} ok=${o.okCount} err=${o.errCount} retries=${o.retries} ms=${o.ms}  engine=${engineLabel(o)}`);
-    const okSteps = o.steps.filter((s) => s.ok);
-    const errSteps = o.steps.filter((s) => !s.ok);
-    lines.push(PTC_OK_SECTION);
-    lines.push(PTC_OK_HEADER);
-    if (okSteps.length > OK_ROWS_INLINE_MAX && offload) {
-        const table = okSteps.map(okRow).join("\n");
-        lines.push(`（成功 ${okSteps.length} 行，超 ${OK_ROWS_INLINE_MAX}，整表卸载）`);
-        lines.push(offload(table, "ok"));
-    }
-    else {
-        for (const s of okSteps)
-            lines.push(okRow(s));
-    }
-    lines.push(PTC_ERR_SECTION);
-    lines.push(PTC_ERR_HEADER);
-    for (const s of errSteps)
-        lines.push(errRow(s));
-    if (o.engineError) {
-        lines.push(errRow({
-            n: 0,
-            tool: "tm_ptc_run",
-            phase: o.engineError.phase,
-            line: o.engineError.line,
-            retry: false,
-            message: `程序抛出：${o.engineError.message}`,
-        }));
-    }
-    if (errSteps.length === 0 && !o.engineError)
-        lines.push(" （无）");
-    // return value (JSON-serialized, capped; oversized → offload handle)
-    if (o.returned) {
-        const json = safeStringify(o.returnValue);
-        if (json.length > RETURN_VALUE_MAX && offload) {
-            lines.push(PTC_RETURN_PREFIX + "（超 2000 字符，卸载为句柄）");
-            lines.push(offload(json, "return"));
-        }
-        else {
-            lines.push(PTC_RETURN_PREFIX + json);
-        }
-    }
-    else {
-        lines.push(PTC_RETURN_PREFIX + "（无：程序未正常 return）");
-    }
-    // error full-text refs (aggregate handle when many)
-    const refs = o.steps.filter((s) => s.errorRef).map((s) => s.errorRef);
-    if (refs.length === 0) {
-        lines.push(PTC_ERRORFULL_PREFIX + "（无错误落盘）");
-    }
-    else if (refs.length > 8 && offload) {
-        lines.push(PTC_ERRORFULL_PREFIX + offload(refs.join("\n"), "errrefs"));
-    }
-    else {
-        lines.push(PTC_ERRORFULL_PREFIX + refs.map((r) => `tm://…/${shortRefCode(r)}`).join(" "));
-    }
-    return lines.join("\n");
-}
-function okRow(s) {
-    return ` ${s.n}  ${pad(s.tool, 8)}${String(s.ms)}ms  ${s.tokens}  ${s.dest}`;
-}
-function errRow(s) {
-    const phase = s.phase ?? "-";
-    const line = typeof s.line === "number" ? String(s.line) : "-";
-    const retry = s.retry ? "yes" : "no";
-    const msg = shorten(s.message ?? "", 60);
-    return ` ${s.n}  ${pad(s.tool, 8)}${pad(phase, 11)}${pad(line, 5)}${pad(retry, 5)}${msg}`;
-}
-function pad(v, w) {
-    const s = String(v);
-    return s.length >= w ? s + " " : s + " ".repeat(w - s.length);
-}
-function safeStringify(v) {
-    try {
-        const s = JSON.stringify(v);
-        return s === undefined ? "null" : s;
-    }
-    catch {
-        return String(v);
-    }
-}
-// ---------- bridge over the real governed pipelines ------------------------
-/**
- * Real M1 bridge: delegate each call to the corresponding exported pipeline,
- * `ctx` passed through untouched, and normalize the pipeline's `unknown`
- * result into `PtcCallResult` (TmErrorBody -> ok:false; anything else -> the
- * already-governed data).  Governance is entirely the pipelines'.
- */
-export function pipelineBridge(pipelines, ctx) {
-    const pick = (tool) => tool === "tm_read"
-        ? pipelines.tmRead
-        : tool === "tm_grep"
-            ? pipelines.tmGrep
-            : tool === "tm_bash"
-                ? pipelines.tmBash
-                : pipelines.tmFetch;
-    return {
-        async call(tool, args) {
-            if (!BRIDGE_ALLOW.includes(tool)) {
-                return { ok: false, error: tmError(tool, "args", "工具不在桥接白名单内").error };
-            }
-            const res = await pick(tool)(args ?? {}, ctx);
-            if (res && typeof res === "object" && "error" in res) {
-                return { ok: false, error: res.error };
-            }
-            return { ok: true, data: res };
-        },
-    };
-}
-// ---------- the tool definition (BUILT here, REGISTERED in M3) -------------
-const PTC_RUN_DESCRIPTION = `Program-mode batch orchestration over the four governed tm_* tools.  One program, N bridged calls, zero LLM round-trips during the run; only an aggregation summary returns to context.
-
-- program: an async function body.  Available: \`tm.read(args)\`, \`tm.grep(args)\`, \`tm.bash(args)\`, \`tm.fetch(args)\` — same args as the tm_* four.  Each returns \`{ok:true, data}\` (data is already governed: inline text, or an offload handle you can tm.fetch again) or \`{ok:false, error:{tool,phase,line?,message}}\`.  \`return\` a value; it is JSON-serialized into the summary (capped 2000 chars, oversized → handle).
-- budgets (optional, tighten-only; clamped to TM_PTC_* ceilings): max_calls, max_errors, timeout_ms.  Hitting any budget stops the whole run (produced output is NOT lost).  Errors are retried at most once and only on idempotent phases (client/execute/store).
-- Governance is NOT bypassed: every bridged call runs the full tm_* pipeline (P2 path scope, P3 allowlist, R6, threshold offload + handles, TTL).  Status is one of ok | stopped-error-budget | stopped-call-budget | timeout | engine-error.
-- Programs containing require/import/process/globalThis/Deno/Bun/fs/net/child_process are rejected before execution (static pre-scan, auxiliary guard).
-- Engine: TM_PTC_ENGINE=auto|worker|inline (auto tries worker first; on engine failure it re-runs the WHOLE program on inline with a degraded-engine mark — bridged calls are read-only, so a re-run is safe, and the fallback starts with fresh budgets under the same wall-clock deadline).  The inline engine kills pre-await synchronous busy-loops via the vm script timeout; a busy loop after the first await blocks the host event loop irrecoverably — prefer worker/auto.`;
-/** Build the tm_ptc_run ToolDefinition.  Registered in the tool segment
- *  when the agent's whitelist grants tm_ptc_run (M3).  `deps.args` is the
- *  ZodRawShape from tools.buildPtcArgsSchema() when zod is available — the
- *  descriptor fallback below keeps the tool usable without zod. */
-export function buildPtcRunTool(deps) {
-    const { cfg, store, nextStepId, ctx, accessToken } = deps;
-    const baseBridge = deps.bridge ?? (deps.pipelines ? pipelineBridge(deps.pipelines, ctx) : undefined);
-    const expireAt = () => Date.now() + cfg.blackboardTtlDays * 24 * 60 * 60 * 1000;
-    return {
-        description: PTC_RUN_DESCRIPTION,
-        args: deps.args ?? {
-            program: { descriptor: "program: string (required, async fn body, ≤TM_PTC_MAX_PROGRAM_CHARS)" },
-            label: { descriptor: "label: string (optional, ≤80 chars)" },
-            budgets: { descriptor: "budgets: { max_calls?, max_errors?, timeout_ms? } (optional, tighten-only)" },
-        },
-        execute: async (rawArgs) => {
-            const parsed = parsePtcArgs(rawArgs ?? {}, cfg);
-            if (!parsed.ok) {
-                return { output: `[${parsed.error.error.tool} 失败 · phase=${parsed.error.error.phase}]\n${parsed.error.error.message}` };
-            }
-            // M2: static pre-scan — reject programs with banned tokens before any engine runs.
-            const pscan = staticPscan(parsed.args.program);
-            if (pscan.rejected) {
-                return {
-                    output: `[tm_ptc_run 失败 · phase=args]\n程序包含禁止标识符（${pscan.tokens.join(", ")}），已拒绝执行。PTC 桥接仅暴露 tm.read/tm.grep/tm.bash/tm.fetch；require/import/process 等不在桥接白名单内。`,
-                };
-            }
-            if (!baseBridge) {
-                return {
-                    output: "[tm_ptc_run 失败 · phase=client]\n桥接管线未提供。",
-                };
-            }
-            // Generate a fresh parent step ID per call.
-            const parentStepId = nextStepId();
-            // Per-call offload helper: persist `text` under a PTC sub-step and
-            // render a handle block matching the four tools' visible shape.
-            const offloadBlock = (text, kind) => {
-                const tokens = estimateTokens(text);
-                try {
-                    const stored = store.writeResult(`${parentStepId}.${kind}`, {
-                        tool: "tm_ptc_run",
-                        content: text,
-                        tokens,
-                        contentType: detectContentType(text),
-                        preview: shorten(text, 120),
-                        expireAt: expireAt(),
-                    });
-                    return [
-                        `ref: ${stored.ref}`,
-                        `access_token: ${accessToken}`,
-                        `expire_at: ${stored.expireAt}`,
-                        `tokens: ${tokens}`,
-                        `（用 tm_fetch(ref, access_token) 取回；大载荷先试 mode:"structure"）`,
-                    ].join("\n");
-                }
-                catch {
-                    return text.slice(0, 2000);
-                }
-            };
-            const outcome = await runPtc({
-                program: parsed.args.program,
-                label: parsed.args.label,
-                budgets: parsed.args.budgets,
-                parentStepId,
-                cfg,
-                store,
-                bridge: baseBridge,
-                ...(deps.engine ? { engine: deps.engine } : {}),
-            });
-            const content = renderPtcSummary(outcome, offloadBlock);
-            // whole-summary offload if it still exceeds the threshold.
-            if (shouldOffload(estimateTokens(content), cfg.offloadThreshold)) {
-                return {
-                    output: `PTC 摘要过大（≈${estimateTokens(content)} tokens），已整体卸载为句柄，短摘要随后：\n` +
-                        offloadBlock(content, "rpt") +
-                        `\n--- 摘要前 1200 字符 ---\n${content.slice(0, 1200)}`,
-                };
-            }
-            return { output: content };
-        },
-    };
-}
-//# sourceMappingURL=ptc.js.map