@lqc123qwe/car-runtime 1.9.0 → 1.11.0

package/dist/mcp/httpClient.js

@@ -0,0 +1,196 @@
+/**
+ * 1.5-S2 · MCP 远程传输客户端（D-21）：Streamable HTTP（2025-06-18 spec 单轨）
+ *
+ * 口径：
+ *  - CAR → 远程 MCP Server 方向（gateway.ts ClientTransport 的第二真实通道——与 stdio 并列）；
+ *  - 懒 initialize 握手：首次 send 前自动 initialize → notifications/initialized；
+ *    响应 `Mcp-Session-Id` 头存在则后续请求回传（无会话头的 server 容许）；
+ *  - 响应形态双兼容：application/json 单响应 / text/event-stream 逐事件取本请求 id
+ *    （SSE 命中即收口，流显式 destroy——悬挂 socket 是 1.4-BUG-2 同源教训）；
+ *  - **出站走 node:http(s) 不用 undici fetch**（1.4-BUG-2 已验证口径：win32 退出 libuv
+ *    断言 0xC0000409 与 undici socket 相关，telemetry 出站同此先例）；TLS 门复用
+ *    assertTlsOrLoopback（D-12a：http 仅豁免 loopback——本地假 server 与本地 MCP）；
+ *  - send 内建 30s 超时（与 stdio 同口径；gateway BD-02 外层 race 不变）；
+ *  - headers 凭据规则（CR-05 经配置通道执行）：值支持 `${ENV_VAR}` 引用（env 缺席显式报错）；
+ *    字面值疑似明文凭据（containsPlaintextCredential 同款模式）直接拒绝——env 引用注入
+ *    才是登记合规通道（展开后值不复查：引注入即目的，展开值是凭据本身）；
+ *  - legacy HTTP+SSE（2024-11-05）不做（1.5 规划 D-21 登记不追溯）；
+ *  - 1.9（D-32 远程 MCP 头通道）：send 加法可选第二参 opts.traceparent → tools/call 请求头
+ *    加法 `traceparent`（W3C Trace Context HTTP 载体惯例——第三方 OTel 接入面主消费通道）；
+ *    注入前 parseTraceparent 校验，畸形**不注入不抛**（协议面 fail-open——严格格式天然排除
+ *    CR/LF，兼防头注入越权面）；otel 关 = 双载体零注入（头与 JSON-RPC 字节面不变）；
+ *    initialize/notifications/tools/list 不注入（无 span 上下文——1.8 tools/list 口径延伸）；
+ *    配置 headers 含字面 `traceparent` 时注入优先（动态 span 上下文为请求级事实，登记）。
+ */
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { containsPlaintextCredential } from './gateway.js';
+import { assertTlsOrLoopback } from '../runtime-core/llm.js';
+import { parseTraceparent } from '../runtime-core/trace.js';
+export const MCP_PROTOCOL_VERSION = '2025-06-18';
+/** node:http(s) POST 单发（1.4-BUG-2 口径：出站不走 undici；TLS 门由 createHttpMcpTransport 把守） */
+export function rawPost(url, headers, body, timeoutMs) {
+    const u = new URL(url);
+    const send = u.protocol === 'https:' ? httpsRequest : httpRequest;
+    return new Promise((resolve, reject) => {
+        const req = send(u, { method: 'POST', headers }, res => {
+            resolve({
+                status: res.statusCode ?? 0,
+                headers: res.headers,
+                body: res,
+            });
+        });
+        req.setTimeout(timeoutMs, () => req.destroy(new Error(`CAR-E-MCP: http transport timeout (${timeoutMs}ms)`)));
+        req.on('error', reject);
+        req.end(body);
+    });
+}
+/**
+ * ${ENV_VAR} 头引用展开（D-21）：值内任意位置的 `${NAME}` 均替换为 env.NAME（如
+ * `Bearer ${TOKEN}`）；env 缺席显式报错（fail-visible，禁静默空值）；字面值疑似明文凭据
+ * 直接拒绝（按原始值检查——展开值是凭据本身，引注入即目的）。
+ */
+export function resolveMcpHeaders(raw, env = process.env) {
+    const out = {};
+    for (const [k, v] of Object.entries(raw)) {
+        const cred = containsPlaintextCredential({ [k]: v });
+        if (cred)
+            throw new Error(`CAR-E-MCP: headers.${k}——${cred}（配置明文禁令 CR-05；请改用 \`\${ENV_VAR}\` 引用注入）`);
+        out[k] = v.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_all, name) => {
+            const val = env[name];
+            if (val === undefined || val === '') {
+                throw new Error(`CAR-E-MCP: headers.${k} 引用的环境变量 ${name} 未设置（fail-visible，禁静默空值）`);
+            }
+            return val;
+        });
+    }
+    return out;
+}
+export function createHttpMcpTransport(spec) {
+    // D-12a TLS 门（与 LLM 适配器同款）：https 直接通过；http 仅豁免 loopback
+    assertTlsOrLoopback(spec.url.replace(/\/+$/, ''));
+    const timeoutMs = spec.timeoutMs ?? 30_000;
+    let sessionId = null;
+    let initialized = false;
+    let initPromise = null;
+    let closed = false;
+    const baseHeaders = () => ({
+        'content-type': 'application/json',
+        'accept': 'application/json, text/event-stream',
+        ...(sessionId ? { 'mcp-session-id': sessionId } : {}),
+        ...spec.headers,
+    });
+    /** 流全读（JSON 响应） */
+    async function readAll(res) {
+        const parts = [];
+        for await (const chunk of res.body)
+            parts.push(Buffer.from(chunk));
+        return Buffer.concat(parts);
+    }
+    /** SSE 响应逐事件取本请求 id（data JSON 自带 id；命中即收口，流显式 destroy） */
+    async function readSseForId(res, id) {
+        const decoder = new TextDecoder();
+        let buf = '';
+        try {
+            for await (const chunk of res.body) {
+                buf += decoder.decode(chunk, { stream: true });
+                let nl;
+                while ((nl = buf.indexOf('\n')) >= 0) {
+                    const line = buf.slice(0, nl).replace(/\r$/, '');
+                    buf = buf.slice(nl + 1);
+                    if (!line.startsWith('data:'))
+                        continue;
+                    const data = line.slice(5).trim();
+                    if (!data)
+                        continue;
+                    let evt;
+                    try {
+                        evt = JSON.parse(data);
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (evt?.id === id)
+                        return evt;
+                }
+            }
+        }
+        finally {
+            try {
+                res.body.destroy();
+            }
+            catch { /* 流已自然结束 */ }
+        }
+        throw new Error('CAR-E-MCP: SSE 流结束未见本请求响应（阶段：read-response）');
+    }
+    async function postAndRead(body, matchId, phase, extraHeaders = {}) {
+        // 1.9-D32：extraHeaders 展开在 baseHeaders 之后——配置头同名时注入优先（登记口径）
+        const res = await rawPost(spec.url, { ...baseHeaders(), ...extraHeaders }, JSON.stringify(body), timeoutMs);
+        const sid = res.headers['mcp-session-id'];
+        if (typeof sid === 'string')
+            sessionId = sid;
+        if (res.status < 200 || res.status >= 300) {
+            try {
+                res.body.destroy();
+            }
+            catch { /* 已结束 */ }
+            throw new Error(`CAR-E-MCP: HTTP ${res.status}（阶段：${phase}——server 拒绝或不可达）`);
+        }
+        const ct = String(res.headers['content-type'] ?? '');
+        if (ct.includes('text/event-stream'))
+            return readSseForId(res, matchId ?? Number.NaN);
+        const json = JSON.parse((await readAll(res)).toString('utf-8'));
+        return json;
+    }
+    /** 懒 initialize 握手（首次 send 前恰好一次）：initialize → 会话头捕获 → notifications/initialized */
+    async function doInitialize() {
+        const initRes = await postAndRead({
+            jsonrpc: '2.0', id: -1, method: 'initialize',
+            params: { protocolVersion: MCP_PROTOCOL_VERSION, capabilities: {}, clientInfo: { name: 'car-runtime', version: '0.0.0' } },
+        }, -1, 'initialize');
+        if (initRes.error) {
+            throw new Error(`CAR-E-MCP: initialize 被拒：${initRes.error.message}（阶段：initialize）`);
+        }
+        // notifications/initialized：无 id 通知——2xx/202 即视为送达（无响应体，显式丢弃）
+        const res = await rawPost(spec.url, baseHeaders(), JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }), timeoutMs);
+        try {
+            res.body.destroy();
+        }
+        catch { /* 已结束 */ }
+        if (res.status < 200 || res.status >= 300) {
+            throw new Error(`CAR-E-MCP: notifications/initialized HTTP ${res.status}（阶段：initialized）`);
+        }
+    }
+    /**
+     * 1.9-D32：tools/call 请求的 `traceparent` 头（W3C Trace Context HTTP 载体惯例）——
+     * parseTraceparent 校验 fail-open（畸形/空 = {} 不注入不抛；严格 hex 格式排除 CR/LF 头注入面）；
+     * 与 body params._meta.traceparent 双载体同值并存（1.8-D29 `_meta` 面维持，头为主消费面）。
+     */
+    function callHeaders(tp) {
+        if (!tp || !parseTraceparent(tp))
+            return {};
+        return { traceparent: tp };
+    }
+    const transport = {
+        send(req, opts) {
+            return (async () => {
+                if (closed)
+                    throw new Error('CAR-E-MCP: http transport closed（server 已收口）');
+                if (!initialized) {
+                    initPromise ??= doInitialize().then(() => { initialized = true; });
+                    try {
+                        await initPromise;
+                    }
+                    catch (e) {
+                        initPromise = null;
+                        throw e;
+                    }
+                }
+                return postAndRead(req, req.id, 'request', callHeaders(opts?.traceparent));
+            })();
+        },
+        alive: () => !closed,
+        close: () => { closed = true; },
+    };
+    return transport;
+}

