@te-river/opencode-team-mode 1.5.0 → 1.5.1

package/dist/tm/store.js

@@ -0,0 +1,222 @@
+/**
+ * JIT layer-2 tools — run-payload store + trajectory.
+ *
+ * Blackboard layout (under TM_BLACKBOARD_DIR, default `<project>/.blackboard/`):
+ *   runs/{run_id}/steps/{step_id}/{seq:03d}-{tool}.md   full offloaded result
+ *   runs/{run_id}/index.jsonl                            one append per result
+ *     entry = { ts, run_id, step_id, seq, tool, ref, file, tokens,
+ *               content_type, expire_at, preview }
+ *
+ * Trajectory layout (under TM_TRAJECTORY_DIR, default `<project>/.trajectory/`):
+ *   runs/{run_id}/steps.jsonl    append-only, one line per event — NO code
+ *                                path may rewrite, truncate or delete lines;
+ *                                the TTL sweep of whole expired run dirs is
+ *                                the sanctioned reclamation path.
+ *   runs/{run_id}/usage.jsonl    RESERVED for T2.2 (constant below, unused).
+ *
+ * Reclamation philosophy mirrors blackboard.ts: a startup sweep removes run
+ * dirs idle past the TTL — idleness measured across the whole run-dir tree
+ * (file appends must count as activity; only this sweep is destructive).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { buildRef } from "./refs.js";
+/** Reserved for T2.2 usage accounting — path constant only in this phase. */
+export const USAGE_JSONL_RELPATH = "usage.jsonl";
+/** Offloaded result files follow `{seq:03d}-{tool}.md` inside a step dir. */
+const STEP_FILE = /^\d{3}-[\w.-]+\.md$/;
+export class RunStore {
+    blackboardRoot;
+    trajectoryRoot;
+    _runId;
+    _ttlMs;
+    constructor(opts) {
+        this._runId = opts.runId;
+        this._ttlMs = opts.ttlDays * 24 * 60 * 60 * 1000;
+        this.blackboardRoot = path.isAbsolute(opts.blackboardDir)
+            ? opts.blackboardDir
+            : path.join(opts.projectRoot, opts.blackboardDir);
+        this.trajectoryRoot = path.isAbsolute(opts.trajectoryDir)
+            ? opts.trajectoryDir
+            : path.join(opts.projectRoot, opts.trajectoryDir);
+    }
+    get runId() {
+        return this._runId;
+    }
+    runDir() {
+        return path.join(this.blackboardRoot, "runs", this._runId);
+    }
+    stepsRoot() {
+        return path.join(this.runDir(), "steps");
+    }
+    trajectoryFile() {
+        return path.join(this.trajectoryRoot, "runs", this._runId, "steps.jsonl");
+    }
+    /**
+     * Write one offloaded result: step file (single write, never rewritten) +
+     * index.jsonl append.  Throws on store failures — the caller degrades
+     * (governance failures must not fail the task).
+     */
+    writeResult(stepId, meta) {
+        const stepDir = path.join(this.stepsRoot(), stepId);
+        fs.mkdirSync(stepDir, { recursive: true });
+        const seq = fs.readdirSync(stepDir).filter((f) => STEP_FILE.test(f)).length + 1;
+        const safeTool = meta.tool.replace(/[^\w-]/g, "_");
+        const name = `${String(seq).padStart(3, "0")}-${safeTool}.md`;
+        const file = path.join(stepDir, name);
+        fs.writeFileSync(file, meta.content, "utf8");
+        const ref = buildRef(this._runId, stepId);
+        const entry = {
+            ts: new Date().toISOString(),
+            run_id: this._runId,
+            step_id: stepId,
+            seq,
+            tool: meta.tool,
+            ref,
+            file: `${stepId}/${name}`,
+            tokens: meta.tokens,
+            content_type: meta.contentType,
+            expire_at: meta.expireAt,
+            preview: meta.preview,
+        };
+        fs.appendFileSync(path.join(this.runDir(), "index.jsonl"), JSON.stringify(entry) + "\n", "utf8");
+        return { stepId, seq, file, ref, expireAt: meta.expireAt };
+    }
+    /**
+     * Append one trajectory event.  Append-only by contract; best-effort
+     * (trajectory failures are swallowed — the blackboard failure path is the
+     * one that degrades upstream).
+     */
+    appendTrajectory(event) {
+        try {
+            const file = this.trajectoryFile();
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            const line = JSON.stringify({ ts: new Date().toISOString(), run_id: this._runId, ...event }) + "\n";
+            fs.appendFileSync(file, line, "utf8");
+        }
+        catch {
+            /* trajectory is best-effort */
+        }
+    }
+    /** Latest index entry for a ref (last append wins), or null. */
+    findIndexEntry(ref) {
+        try {
+            const text = fs.readFileSync(path.join(this.runDir(), "index.jsonl"), "utf8");
+            let found = null;
+            for (const line of text.split(/\r?\n/)) {
+                if (!line.trim())
+                    continue;
+                try {
+                    const entry = JSON.parse(line);
+                    if (entry && entry.ref === ref)
+                        found = entry;
+                }
+                catch {
+                    /* skip torn/bad line — append-only logs can have them on crash */
+                }
+            }
+            return found;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Read the offloaded payload file of a step; null when gone/unreadable.
+     *  With multiple seq files in one step (defensive re-entry), the LATEST
+     *  seq wins — consistent with findIndexEntry's last-append-wins. */
+    readStepFile(stepId) {
+        try {
+            const dir = path.join(this.stepsRoot(), stepId);
+            const files = fs.readdirSync(dir).filter((f) => STEP_FILE.test(f)).sort();
+            if (files.length === 0)
+                return null;
+            return { content: fs.readFileSync(path.join(dir, files[files.length - 1]), "utf8") };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Startup-only reclamation: remove run dirs (both stores) whose last tree
+     * activity is older than the TTL.  This is the ONLY destructive path in
+     * this module.  Returns the number of run dirs removed.  Never throws.
+     */
+    sweepExpired(now = Date.now()) {
+        let removed = 0;
+        for (const root of [this.blackboardRoot, this.trajectoryRoot]) {
+            const runsDir = path.join(root, "runs");
+            let entries;
+            try {
+                entries = fs.readdirSync(runsDir);
+            }
+            catch {
+                continue; // store not created yet — nothing to sweep
+            }
+            for (const entry of entries) {
+                const dir = path.join(runsDir, entry);
+                try {
+                    if (!fs.statSync(dir).isDirectory())
+                        continue;
+                    // Activity = max mtime across the run-dir TREE (M2, mirrors
+                    // blackboard.ts): appending to steps.jsonl / step files does NOT
+                    // refresh the parent dir's mtime, so a dir-mtime check deleted
+                    // live runs (review probe E1).  lastActivityMs returning 0 (stat
+                    // failure) keeps the dir — fail-closed.
+                    const last = lastActivityMs(dir);
+                    if (last !== 0 && now - last > this._ttlMs) {
+                        fs.rmSync(dir, { recursive: true, force: true });
+                        removed++;
+                    }
+                }
+                catch {
+                    /* raced entry — skip */
+                }
+            }
+        }
+        return removed;
+    }
+}
+/**
+ * Latest mtime within `dir`, recursing the whole tree (M2 — mirrors
+ * blackboard.ts's lastActivity, which is regression-pinned there).  A
+ * directory's own mtime only changes when direct children are created/
+ * removed/renamed — NOT when a file inside is appended or rewritten in
+ * place — so the sweep must look at file activity.
+ *
+ * The depth difference vs blackboard.ts's lastActivity (capped `levels`
+ * recursion) is DELIBERATE: blackboard trees can be user-managed and
+ * arbitrarily deep, so they cap defensively; the run-dir tree here is
+ * plugin-owned and bounded by what the plugin itself wrote.  Even a
+ * pathological cycle terminates naturally — fs.statSync on a symlink loop
+ * fails with ELOOP and is swallowed by the catch below.
+ */
+function lastActivityMs(dir) {
+    let latest;
+    try {
+        latest = fs.statSync(dir).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        return latest; // unreadable dir: its own mtime is all we know
+    }
+    for (const entry of entries) {
+        const child = path.join(dir, entry);
+        try {
+            const st = fs.statSync(child);
+            const seen = st.isDirectory() ? lastActivityMs(child) : st.mtimeMs;
+            if (seen > latest)
+                latest = seen;
+        }
+        catch {
+            /* raced deletion — ignore */
+        }
+    }
+    return latest;
+}
+//# sourceMappingURL=store.js.map

package/dist/tm/store.js.map

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

package/dist/tm/tools.d.ts

@@ -0,0 +1,68 @@
+/**
+ * JIT layer-2 tools — the four governed pipelines (T1.2 + T1.3 + T1.4).
+ *
+ *   tm_read  — governed passthrough of client.file.read  (T0.4-verified API)
+ *   tm_grep  — governed passthrough of client.find.text  (T0.4-verified API)
+ *   tm_bash  — read-only allowlisted shell via the host `$` bridge
+ *   tm_fetch — paged/structured retrieval of offloaded payloads (handles)
+ *
+ * Shared governance (every tool):
+ *   - ToolResult contract (official tool.d.ts:39-46): execute() returns
+ *     {output: string} — ALWAYS.  Handles, structured errors, pages and
+ *     degraded warnings are formatted INTO the output text; a bare object
+ *     return crashes the host result pipeline (`c.split`) and the model
+ *     would never see the handle it needs to drive tm_fetch.
+ *   - R6 reuse: env-file paths / env commands are refused through the SAME
+ *     envprotect matchers the global hook uses (anti-backdoor requirement);
+ *     the hook layer additionally aliases tm_* onto read/grep/bash so even a
+ *     future tool-code regression cannot bypass R6.
+ *   - Threshold offload: estimateTokens(content) >= TM_OFFLOAD_THRESHOLD
+ *     (default 2000; == threshold also offloads) -> full payload to the run
+ *     store + trajectory, handle {offloaded, ref, access_token, expire_at,
+ *     tokens, preview} back.  Below -> content inline.
+ *   - Structured errors (T1.4): pipelines still produce
+ *     {error: {tool, phase, message, line?}} internally — never a bare
+ *     throw — and execute() renders them readably into output; shell errors
+ *     carry a line when one can be extracted and stdout noise is stripped.
+ *   - Degradation: an offload (store) failure returns truncated content plus
+ *     a warning — a governance fault must never fail the task.
+ */
+import type * as crypto from "node:crypto";
+import { type EnvProtectMode } from "../envprotect.js";
+import type { ToolDefinition } from "../types.js";
+import { type TmConfig } from "./config.js";
+import type { RunStore } from "./store.js";
+export type TmPhase = "args" | "permission" | "client" | "execute" | "store" | "governance";
+export interface TmErrorBody {
+    error: {
+        tool: string;
+        phase: TmPhase;
+        message: string;
+        line?: number;
+    };
+}
+export declare function tmError(tool: string, phase: TmPhase, message: string, line?: number): TmErrorBody;
+/** Fixed invalid-handle message (spec-pinned wording for tm_fetch). */
+export declare const HANDLE_INVALID_MESSAGE = "\u8F7D\u8377\u5DF2\u6E05\u7406\u6216 run \u4E0D\u5339\u914D\uFF0C\u5EFA\u8BAE\u91CD\u8DD1\u539F\u5DE5\u5177\u3002";
+export interface TmDeps {
+    client: unknown;
+    $: unknown;
+    cfg: TmConfig;
+    store: RunStore;
+    runId: string;
+    /** Process-random HMAC key — used to VERIFY handle tokens in tm_fetch. */
+    hmacKey: crypto.BinaryLike;
+    accessToken: string;
+    expireAt: number;
+    mode: EnvProtectMode;
+    extra: RegExp[];
+}
+/**
+ * Build the four tool definitions.  Async only because of the optional zod
+ * load; every pipeline itself is runtime-defensive against raw args.  Every
+ * execute() funnels through toToolResult so the return value ALWAYS satisfies
+ * the host ToolResult contract ({output: string}) — handles, structured
+ * errors, pages and degraded warnings included.
+ */
+export declare function buildTmTools(deps: TmDeps): Promise<Record<string, ToolDefinition>>;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tm/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/tm/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,KAAK,MAAM,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAgE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACpH,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,aAAa,CAAA;AAC7D,OAAO,EAA0C,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAA;AAEnF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAW1C,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,YAAY,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,YAAY,CAAA;AAE3F,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CACxE;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,CAIjG;AAED,uEAAuE;AACvE,eAAO,MAAM,sBAAsB,sHAA4B,CAAA;AAgQ/D,MAAM,WAAW,MAAM;IACrB,MAAM,EAAE,OAAO,CAAA;IACf,CAAC,EAAE,OAAO,CAAA;IACV,GAAG,EAAE,QAAQ,CAAA;IACb,KAAK,EAAE,QAAQ,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC,UAAU,CAAA;IAC1B,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,cAAc,CAAA;IACpB,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB;AAqaD;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAyBxF"}