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

package/dist/tm/guard.js

@@ -0,0 +1,249 @@
+/**
+ * JIT layer-2 tools — permission guards (R1 pipeline).
+ *
+ * P2 (path level, tm_read / tm_grep scope): read scope = project root +
+ * blackboard dir + trajectory dir.  Everything else — including `..` escapes
+ * and absolute paths outside the scopes — is rejected.  Both the target and
+ * each scope are fs.realpathSync'd first (fail-closed): a junction/symlink
+ * pointing outside the scope defeats purely lexical resolve/relative checks.
+ *
+ * P3 (command level, tm_bash): a read-only allowlist gates what R6 does not
+ * already forbid.  The two layers are deliberately non-conflicting:
+ *   R6      governs what is FORBIDDEN (env dumps, env files — same source);
+ *   the P3 allowlist governs what is PERMITTED (read-only heads only).
+ * Hardening beyond the head token: output redirection, command substitution
+ * ($()/backticks/<>()), VAR=value assignment prefixes (BASH_ENV/LD_PRELOAD/
+ * PATH borrow an allowlisted head to run arbitrary scripts — fail closed),
+ * find -delete/-exec, tail -f and Get-Content/Get-ChildItem -Wait (hang),
+ * awk system() and rg --pre are rejected even under allowlisted heads.
+ * Quoted metacharacters (`|`, `;`, `>`, single-quoted `$()`) are literal
+ * text in both dialects — one shared quote-blanking view keeps segmentation
+ * and the redirect/substitution checks from misreading them (see the
+ * blankQuoted helpers; one implementation, never two drifting copies).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { shorten } from "./config.js";
+/**
+ * Split a command into shell segments so compound statements and pipelines
+ * are checked at every boundary (mirrors envprotect's segmentation).
+ */
+function segments(command) {
+    return command.split(/&&|\|\||[;\n|&]/);
+}
+/**
+ * Quoted-span blanking — ONE shared implementation for every quote-aware
+ * view (two prior review rounds both traced back to drifted copies).  A
+ * quoted span is literal text in bash AND PowerShell, so its metacharacters
+ * are neither segment boundaries nor operators.
+ *   blankQuoted       — blanks single- AND double-quoted spans: used for the
+ *                       redirect check and for segmentation (rg "err|warn"
+ *                       src, grep -E "a;b" f must not split on quoted `|;/`).
+ *   blankSingleQuoted — blanks single-quoted spans ONLY: used by the
+ *                       substitution check, because double quotes still
+ *                       expand $()/backticks in bash (and $( ) is a PS
+ *                       subexpression inside "..."), so blanking them would
+ *                       be a real allowance — single quotes are literal in
+ *                       both dialects (awk '{print $(NF)}' is a field ref).
+ */
+const QUOTED_SPAN = /"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'/g;
+const SINGLE_QUOTED_SPAN = /'(?:[^'\\]|\\.)*'/g;
+function blankQuoted(text) {
+    return text.replace(QUOTED_SPAN, " ");
+}
+function blankSingleQuoted(text) {
+    return text.replace(SINGLE_QUOTED_SPAN, " ");
+}
+/**
+ * Statement head of one segment: peel subshell/group openers, escaped
+ * commands and the `time` keyword until the real command word surfaces (same
+ * peeling idea as envprotect).  `assignment` reports that a leading
+ * `VAR=value` prefix was peeled on the way — the caller must FAIL CLOSED on
+ * it: a read-only aggregate never needs an assignment, and BASH_ENV/
+ * LD_PRELOAD/PATH prefixes are exactly how arbitrary scripts borrow an
+ * allowlisted head (non-interactive bash sources BASH_ENV before running
+ * `ls`).
+ */
+function headInfo(segment) {
+    let s = segment.trim();
+    for (;;) {
+        const next = s
+            .replace(/^[({\\]+/, "")
+            .replace(/[)}]+$/, "")
+            .replace(/^time\s+/i, "")
+            .trim();
+        if (next === s)
+            break;
+        s = next;
+    }
+    const sp = s.search(/\s/);
+    const token = sp === -1 ? s : s.slice(0, sp);
+    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(token)) {
+        const rest = sp === -1 ? "" : s.slice(sp).trim();
+        const inner = rest ? headInfo(rest) : { head: "", assignment: false };
+        return { head: inner.head, assignment: true };
+    }
+    return { head: token, assignment: false };
+}
+function allowVerdict(reason, suggestion) {
+    return { ok: false, reason, suggestion };
+}
+/**
+ * Classify a tm_bash command against the read-only allowlist.
+ * Every segment head (across && ; | & and newlines) must be allowlisted.
+ * Matching is case-insensitive (PowerShell is; sh spellings are unaffected).
+ */
+export function classifyReadonlyCommand(command, allowlist) {
+    const text = String(command ?? "").trim();
+    if (!text) {
+        return allowVerdict("空命令", "提供要执行的只读命令");
+    }
+    // Output redirection is a write path — reject (stream dups like `2>&1` and
+    // `2>>&1` are blanked first so legitimate stream merging still passes —
+    // blanking BEFORE segmentation also stops the `&` inside `2>&1` from
+    // splitting the command into bogus segments).
+    const noDup = text.replace(/\d+>&\d+/g, " ");
+    // Quoted `>`/`|`/`;` are literal text (grep "a>b", rg "err|warn" src) —
+    // blank quoted spans for the redirect check AND for segmentation; every
+    // real unquoted metacharacter still matches (no new allowance surface).
+    const noQuote = blankQuoted(noDup);
+    if (/(>>|>|&>|<>)/.test(noQuote)) {
+        return allowVerdict("只读模式禁止输出重定向（>/>>）", "去掉重定向只看输出；需要写文件请改用内置 bash（危险操作会弹官方确认框审批），无 bash 权限则向 HUMAN 申请");
+    }
+    // Command substitution executes arbitrary commands INSIDE an allowlisted
+    // head — the head token never sees it (review probes A1/A2/A3: `ls $(rm
+    // -rf x)`, backticks, `cat <(rm …)` all passed the allowlist).  A read-only
+    // aggregate never needs substitution: fail closed on all of it.  Only
+    // single-quoted spans are blanked here — single quotes are literal in both
+    // dialects (awk '{print $(NF)}' is a field reference, not a call), while
+    // double-quoted $( ) still expands (grep "$(x)" f stays rejected).
+    if (/\$\(|`|<\(|>\(/.test(blankSingleQuoted(noDup))) {
+        return allowVerdict("只读模式禁止命令替换（$() / 反引号 / <() / >()）", "命令替换会执行任意命令；改用管道组合只读命令，或改用内置 bash 执行（将弹官方确认框审批）");
+    }
+    const allow = (head) => allowlist.some((a) => a.toLowerCase() === head);
+    for (const seg of segments(noQuote)) {
+        const { head, assignment } = headInfo(seg);
+        // Fail closed on assignment prefixes: peeling used to expose the real
+        // head (BASH_ENV=./setup.sh ls -> ls) and let env injection borrow an
+        // allowlisted head.  No read-only aggregation needs VAR=value.
+        if (assignment) {
+            return allowVerdict("只读模式禁止环境变量赋值前缀（VAR=value cmd）", "BASH_ENV/LD_PRELOAD/PATH 等赋值前缀可借白名单头执行任意脚本；去掉赋值前缀，或改用内置 bash 执行（将弹官方确认框审批）");
+        }
+        if (!head)
+            continue;
+        const base = head.replace(/^.*[\\/]/, "").toLowerCase();
+        if (!allow(base)) {
+            return allowVerdict(`命令 "${shorten(base, 40)}" 不在 tm_bash 只读白名单内`, "改用白名单只读命令（ls/cat/head/tail/grep/rg/find/awk/sort/uniq/wc/cut/dir/Get-Content/Get-ChildItem/Select-String/Measure-Object）；需要执行删除/网络/安装/进程等危险命令请改用内置 bash（将弹官方确认框审批），无 bash 权限则向 HUMAN 申请批准");
+        }
+    }
+    // Write / execute / hang escapes that ride on allowlisted heads.
+    // deq view (review round-4 major): the shell dequotes argv, so `find .
+    // "-delete"` really arrives as `-delete` — but the raw-text checks below
+    // want whitespace before the flag (a `"`/`\` prefix slipped past) and the
+    // blanked view erases in-quote flags entirely.  One quote-char-stripped
+    // view closes all three; over-rejection is safe (`find . -name "-delete"`
+    // also dies — acceptable for a read-only aggregate).
+    const deq = text.replace(/["'\\]/g, "");
+    if (/\bfind\b/i.test(deq) && /\s-{1,2}(?:delete|exec(?:dir)?|ok(?:dir)?|fls|fprint\w*)\b/i.test(deq)) {
+        return allowVerdict("find 的写入/执行参数（-delete/-exec/…）不允许", "find 只用于查找；删除或执行请向 HUMAN 申请");
+    }
+    if (/\bawk\b/i.test(text) && /\bsystem\s*\(/.test(text)) {
+        return allowVerdict("awk 的 system() 调用不允许", "awk 仅做文本聚合；执行外部命令请向 HUMAN 申请");
+    }
+    // `--pre` only when NOT `--pre-glob` (lookahead requires [\s=] or EOL —
+    // a `\b` between "pre" and "-" also matched, wrongly banning --pre-glob).
+    if (/--pre(?=[\s=]|$)/i.test(deq)) {
+        return allowVerdict("rg --pre（外部预处理命令）不允许", "去掉 --pre；需要预处理请向 HUMAN 申请");
+    }
+    // Hang escapes: tail -f/--follow, and PowerShell -Wait on Get-Content /
+    // Get-ChildItem / its `dir` alias (streams/waits — never returns).
+    // Checked on BOTH views: the quote-blanked view keeps `dir "a|b" -Wait`
+    // rejected (deq segmentation would split the quoted pipe and strand the
+    // -Wait on a non-dir head); the deq view catches in-quote flags the
+    // blanked view erases (`tail "-f" x`, `dir "-Wait" x`).
+    for (const view of [noQuote, deq]) {
+        for (const seg of segments(view)) {
+            const tokens = seg.trim().split(/\s+/);
+            const head = tokens[0]?.replace(/^.*[\\/]/, "").toLowerCase();
+            if (head === "tail") {
+                for (const t of tokens.slice(1)) {
+                    if (t === "-f" || t.startsWith("--follow")) {
+                        return allowVerdict("tail -f/--follow 会挂起不返回", "改用 tail -n <N> 取末尾若干行");
+                    }
+                }
+            }
+            else if (head === "get-content" || head === "get-childitem" || head === "dir") {
+                // `-wai` still covers PowerShell's unambiguous -Wait prefixes
+                // (-wai/-wait) without also matching -WarningAction/-WarningVariable.
+                if (tokens.slice(1).some((t) => /^-wai/i.test(t))) {
+                    return allowVerdict("Get-Content/Get-ChildItem -Wait 会挂起不返回", "去掉 -Wait 取当前内容即可");
+                }
+            }
+        }
+    }
+    return { ok: true };
+}
+// ---------- P2 path scope ----------
+/** True when `target` resolves inside `rootDir` (win32 compares case-insensitively). */
+export function isInsideDir(rootDir, target) {
+    const rootAbs = path.resolve(rootDir);
+    const targetAbs = path.resolve(target);
+    const rel = path.relative(rootAbs, targetAbs);
+    if (rel === "")
+        return true;
+    if (!rel.startsWith("..") && !path.isAbsolute(rel))
+        return true;
+    if (process.platform === "win32") {
+        const relLc = path.relative(rootAbs.toLowerCase(), targetAbs.toLowerCase());
+        return relLc !== "" && !relLc.startsWith("..") && !path.isAbsolute(relLc);
+    }
+    return false;
+}
+/** realpathSync wrapper — null when the path does not exist / cannot resolve. */
+function realPathSafe(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve a requested path against the tool's directory and enforce the P2
+ * read scope (project root + extra dirs, i.e. blackboard + trajectory).
+ * Junction/symlink hardening (#6): BOTH the target and each scope dir are
+ * fs.realpathSync'd before the containment check — a purely lexical
+ * resolve/relative is defeated by a junction pointing outside the scope.
+ * Fail-closed: an unresolvable target is rejected; a scope dir that cannot
+ * be resolved (not created yet) simply cannot contain anything real and is
+ * skipped.  The error message never echoes env-file style paths beyond the
+ * scope verdict itself (R6 rejections upstream carry no path text at all).
+ */
+export function assertReadablePath(baseDir, requested, extraDirs = []) {
+    const raw = String(requested ?? "").trim();
+    if (!raw) {
+        return { ok: false, message: "缺少 path 参数" };
+    }
+    const abs = path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(baseDir, raw);
+    const absReal = realPathSafe(abs);
+    if (!absReal) {
+        return {
+            ok: false,
+            message: `路径不存在或无法解析（P2 fail-closed）: ${shorten(abs, 160)}`,
+        };
+    }
+    const scopes = [baseDir, ...extraDirs];
+    for (const scope of scopes) {
+        const scopeReal = realPathSafe(scope);
+        if (!scopeReal)
+            continue;
+        if (isInsideDir(scopeReal, absReal)) {
+            return { ok: true, abs };
+        }
+    }
+    return {
+        ok: false,
+        message: `路径越界（P2 只读范围 = 项目根 + 黑板 + Trajectory）: ${shorten(abs, 160)}`,
+    };
+}
+//# sourceMappingURL=guard.js.map

package/dist/tm/guard.js.map

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

package/dist/tm/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * JIT layer-2 tools — runtime assembly.
+ *
+ * `createTmTools(input)` is called ONCE per server() invocation and returns
+ * the runtime the plugin merges into its hooks:
+ *
+ *   const tm = await createTmTools(input)
+ *   return { config, "tool.execute.before", tool: tm.tools }
+ *
+ * It generates the run identity (run id + process-random HMAC key), resolves
+ * the env config, sweeps expired run payloads (startup-only TTL reclamation)
+ * and assembles the four statically-registered tools (T0.4-verified shape:
+ * `{ tool: { tm_read: { description, args, execute(args, ctx) } } }`).
+ */
+import type { PluginInput, ToolDefinition } from "../types.js";
+import { type EnvProtectMode } from "../envprotect.js";
+import { type TmConfig } from "./config.js";
+import { RunStore } from "./store.js";
+export interface TmRuntime {
+    runId: string;
+    config: TmConfig;
+    store: RunStore;
+    tools: Record<string, ToolDefinition>;
+}
+export interface CreateTmToolsOptions {
+    /** R6 mode — pass the plugin-level resolved value to keep ONE source. */
+    mode?: EnvProtectMode;
+    /** R6 extra deny rules — same single-source rule. */
+    extra?: RegExp[];
+}
+export declare function createTmTools(input: PluginInput, opts?: CreateTmToolsOptions): Promise<TmRuntime>;
+export { DEFAULT_BASH_READONLY_ALLOWED, estimateTokens, parseAllowlistEnv, resolveTmConfig, shouldOffload, shorten, TM_CONFIG_DEFAULTS, } from "./config.js";
+export { buildRef, hmacToken, isExpired, newRunId, parseRef, REF_PATTERN, verifyToken, } from "./refs.js";
+export { RunStore, USAGE_JSONL_RELPATH } from "./store.js";
+export { buildPreview, buildStructureSummary, capTokens, contentTypeForPath, detectContentType, sniffContentType, } from "./preview.js";
+export { assertReadablePath, classifyReadonlyCommand, isInsideDir, } from "./guard.js";
+export { buildTmTools, buildPipelines, HANDLE_INVALID_MESSAGE, tmError } from "./tools.js";
+export type { TmDeps, TmPhase, TmPipelines } from "./tools.js";
+export { BRIDGE_ALLOW, InlineSequentialEngine, InlineVmEngine, WorkerEngine, PTC_LABEL_MAX, PTC_STATUS_VALUES, RETRYABLE_PHASES, PTC_SUMMARY_HEADER, PTC_OK_SECTION, PTC_OK_HEADER, PTC_ERR_SECTION, PTC_ERR_HEADER, PTC_RETURN_PREFIX, PTC_ERRORFULL_PREFIX, buildPtcRunTool, createGateBridge, parsePtcArgs, pipelineBridge, renderPtcSummary, resolvePtcBudgets, runPtc, selectEngine, staticPscan, } from "./ptc.js";
+export type { PtcStatus, PtcEngine, PtcEngineName, PtcBridge, PtcCallResult, PtcErrorBody, PtcRunRequest, PtcRpcRequest, PtcRpcResponse, PtcRpcAbort, PtcEngineMessage, PtcBudgets, PtcStepRecord, PtcRunOutcome, RunPtcOptions, } from "./ptc.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tm/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAC9D,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAmB,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE5D,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAIrC,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,QAAQ,CAAA;IAChB,KAAK,EAAE,QAAQ,CAAA;IACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;CACtC;AAED,MAAM,WAAW,oBAAoB;IACnC,yEAAyE;IACzE,IAAI,CAAC,EAAE,cAAc,CAAA;IACrB,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CACjB;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,IAAI,GAAE,oBAAyB,GAC9B,OAAO,CAAC,SAAS,CAAC,CA4DpB;AAID,OAAO,EACL,6BAA6B,EAC7B,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,OAAO,EACP,kBAAkB,GACnB,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,QAAQ,EACR,SAAS,EACT,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,WAAW,GACZ,MAAM,WAAW,CAAA;AAClB,OAAO,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,WAAW,GACZ,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,sBAAsB,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAC1F,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAK9D,OAAO,EACL,YAAY,EACZ,sBAAsB,EACtB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,MAAM,EACN,YAAY,EACZ,WAAW,GACZ,MAAM,UAAU,CAAA;AACjB,YAAY,EACV,SAAS,EACT,SAAS,EACT,aAAa,EACb,SAAS,EACT,aAAa,EACb,YAAY,EACZ,aAAa,EACb,aAAa,EACb,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,UAAU,EACV,aAAa,EACb,aAAa,EACb,aAAa,GACd,MAAM,UAAU,CAAA"}

package/dist/tm/index.js

@@ -0,0 +1,93 @@
+/**
+ * JIT layer-2 tools — runtime assembly.
+ *
+ * `createTmTools(input)` is called ONCE per server() invocation and returns
+ * the runtime the plugin merges into its hooks:
+ *
+ *   const tm = await createTmTools(input)
+ *   return { config, "tool.execute.before", tool: tm.tools }
+ *
+ * It generates the run identity (run id + process-random HMAC key), resolves
+ * the env config, sweeps expired run payloads (startup-only TTL reclamation)
+ * and assembles the four statically-registered tools (T0.4-verified shape:
+ * `{ tool: { tm_read: { description, args, execute(args, ctx) } } }`).
+ */
+import * as crypto from "node:crypto";
+import { parseExtraDeny, resolveEnvProtectMode, } from "../envprotect.js";
+import { resolveTmConfig } from "./config.js";
+import { hmacToken, newRunId } from "./refs.js";
+import { RunStore } from "./store.js";
+import { buildTmTools, buildPipelines } from "./tools.js";
+import { buildPtcRunTool } from "./ptc.js";
+export async function createTmTools(input, opts = {}) {
+    const cfg = resolveTmConfig(process.env);
+    const directory = typeof input?.directory === "string" && input.directory.length > 0
+        ? input.directory
+        : process.cwd();
+    const runId = newRunId();
+    const hmacKey = crypto.randomBytes(32);
+    const accessToken = hmacToken(hmacKey, runId);
+    const store = new RunStore({
+        projectRoot: directory,
+        blackboardDir: cfg.blackboardDir,
+        trajectoryDir: cfg.trajectoryDir,
+        runId,
+        ttlDays: cfg.blackboardTtlDays,
+    });
+    // Startup-only TTL reclamation for expired run payloads — the sole cleanup
+    // path for the tm store (mirrors blackboard.ts's sweeper philosophy).
+    store.sweepExpired();
+    const mode = opts.mode ?? resolveEnvProtectMode(process.env.TM_ENV_PROTECT);
+    const extra = opts.extra ?? parseExtraDeny(process.env.TM_ENV_PROTECT_EXTRA_DENY);
+    const expireAt = Date.now() + cfg.blackboardTtlDays * 24 * 60 * 60 * 1000;
+    const tools = await buildTmTools({
+        client: input?.client,
+        $: input?.$,
+        cfg,
+        store,
+        runId,
+        hmacKey,
+        accessToken,
+        expireAt,
+        mode,
+        extra,
+    });
+    // M3: build tm_ptc_run using a separate pipeline instance (governance
+    // reused verbatim; step counter is independent — store handles any
+    // step-id overlap via tool-name-prefixed files).
+    const ptcDeps = {
+        client: input?.client,
+        $: input?.$,
+        cfg,
+        store,
+        runId,
+        hmacKey,
+        accessToken,
+        expireAt,
+        mode,
+        extra,
+    };
+    const ptcPipelines = buildPipelines(ptcDeps);
+    const ptcTool = buildPtcRunTool({
+        cfg,
+        store,
+        nextStepId: ptcPipelines.nextStepId,
+        ctx: { directory },
+        accessToken,
+        pipelines: ptcPipelines,
+    });
+    tools.tm_ptc_run = ptcTool;
+    return { runId, config: cfg, store, tools };
+}
+// ---------- re-exports (stable import surface for tests + plugin entry) ----------
+export { DEFAULT_BASH_READONLY_ALLOWED, estimateTokens, parseAllowlistEnv, resolveTmConfig, shouldOffload, shorten, TM_CONFIG_DEFAULTS, } from "./config.js";
+export { buildRef, hmacToken, isExpired, newRunId, parseRef, REF_PATTERN, verifyToken, } from "./refs.js";
+export { RunStore, USAGE_JSONL_RELPATH } from "./store.js";
+export { buildPreview, buildStructureSummary, capTokens, contentTypeForPath, detectContentType, sniffContentType, } from "./preview.js";
+export { assertReadablePath, classifyReadonlyCommand, isInsideDir, } from "./guard.js";
+export { buildTmTools, buildPipelines, HANDLE_INVALID_MESSAGE, tmError } from "./tools.js";
+// ---------- tm_ptc_run (M1 contract skeleton) ----------
+// NOTE: `buildPtcRunTool` is exported for tests + future M3 wiring, but index
+// does NOT add tm_ptc_run to the registered `tools` map yet (design §10/M3).
+export { BRIDGE_ALLOW, InlineSequentialEngine, InlineVmEngine, WorkerEngine, PTC_LABEL_MAX, PTC_STATUS_VALUES, RETRYABLE_PHASES, PTC_SUMMARY_HEADER, PTC_OK_SECTION, PTC_OK_HEADER, PTC_ERR_SECTION, PTC_ERR_HEADER, PTC_RETURN_PREFIX, PTC_ERRORFULL_PREFIX, buildPtcRunTool, createGateBridge, parsePtcArgs, pipelineBridge, renderPtcSummary, resolvePtcBudgets, runPtc, selectEngine, staticPscan, } from "./ptc.js";
+//# sourceMappingURL=index.js.map

package/dist/tm/index.js.map

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

package/dist/tm/preview.d.ts

@@ -0,0 +1,46 @@
+/**
+ * JIT layer-2 tools — content-aware previews (the soul of the offload handle)
+ * plus the L1 "structure" summaries for tm_fetch mode:"structure".
+ *
+ * Five branches, chosen by content_type (path hint) with sniffing fallback:
+ *   json   -> first 3 keys: path + type + magnitude
+ *   csv    -> header + 2 sample rows + total rows x cols
+ *   log    -> first 3 lines + pattern stats (ERROR x N, ...) + path:line refs
+ *   code   -> function/class signature list (with line numbers)
+ *   binary -> type + size + "不可预览"
+ *
+ * RED LINE: previews are hard-capped at TM_PREVIEW_MAX_TOKENS (default 80
+ * estimated tokens).  A bloated preview is an R4 regression — the cap is
+ * enforced by composition (body budget = cap - meta) so clue + hint lines
+ * always survive truncation.
+ */
+export type ContentType = "json" | "csv" | "log" | "text" | "code" | "binary";
+/** Content type derived from the file extension (deterministic hint). */
+export declare function contentTypeForPath(p: string): ContentType;
+/**
+ * Sniff content type when no path hint exists (or the hint was plain "text").
+ * Order: binary -> json -> csv -> code -> text.  Logs and plain text share
+ * the same preview branch, so no separate sniff rule is needed for them.
+ */
+export declare function sniffContentType(content: string): ContentType;
+/**
+ * Resolve the effective branch: a path-derived hint wins (deterministic);
+ * plain-text hints and missing hints fall through to sniffing (which may
+ * still upgrade the content to json / csv / code / binary).
+ */
+export declare function detectContentType(content: string, hint?: ContentType): ContentType;
+/** Hard cap by estimated tokens (chars/4): never exceed maxTokens. */
+export declare function capTokens(text: string, maxTokens: number): string;
+export interface PreviewOptions {
+    /** Raw-line scan budget for the branch builders (TM_PREVIEW_LINES). */
+    lines?: number;
+    /** Hard cap in estimated tokens (TM_PREVIEW_MAX_TOKENS). */
+    maxTokens?: number;
+    /** Retrieval clue embedded into the preview (path / pattern / cmd). */
+    clue?: string;
+}
+/** Build the governed preview for offloaded content. Never throws. */
+export declare function buildPreview(content: string, contentType: ContentType, opts?: PreviewOptions): string;
+/** ~100-token-level L1 map of an offloaded payload (TOC / key tree / error lines). */
+export declare function buildStructureSummary(content: string, contentType: string): string;
+//# sourceMappingURL=preview.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../src/tm/preview.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAA;AAiB7E,yEAAyE;AACzE,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,GAAG,WAAW,CAQzD;AAsBD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,CAc7D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,WAAW,CAGlF;AAED,sEAAsE;AACtE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CASjE;AAiJD,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,IAAI,GAAE,cAAmB,GAAG,MAAM,CAwBzG;AA+CD,sFAAsF;AACtF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAqBlF"}