package/dist/mcp/stdioClient.d.ts

@@ -0,0 +1,8 @@
+import type { ClientTransport } from './gateway.ts';
+export interface StdioServerSpec {
+    command: string;
+    args?: string[];
+}
+export declare function createStdioClientTransport(spec: StdioServerSpec): ClientTransport & {
+    readonly alive: () => boolean;
+};

package/dist/mcp/stdioClient.js

@@ -0,0 +1,73 @@
+/**
+ * 1.4-S7 · MCP stdio 客户端传输（W1 MCP 工具进 turn）：spawn 子进程 + JSON-RPC 换行分隔 JSON
+ *
+ * 口径（1.4 规划 W1 MCP 块 / D-18）：
+ *  - CAR → 外部 MCP Server 方向（gateway.ts ClientTransport 的真实通道实装——此前仅测试替身）；
+ *    server 侧对偶（宿主 → CAR）见 src/host/stdio.ts；
+ *  - 行协议：请求一行 JSON 写入 server stdin；响应按 id 匹配 pending 表（行解析容错跳过非 JSON 行）；
+ *  - send 内建 30s 超时（fail-visible——gateway.register 的 tools/list 无外层 race，防挂死）；
+ *  - stderr 不透传（server 诊断输出与协议通道隔离）；close = kill（car run 收口调用）。
+ */
+import { spawn } from 'node:child_process';
+export function createStdioClientTransport(spec) {
+    const child = spawn(spec.command, spec.args ?? [], { stdio: ['pipe', 'pipe', 'pipe'] });
+    const pending = new Map();
+    let buffer = '';
+    let exited = false;
+    child.on('exit', () => { exited = true; });
+    child.stdout.on('data', chunk => {
+        buffer += chunk.toString('utf-8');
+        let nl;
+        while ((nl = buffer.indexOf('\n')) >= 0) {
+            const line = buffer.slice(0, nl).trim();
+            buffer = buffer.slice(nl + 1);
+            if (!line)
+                continue;
+            try {
+                const res = JSON.parse(line);
+                const settle = pending.get(res.id);
+                if (settle) {
+                    pending.delete(res.id);
+                    settle(res);
+                }
+            }
+            catch { /* 非 JSON 行容错跳过（server 诊断污染 stdin 协议通道时不断链） */ }
+        }
+    });
+    child.stderr.on('data', () => { });
+    child.on('error', () => { exited = true; });
+    const transport = {
+        send(req) {
+            return new Promise((resolve, reject) => {
+                if (!transport.alive()) {
+                    reject(new Error('CAR-E-MCP: stdio transport not alive（server 进程已退出）'));
+                    return;
+                }
+                const timer = setTimeout(() => {
+                    pending.delete(req.id);
+                    reject(new Error('CAR-E-MCP: stdio send timeout (30s)'));
+                }, 30_000);
+                pending.set(req.id, res => {
+                    clearTimeout(timer);
+                    resolve(res);
+                });
+                try {
+                    child.stdin.write(JSON.stringify(req) + '\n');
+                }
+                catch (e) {
+                    clearTimeout(timer);
+                    pending.delete(req.id);
+                    reject(e);
+                }
+            });
+        },
+        alive: () => !exited && child.exitCode === null && !child.killed,
+        close: () => {
+            try {
+                child.kill();
+            }
+            catch { /* 已退出 */ }
+        },
+    };
+    return transport;
+}

package/dist/ptc/budget.d.ts

@@ -0,0 +1,21 @@
+/**
+ * T-2 · PTC 预算控制（M3-S14）
+ *
+ * 口径（M3系统设计增补 T-2 / D5 §12 一手口径）：
+ *  - 初始对齐 dsh：computeMs=60s / maxWallMs=600s / maxOutputBytes=64MB；
+ *  - **三层收敛只许下调**（fail-closed）：任何上调 = 显式报错——预算放宽属安全相关变更，
+ *    须经标定流程（四步标定法：P99×2 余量校验 + 逃逸验证 + 季度复标）而非配置直改；
+ *  - 预算定位 = **资源护栏而非安全边界**（containment 非安全边界，对外声明口径归安全设计）。
+ */
+export interface PtcBudget {
+    computeMs: number;
+    maxWallMs: number;
+    maxOutputBytes: number;
+}
+/** 初始基线（dsh 一手口径对齐值；标定后经 ADR 修订） */
+export declare const PTC_BUDGET_BASELINE: Readonly<PtcBudget>;
+/**
+ * 预算收敛校验：用户覆盖值只许 ≤ 基线（逐项）；上调 = CAR-E-BUDGET 显式报错。
+ * 返回收敛后的完整预算（未覆盖项取基线）。
+ */
+export declare function convergeBudget(override?: Partial<PtcBudget>): PtcBudget;

package/dist/ptc/budget.js

@@ -0,0 +1,36 @@
+/**
+ * T-2 · PTC 预算控制（M3-S14）
+ *
+ * 口径（M3系统设计增补 T-2 / D5 §12 一手口径）：
+ *  - 初始对齐 dsh：computeMs=60s / maxWallMs=600s / maxOutputBytes=64MB；
+ *  - **三层收敛只许下调**（fail-closed）：任何上调 = 显式报错——预算放宽属安全相关变更，
+ *    须经标定流程（四步标定法：P99×2 余量校验 + 逃逸验证 + 季度复标）而非配置直改；
+ *  - 预算定位 = **资源护栏而非安全边界**（containment 非安全边界，对外声明口径归安全设计）。
+ */
+/** 初始基线（dsh 一手口径对齐值；标定后经 ADR 修订） */
+export const PTC_BUDGET_BASELINE = Object.freeze({
+    computeMs: 60_000,
+    maxWallMs: 600_000,
+    maxOutputBytes: 64 * 1024 * 1024,
+});
+/**
+ * 预算收敛校验：用户覆盖值只许 ≤ 基线（逐项）；上调 = CAR-E-BUDGET 显式报错。
+ * 返回收敛后的完整预算（未覆盖项取基线）。
+ */
+export function convergeBudget(override) {
+    const out = { ...PTC_BUDGET_BASELINE };
+    if (!override)
+        return out;
+    for (const key of ['computeMs', 'maxWallMs', 'maxOutputBytes']) {
+        const v = override[key];
+        if (v === undefined)
+            continue;
+        if (!Number.isFinite(v) || v <= 0)
+            throw new Error(`CAR-E-BUDGET: ${key} must be a positive number, got ${v}`);
+        if (v > PTC_BUDGET_BASELINE[key]) {
+            throw new Error(`CAR-E-BUDGET: ${key}=${v} exceeds baseline ${PTC_BUDGET_BASELINE[key]}——预算只许下调（fail-closed），上调须经四步标定流程修订基线`);
+        }
+        out[key] = v;
+    }
+    return out;
+}

package/dist/ptc/erasable.d.ts

@@ -0,0 +1,14 @@
+/**
+ * T-2 · erasable-only TS 静态检查（M3-S14 双挂点：loader 提交链 + run_code 入口）
+ *
+ * 口径（M3系统设计增补 T-2 / dsh 源码一手口径 code-runtime-worker-thread/src/index.ts:306-308）：
+ *  - PTC 程序体与插件提交链只接受 erasable TS（Node type-stripping 可直接剥离的语法）——
+ *    禁止 enum / namespace / module / 构造器参数属性 / import=require 等需转换的语法；
+ *  - 双挂点保证「无 worker 即无执行，漏检面 = 0」：loader 在插件装载时检查源码，
+ *    run_code 在 worker 启动前检查程序体——两处调用同一函数（单一事实源）。
+ */
+/** erasable-only 检查：违规 = 显式报错（冲突链定位到语法名；v1 为启发式，行号随 AST 升级） */
+export declare function checkErasableOnly(code: string): {
+    ok: boolean;
+    violation?: string;
+};

package/dist/ptc/erasable.js

@@ -0,0 +1,27 @@
+/**
+ * T-2 · erasable-only TS 静态检查（M3-S14 双挂点：loader 提交链 + run_code 入口）
+ *
+ * 口径（M3系统设计增补 T-2 / dsh 源码一手口径 code-runtime-worker-thread/src/index.ts:306-308）：
+ *  - PTC 程序体与插件提交链只接受 erasable TS（Node type-stripping 可直接剥离的语法）——
+ *    禁止 enum / namespace / module / 构造器参数属性 / import=require 等需转换的语法；
+ *  - 双挂点保证「无 worker 即无执行，漏检面 = 0」：loader 在插件装载时检查源码，
+ *    run_code 在 worker 启动前检查程序体——两处调用同一函数（单一事实源）。
+ */
+/** erasable 语法黑名单（启发式正则；完整 AST 检查随 jiti 实装升级为语法级） */
+const NON_ERASABLE = [
+    { name: 'enum 声明', re: /(?:^|\n)\s*(?:export\s+)?(?:const\s+)?enum\s+[A-Za-z_$]/ },
+    { name: 'namespace 声明', re: /(?:^|\n)\s*(?:export\s+)?namespace\s+[A-Za-z_$]/ },
+    { name: 'module 声明', re: /(?:^|\n)\s*(?:export\s+)?module\s+[A-Za-z_$"'`]/ },
+    { name: '构造器参数属性', re: /constructor\s*\(\s*(?:public|private|protected|readonly)\s+[A-Za-z_$]/ },
+    { name: 'import=require', re: /import\s+[A-Za-z_$][\w$]*\s*=\s*require\s*\(/ },
+    { name: 'export=require', re: /export\s*=\s*/ },
+    { name: '装饰器（实验性，非 erasable）', re: /@\s*[A-Za-z_$][\w$]*\s*\(/ },
+];
+/** erasable-only 检查：违规 = 显式报错（冲突链定位到语法名；v1 为启发式，行号随 AST 升级） */
+export function checkErasableOnly(code) {
+    for (const { name, re } of NON_ERASABLE) {
+        if (re.test(code))
+            return { ok: false, violation: `non-erasable TS: ${name}（PTC 程序体与插件提交链仅接受 erasable TS，见 M3系统设计增补 T-2）` };
+    }
+    return { ok: true };
+}

package/dist/ptc/runCode.d.ts

@@ -0,0 +1,65 @@
+import { type PtcBudget } from './budget.ts';
+export interface PtcRequest {
+    code: string;
+    description: string;
+    toolCallId: string;
+    budget?: Partial<PtcBudget>;
+}
+export interface PtcResult {
+    ok: boolean;
+    result?: unknown;
+    error?: string;
+    wallMs: number;
+    outputBytes: number;
+    budgetExceeded?: boolean;
+    /** F12 出站覆盖命中数（secrets 脱敏在回填上下文前强制执行） */ secretsRedacted?: number;
+}
+export interface ToolBridge {
+    run(args: unknown): Promise<unknown>;
+}
+/** 1.8-D31：PTC 桥挂链面（结构兼容 trace.ts PtcRelayHandle——ptc 模块不依赖 runtime-core/trace） */
+export interface PtcSpanBridge {
+    complete(startMs: number, endMs: number, outcome: string, error?: unknown): void;
+}
+/** PTC 程序执行：每次新 worker；子调用经消息桥回主线程执行工具（宿主权限门生效面） */
+export interface RunCodeOpts {
+    tools: Map<string, ToolBridge>;
+    audit?: (d: Record<string, unknown>) => void;
+    /** 授权门（S15）：返回 false = 拒绝（无 worker 启动，审计留痕）；authorizationId 幂等由 authz 服务承载 */ authorize?: (req: PtcRequest) => Promise<boolean>;
+    /** 1.8-D31：桥挂链供给（每次 runCode 一次——每程序新 worker；null = 无遥测零 relay） */ spanBridge?: () => {
+        complete(startMs: number, endMs: number, outcome: string, error?: unknown): void;
+    } | null;
+}
+export declare function runCode(req: PtcRequest, opts: RunCodeOpts): Promise<PtcResult>;
+/** PTC 作为一等 ToolDefinition：强制 write 侧效应（授权门无旁路），接入 runTurn 工具面 */
+export declare function makePtcToolDefinition(opts: {
+    tools: Map<string, ToolBridge>;
+    audit?: (d: Record<string, unknown>) => void;
+    /** 1.8-D31：桥挂链供给透传（每次 runCode 一次；缺省 = 无遥测零 relay） */ spanBridge?: () => {
+        complete(startMs: number, endMs: number, outcome: string, error?: unknown): void;
+    } | null;
+}): {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            code: {
+                type: string;
+                description: string;
+            };
+            description: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+    declaredSideEffect: 'write';
+    run: (args: {
+        code: string;
+        description: string;
+        toolCallId?: string;
+    }) => Promise<unknown>;
+};

package/dist/ptc/runCode.js

@@ -0,0 +1,140 @@
+/**
+ * F16 · PTC（Programmatic Tool Calling）执行器（M3-S14）
+ *
+ * 口径（M3系统设计增补 T-2 / 决议③ PTC 落位 / dsh 一手口径）：
+ *  - run_code 签名：code + description **双必填**（description = 授权门「凭什么」人审凭据，无默认值）；
+ *  - 隔离：每次新 worker（独立无跨运行状态）；containment 非安全边界 → **强制 declaredSideEffect='write'**
+ *    走 stop.ts 既有权限门（S15 authorizationId='ptc-'+id 幂等集成）；
+ *  - erasable-only 双挂点之一（本入口）；挂点二在 loader 提交链（mountPlugin）；
+ *  - **预算到期不掐 turn**：超限 = 工具错误结果交回模型（TurnEndReason 六值零扩展，ADR-001 兼容）；
+ *  - 并发护栏（自研五维）：并发 4 / 子调用超时 30s / 总 worker 存活由本执行器串行门管控。
+ *
+ * 1.8（D-31 PTC worker 桥挂链）：opts.spanBridge 加法（otel 显式开且 turn span 存活时非空）——
+ * worker 侧程序计时（Date.now，worker_threads 同进程同时钟域）经 done 消息加法 span 字段回传，
+ * 主线程经 bridge.complete() 单点收口 car.ptc span（trace.ts ptcRelay——trace 挂链 turn /
+ * facade 时刻覆盖）；**单 exporter 纪律：worker 零独立出站通道、零 trace 载荷注入**（worker 无
+ * outbound 面——挂链由主线程句柄归因 + 计时 relay 完成）。主侧 killer / worker error 兜底路径
+ * 无 done 回传（terminate/崩溃抢先），以主线程时钟收口（口径登记：兜底非 worker 计时）。
+ */
+import { Worker } from 'node:worker_threads';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { convergeBudget } from './budget.js';
+import { checkErasableOnly } from './erasable.js';
+import { redactSecrets } from '../security/secrets.js';
+const WORKER_PATH = join(dirname(fileURLToPath(import.meta.url)), 'worker-entry.ts');
+const MAX_CONCURRENT = 4;
+let active = 0;
+export async function runCode(req, opts) {
+    // 双必填（description 为授权凭据——S15 授权门消费）
+    if (!req.code?.trim())
+        throw new Error('CAR-E-PTC: code is required（run_code 双必填）');
+    if (!req.description?.trim())
+        throw new Error('CAR-E-PTC: description is required——授权门人审凭据（无默认值，M3系统设计增补 T-2）');
+    // 授权门前置（无 worker 启动）：拒绝 = 工具错误结果 + 审计留痕（authorizationId='ptc-'+id 幂等键）
+    if (opts.authorize) {
+        const granted = await opts.authorize(req);
+        if (!granted) {
+            opts.audit?.({ kind: 'ptc-denied', toolCallId: req.toolCallId, authorizationId: 'ptc-' + req.toolCallId, description: req.description });
+            return { ok: false, error: 'authorization-denied (ptc)——授权拒绝落审计，程序未执行', wallMs: 0, outputBytes: 0 };
+        }
+    }
+    // erasable-only 挂点（入口）
+    const era = checkErasableOnly(req.code);
+    if (!era.ok)
+        throw new Error(`CAR-E-PTC: ${era.violation}`);
+    const budget = convergeBudget(req.budget);
+    if (active >= MAX_CONCURRENT) {
+        return { ok: false, error: 'CAR-E-PTC: concurrency guard (max=4)——超限拒绝留痕', wallMs: 0, outputBytes: 0 };
+    }
+    const started = Date.now();
+    active++;
+    // 1.8-D31：桥挂链供给（每次 runCode 一次）；null = 无遥测零 relay
+    const relay = opts.spanBridge?.() ?? null;
+    opts.audit?.({ kind: 'ptc-start', description: req.description, toolCallId: req.toolCallId, budget });
+    try {
+        return await new Promise((resolve) => {
+            const worker = new Worker(WORKER_PATH, {
+                workerData: { code: req.code, budget },
+                resourceLimits: { maxOldGenerationSizeMb: 256, maxYoungGenerationSizeMb: 32 },
+            });
+            // 主线程侧兜底（worker 内计时器失效时强杀——双层预算）
+            const killer = setTimeout(() => {
+                void worker.terminate();
+                // 1.8-D31：兜底收口（主线程时钟——terminate 抢先无 done relay，口径登记）
+                relay?.complete(started, Date.now(), 'error', new Error(`budget-exceeded (maxWallMs=${budget.maxWallMs}, main-side guard)`));
+                resolve({ ok: false, error: `budget-exceeded (maxWallMs=${budget.maxWallMs}, main-side guard)`, wallMs: Date.now() - started, outputBytes: 0, budgetExceeded: true });
+            }, budget.maxWallMs + 1000);
+            worker.on('message', (m) => {
+                if (m.type === 'tool') {
+                    const def = opts.tools.get(m.name);
+                    // 工具异常必须回传为 tool-result error（供程序体 try/catch 恢复）——
+                    // 无 catch 会成为 unhandled rejection 崩溃主进程（S19 评测 E1 捕获）
+                    void (def
+                        ? def.run(m.args).then(r => worker.postMessage({ type: 'tool-result', callId: m.callId, result: r }), (e) => worker.postMessage({ type: 'tool-result', callId: m.callId, error: String(e) }))
+                        : Promise.resolve(worker.postMessage({ type: 'tool-result', callId: m.callId, error: `unknown tool "${m.name}"` })));
+                    return;
+                }
+                if (m.type === 'done') {
+                    clearTimeout(killer);
+                    // 1.8-D31：worker 计时 relay 收口（error 路径同样收口——D-26 exception 形态成立）
+                    if (m.span && relay)
+                        relay.complete(m.span.startMs, m.span.endMs, m.error ? 'error' : 'ok', m.error);
+                    // F12 出站覆盖：worker 输出回填上下文前强制 redact（M3安全设计增补 T-4）
+                    let result = m.result;
+                    let secretsRedacted = 0;
+                    if (result !== undefined) {
+                        const serialized = JSON.stringify(result);
+                        const r = redactSecrets(serialized);
+                        secretsRedacted = r.redacted;
+                        if (r.redacted > 0) {
+                            result = JSON.parse(r.text);
+                            opts.audit?.({ kind: 'ptc-secrets-redacted', toolCallId: req.toolCallId, hits: r.redacted });
+                        }
+                    }
+                    resolve({
+                        ok: !m.error,
+                        result,
+                        error: m.error,
+                        wallMs: Date.now() - started,
+                        outputBytes: Buffer.byteLength(JSON.stringify(result ?? null)),
+                        budgetExceeded: !!m.error?.startsWith('budget-exceeded'),
+                        secretsRedacted,
+                    });
+                }
+            });
+            worker.on('error', (e) => { clearTimeout(killer); relay?.complete(started, Date.now(), 'error', e); resolve({ ok: false, error: String(e), wallMs: Date.now() - started, outputBytes: 0 }); });
+            worker.on('exit', (code) => { clearTimeout(killer); active--; });
+            // exit 可能先于 done（budget killer）——兜底 resolve 幂等由 Promise 语义保证
+        });
+    }
+    finally {
+        // active 递归在 exit 事件处理；此处为异常路径兜底
+        setTimeout(() => { active = Math.max(0, active - 0); }, 0);
+    }
+}
+/** PTC 作为一等 ToolDefinition：强制 write 侧效应（授权门无旁路），接入 runTurn 工具面 */
+export function makePtcToolDefinition(opts) {
+    return {
+        name: 'run_code',
+        description: '执行一段 erasable TypeScript 程序（PTC）——程序体内经 tools.<name>(args) 调用已注册工具',
+        // 1.4-S7：run_code 入参 schema（进模型声明面——此前无 parameters，模型看不到 code/description 形状）
+        parameters: {
+            type: 'object',
+            properties: {
+                code: { type: 'string', description: 'erasable TS 程序体（async 函数体；经 tools.<name>(args) 调用已注册工具）' },
+                description: { type: 'string', description: '本段程序的一句话描述（审计留痕）' },
+            },
+            required: ['code', 'description'],
+            additionalProperties: false,
+        },
+        // T-22 语义：PTC 与 bash 同信任级别 → 强制 write 最高约束（不可声明为 readonly）
+        declaredSideEffect: 'write',
+        run: async (args) => {
+            const r = await runCode({ code: args.code, description: args.description, toolCallId: args.toolCallId ?? 'ptc-' + Date.now().toString(36) }, opts);
+            if (!r.ok)
+                throw new Error(r.error);
+            return r.result;
+        },
+    };
+}

package/dist/ptc/schemaRender.d.ts

@@ -0,0 +1,15 @@
+/**
+ * T-2+ · JSON Schema → TS 深度参数渲染（M5 · DEC-4 预埋项转正，原 M3-S16 评估项）
+ *
+ * 口径（M3系统设计增补 T-2 预埋 / M4演进规划 RC-3 / M5 DEC-4 用户裁决①）：
+ *  - 渲染源仍为注册表快照同一条目（声明面 = 授权面红线不变）——inputSchema 只是
+ *    ToolBridge/McpToolDefinition 上的附加字段，不引入独立声明通道；
+ *  - 深度转换 **fail-visible**：超深 / 不支持节点（$ref、not）/ 畸形输入落 `unknown`
+ *    并以内联注释标记原因（禁止静默截断——N1「零静默」纪律在类型面上的延伸）；
+ *  - 输入 = MCP tools/list 的 inputSchema（JSON Schema 2020-12 常用子集）。
+ */
+/**
+ * JSON Schema 节点 → TS 类型表达式（深度递归）。
+ * 任何不可判定路径返回带内联原因标记的 unknown 字符串（形如 unknown + 注释）——可读、可测、不静默。
+ */
+export declare function jsonSchemaToTs(schema: unknown, depth?: number): string;