@lqc123qwe/car-runtime 1.8.0 → 1.10.0

package/dist/loop/goal.d.ts

@@ -0,0 +1,31 @@
+/**
+ * F13 · Goal 层（五层停止第五层）：phase 持久化 + activation 进程内
+ *
+ * 口径（dsh goal/goal/src/types.ts:45,75,87-89 源码级已核实 + M2 系统设计增补 T-1）：
+ *  - GoalPhase = active | paused | blocked | complete —— 持久化：经会话日志 goalUpdate 事件
+ *  - GoalActivation = armed | disarmed —— 进程内、never persisted：
+ *    新实例默认 disarmed = 「session-start 重置 disarmed」零分支天然满足（AC-4.5）
+ *  - update_goal(complete) 不立刻掐断 turn：先写持久状态，turn 由既有收口逻辑完成（D5 §9）
+ *  - blocked 产出点：授权门 blockOnDeny / 策略门（stop.ts 集成）
+ */
+import type { SessionLog, SessionEvent } from '../session/log.ts';
+export type GoalPhase = 'active' | 'paused' | 'blocked' | 'complete';
+export type GoalActivation = 'armed' | 'disarmed';
+export declare class GoalDriver {
+    #private;
+    constructor(log: SessionLog);
+    get phase(): GoalPhase;
+    get activation(): GoalActivation;
+    /** 持久状态变更：写 goalUpdate 事件（重启后由恢复层读取重放） */
+    setPhase(phase: GoalPhase, reason: string): void;
+    /** 进程内激活（不持久化——重启后默认 disarmed） */
+    arm(): void;
+    disarm(reason: string): void;
+    /** 超限/撞限/错误自动 disarm（D5 §9：Round 超限、max-tokens、Agent error 都会 disarm） */
+    autoDisarmOnTurnEnd(reason: string): void;
+    /** 恢复层：从已落盘日志重放 goalUpdate 重建 phase（activation 不恢复——保持 disarmed） */
+    static replay(events: readonly SessionEvent[]): {
+        phase: GoalPhase;
+        activation: GoalActivation;
+    };
+}

package/dist/loop/goal.js

@@ -0,0 +1,34 @@
+export class GoalDriver {
+    #log;
+    #phase = 'active';
+    #activation = 'disarmed'; // 重启/新实例默认 disarmed（不会把历史任务叫醒）
+    #disarmReasons = [];
+    constructor(log) { this.#log = log; }
+    get phase() { return this.#phase; }
+    get activation() { return this.#activation; }
+    /** 持久状态变更：写 goalUpdate 事件（重启后由恢复层读取重放） */
+    setPhase(phase, reason) {
+        this.#phase = phase;
+        this.#log.append('runtime', 'goalUpdate', 'GOAL', { phase, reason });
+    }
+    /** 进程内激活（不持久化——重启后默认 disarmed） */
+    arm() { this.#activation = 'armed'; }
+    disarm(reason) {
+        this.#activation = 'disarmed';
+        this.#disarmReasons.push(reason);
+    }
+    /** 超限/撞限/错误自动 disarm（D5 §9：Round 超限、max-tokens、Agent error 都会 disarm） */
+    autoDisarmOnTurnEnd(reason) {
+        if (reason !== 'completed')
+            this.disarm(`turn ended with ${reason}`);
+    }
+    /** 恢复层：从已落盘日志重放 goalUpdate 重建 phase（activation 不恢复——保持 disarmed） */
+    static replay(events) {
+        let phase = 'active';
+        for (const e of events) {
+            if (e.kind === 'goalUpdate' && e.payload?.phase)
+                phase = e.payload.phase;
+        }
+        return { phase, activation: 'disarmed' }; // activation 永不持久化
+    }
+}

package/dist/loop/recover.d.ts

@@ -0,0 +1,17 @@
+/**
+ * F13 · 恢复层：interrupted 补记（进程消失后恢复层给未闭合 turn 补状态）
+ *
+ * 口径（D4 §18 / D5 §19）：
+ *  - interrupted = 进程消失后恢复层补记，与 aborted（运行期取消可清理）不可混用
+ *  - 未配对 toolCall 补合成错误 toolResult（日志无缺口红线）
+ *  - 副作用审计：补记事件带 recovered=true 标记（副作用是否落地由恢复层显式声明为未知）
+ */
+import type { SessionLog } from '../session/log.ts';
+export interface RecoveryReport {
+    /** 补记 interrupted 的 turn 数 */
+    turnsClosed: number;
+    /** 补记合成 toolResult 的未配对调用数 */
+    pairedCalls: number;
+}
+/** 扫描日志中未闭合的 turn（有 turnStart 语义的用户事件但没有 turnEnd）与未配对 toolCall */
+export declare function recoverInterrupted(log: SessionLog): RecoveryReport;

package/dist/loop/recover.js

@@ -0,0 +1,39 @@
+/** 扫描日志中未闭合的 turn（有 turnStart 语义的用户事件但没有 turnEnd）与未配对 toolCall */
+export function recoverInterrupted(log) {
+    const report = { turnsClosed: 0, pairedCalls: 0 };
+    const callIds = new Set();
+    const resultIds = new Set();
+    const openTurns = new Set();
+    const closedTurns = new Set();
+    for (const e of log.events) {
+        if (e.kind === 'toolCall')
+            callIds.add(e.payload.id);
+        if (e.kind === 'toolResult')
+            resultIds.add(e.payload.id);
+        if (e.kind === 'user')
+            openTurns.add(e.turnId);
+        if (e.kind === 'turnEnd') {
+            closedTurns.add(e.turnId);
+            openTurns.delete(e.turnId);
+        }
+    }
+    // 未配对 toolCall → 合成错误 toolResult（副作用状态未知：recovered=true 显式声明）
+    for (const e of log.events) {
+        if (e.kind !== 'toolCall')
+            continue;
+        const id = e.payload.id;
+        if (resultIds.has(id))
+            continue;
+        if (closedTurns.has(e.turnId))
+            continue; // 已闭合 turn 内成对由原逻辑保证
+        log.append('runtime', 'toolResult', e.turnId, { id, error: 'recovered: process interrupted before dispatch result', recovered: true });
+        resultIds.add(id);
+        report.pairedCalls++;
+    }
+    // 未闭合 turn → 补记 turnEnd=interrupted（不可与 aborted 混用）
+    for (const turnId of openTurns) {
+        log.append('runtime', 'turnEnd', turnId, null, { reason: 'interrupted', recovered: true });
+        report.turnsClosed++;
+    }
+    return report;
+}

package/dist/loop/stop.d.ts

@@ -0,0 +1,79 @@
+/**
+ * F5 · 最小 turn 级停止语义（ADR-001 实装）
+ *
+ * 口径（《系统设计》F5 / D4-D5 机制对照 / POC-3 I4）：
+ *  - step 三结果：completed / max-tokens / null（null = 工具结果交回模型，非异常）
+ *  - TurnEndReason 六值：completed / max-tokens / aborted / error / blocked / interrupted
+ *    （aborted=运行期取消可清理；interrupted=进程消失后恢复层补记——不可混用，S1/S2 仅实装前者）
+ *  - ADR-001：max-tokens 解析前收口（截断响应不解析工具调用，禁补全半截 JSON）；
+ *    只读白名单可选补错重试（preset.maxTokens.retryReadOnly）；endReasonTrail 保守判定：
+ *    turn 内任一 step 撞限 → turn/end 保留 max-tokens，不被后续成功 step 冲销
+ *  - 工具收口：concludesTurn=OR（任一 true 即收口）；terminate=AND（整批 finalized 全 true 才中断）
+ *  - 取消：未派发调用补记成对事件（toolCall + 合成错误 toolResult），日志无缺口
+ */
+import type { SessionLog } from '../session/log.ts';
+export type StepOutcome = 'completed' | 'max-tokens' | 'null';
+export type TurnEndReason = 'completed' | 'max-tokens' | 'aborted' | 'error' | 'blocked' | 'interrupted';
+export type SideEffect = 'readonly' | 'write';
+export interface ToolCall {
+    id: string;
+    tool: string;
+    args: Record<string, unknown>;
+}
+export interface ToolDef {
+    declaredSideEffect: SideEffect;
+    concludesTurn?: boolean;
+    terminate?: boolean;
+    run(args: Record<string, unknown>): Promise<unknown>;
+    description?: string;
+    parameters?: unknown;
+}
+/** 模型单步响应（provider 形态；stopReason 为不可变透传——ADR-001） */
+export interface ModelStep {
+    text?: string;
+    stopReason: 'stop' | 'length' | 'toolUse' | 'error';
+    /** 仅 stopReason=toolUse 时有意义；length 时 provider 可能给半截信息（CAR 不解析其 args） */
+    toolCalls?: ToolCall[];
+    /** length 时 provider 给出的「截断工具调用」：只有名字，args 不可信 */
+    truncatedTools?: Array<{
+        id: string;
+        tool: string;
+    }>;
+}
+export interface TurnPreset {
+    /** ADR-001：只读白名单补错重试开关（默认关） */
+    maxTokensRetryReadOnly?: boolean;
+    /** 权限模式（F4 集成点）：confirm 下写操作需审批回调放行 */
+    mode?: 'readonly' | 'confirm' | 'full';
+    /** 确认模式审批回调：返回 true 放行 */
+    authorize?: (call: ToolCall) => Promise<boolean>;
+    maxSteps?: number;
+    /** F13：OR/AND 收口可配置（默认 any/all = M1 行为等价） */
+    aggregate?: {
+        concludesTurn?: 'any' | 'all';
+        terminate?: 'any' | 'all';
+    };
+    /** F13：授权拒绝即收口 blocked（默认 false = 模型继续调整） */
+    blockOnDeny?: boolean;
+}
+export interface TurnResult {
+    reason: TurnEndReason;
+    steps: number;
+    endReasonTrail: Array<{
+        seq: number;
+        reason: TurnEndReason;
+    }>;
+}
+export declare class TurnAborted extends Error {
+    constructor();
+}
+export declare function runTurn(opts: {
+    log: SessionLog;
+    turnId: string;
+    model: () => Promise<ModelStep>;
+    tools: Map<string, ToolDef>;
+    preset?: TurnPreset;
+    signal?: {
+        aborted: boolean;
+    };
+}): Promise<TurnResult>;

package/dist/loop/stop.js

@@ -0,0 +1,151 @@
+import { CarM8Error } from '../runtime-core/errors.js';
+export class TurnAborted extends Error {
+    constructor() { super('CAR-ABORTED: turn cancelled by user'); }
+}
+export async function runTurn(opts) {
+    const { log, turnId, model, tools, preset = {}, signal } = opts;
+    const maxSteps = preset.maxSteps ?? 32;
+    const trail = [];
+    let sawMaxTokens = false;
+    let steps = 0;
+    const executeBatch = async (calls) => {
+        let concludesTurn = false;
+        let concludesVotes = 0;
+        let terminateVotes = 0;
+        let finalized = 0;
+        let denies = 0;
+        for (const call of calls) {
+            if (signal?.aborted) {
+                // 取消：未派发调用补记成对事件（日志无缺口）
+                log.append('runtime', 'toolCall', turnId, call);
+                log.append('runtime', 'toolResult', turnId, { id: call.id, error: 'aborted-before-dispatch' });
+                continue;
+            }
+            const def = tools.get(call.tool);
+            log.append('model', 'toolCall', turnId, call);
+            if (!def) {
+                log.append('plugin', 'toolResult', turnId, { id: call.id, error: `unknown tool "${call.tool}"` });
+                continue;
+            }
+            // 权限门（F4 集成点）：write 类在 readonly/confirm 模式需放行
+            if (def.declaredSideEffect === 'write' && preset.mode !== 'full') {
+                const granted = preset.mode === 'confirm' ? await (preset.authorize?.(call) ?? Promise.resolve(false)) : false;
+                log.append('runtime', 'toolResult', turnId, { id: call.id, error: 'authorization-denied', granted, mode: preset.mode });
+                if (!granted) {
+                    denies++;
+                    continue;
+                }
+            }
+            // 工具错误 = 成对 toolResult 交回模型（US-5/D5 语义：工具错误是结果而非 turn 中断——
+            // 与取消补记成对事件同纪律；turn 级 error 仅保留给模型请求/协议层失败）
+            let result;
+            let toolError;
+            try {
+                result = await def.run(call.args);
+            }
+            catch (e) {
+                result = undefined;
+                toolError = String(e);
+            }
+            log.append('plugin', 'toolResult', turnId, { id: call.id, result, ...(toolError ? { error: toolError } : {}) });
+            finalized++;
+            if (def.concludesTurn) {
+                concludesTurn = true;
+                concludesVotes++;
+            }
+            if (def.terminate)
+                terminateVotes++;
+        }
+        return {
+            concludesTurn, concludesAll: finalized > 0 && concludesVotes === finalized,
+            terminateVotes, terminateAll: finalized > 0 && terminateVotes === finalized,
+            finalized, denies,
+        };
+    };
+    try {
+        while (steps < maxSteps) {
+            if (signal?.aborted) {
+                const seq = log.append('runtime', 'turnEnd', turnId, null, { reason: 'aborted' }).seq;
+                trail.push({ seq, reason: 'aborted' });
+                return { reason: 'aborted', steps, endReasonTrail: trail };
+            }
+            steps++;
+            log.snapshotModelRequest(); // agent-loop 集成点：请求时快照（N1）
+            const step = await model();
+            if (step.stopReason === 'error') {
+                const seq = log.append('runtime', 'turnEnd', turnId, null, { reason: 'error' }).seq;
+                trail.push({ seq, reason: 'error' });
+                return { reason: 'error', steps, endReasonTrail: trail };
+            }
+            // ===== ADR-001：解析前收口 =====
+            if (step.stopReason === 'length') {
+                sawMaxTokens = true;
+                const readonlyRetry = preset.maxTokensRetryReadOnly === true;
+                const trunc = step.truncatedTools ?? [];
+                const retryable = readonlyRetry && trunc.every(t => tools.get(t.tool)?.declaredSideEffect === 'readonly');
+                if (retryable && trunc.length) {
+                    // Pi 式补错重试：只读白名单工具收到「参数可能被截断」错误结果，交回模型下轮
+                    for (const t of trunc) {
+                        log.append('runtime', 'toolCall', turnId, { id: t.id, tool: t.tool, args: {}, truncated: true });
+                        log.append('runtime', 'toolResult', turnId, { id: t.id, error: 'arguments may be truncated (max-tokens)' });
+                    }
+                    continue;
+                }
+                // 默认收口：截断响应不解析、不执行任何工具调用
+                const seq = log.append('runtime', 'turnEnd', turnId, null, { reason: 'max-tokens' }).seq;
+                trail.push({ seq, reason: 'max-tokens' });
+                return { reason: 'max-tokens', steps, endReasonTrail: trail };
+            }
+            if (step.stopReason === 'toolUse' && step.toolCalls?.length) {
+                const batch = await executeBatch(step.toolCalls);
+                // F13：授权拒绝即收口（blockOnDeny 产出点——blocked 仅新增产出点，枚举不增）
+                if (preset.blockOnDeny && batch.denies > 0) {
+                    const seq = log.append('runtime', 'turnEnd', turnId, null, { reason: 'blocked', denies: batch.denies }).seq;
+                    trail.push({ seq, reason: 'blocked' });
+                    return { reason: 'blocked', steps, endReasonTrail: trail };
+                }
+                const agg = preset.aggregate ?? {};
+                const abortedNow = (agg.terminate ?? 'all') === 'any' ? batch.terminateVotes > 0 : batch.terminateAll;
+                if (abortedNow) { // terminate 收口：默认 AND（整批），可配置 any
+                    const seq = log.append('runtime', 'turnEnd', turnId, null, { reason: 'aborted' }).seq;
+                    trail.push({ seq, reason: 'aborted' });
+                    return { reason: 'aborted', steps, endReasonTrail: trail };
+                }
+                const concludedNow = (agg.concludesTurn ?? 'any') === 'any' ? batch.concludesTurn : batch.concludesAll && batch.finalized > 0;
+                if (concludedNow) { // concludesTurn 收口：默认 OR，可配置 all
+                    const reason = sawMaxTokens ? 'max-tokens' : 'completed';
+                    const seq = log.append('runtime', 'turnEnd', turnId, null, { reason }).seq;
+                    trail.push({ seq, reason });
+                    return { reason, steps, endReasonTrail: trail };
+                }
+                // null：工具结果交回模型，继续下一 step（非异常）
+                continue;
+            }
+            // stopReason === 'stop'：模型自然完成
+            const reason = sawMaxTokens ? 'max-tokens' : 'completed';
+            const seq = log.append('runtime', 'turnEnd', turnId, null, { reason }).seq;
+            trail.push({ seq, reason });
+            return { reason, steps, endReasonTrail: trail };
+        }
+        const seq = log.append('runtime', 'turnEnd', turnId, null, { reason: 'error', detail: 'max-steps' }).seq;
+        trail.push({ seq, reason: 'error' });
+        return { reason: 'error', steps, endReasonTrail: trail };
+    }
+    catch (e) {
+        if (e instanceof TurnAborted) {
+            const seq = log.append('runtime', 'turnEnd', turnId, null, { reason: 'aborted' }).seq;
+            trail.push({ seq, reason: 'aborted' });
+            return { reason: 'aborted', steps, endReasonTrail: trail };
+        }
+        // 1.4-S4：CarM8Error 保形——code/userHint/retryable 进 turnEnd（A080001 引导文案「请运行
+        // car doctor」可达用户；非 CarM8Error 维持 String(e) 口径不变）
+        const m8 = e instanceof CarM8Error;
+        const detail = m8 ? `${e.slug}: ${e.message}` : String(e);
+        const seq = log.append('runtime', 'turnEnd', turnId, null, {
+            reason: 'error', detail,
+            ...(m8 ? { code: e.code, userHint: e.userHint, retryable: e.retryable } : {}),
+        }).seq;
+        trail.push({ seq, reason: 'error' });
+        return { reason: 'error', steps, endReasonTrail: trail };
+    }
+}

package/dist/mcp/gateway.d.ts

@@ -0,0 +1,96 @@
+/**
+ * F8 · MCP 桥接网关：登记制 + 工具桥接 + 崩溃隔离 + 凭据门
+ *
+ * 口径（《系统设计》M5 / 冻结决策① / 安全设计 T3 域）：
+ *  - serverId 登记制：运行期不接受未登记连接（A050001）；Python 侧仅工具供给方，无 ctx 级 API
+ *  - 工具桥接为一等 ToolDefinition：declaredSideEffect 未声明按 write 最高约束（T-22）
+ *  - 调用过三权限审批门（与其他工具同一审批门，无旁路——US-6 AC3）
+ *  - Server 崩溃/超时 → BD-02 整体标记不可用，不传导进内核主链路（US-6 AC4）
+ *  - McpServerConfig.env 禁明文密钥（疑似凭据模式即拒绝，sk- 前缀等——§3.2.5 传参禁忌）
+ *  - 传输抽象：stdio 真实通道（JSON-RPC over 换行分隔 JSON）/ in-process 测试通道
+ *
+ * 1.8（D-29 W3C traceparent client 侧注入）：callTool 加法 opts.traceparent → params._meta
+ * （MCP `_meta` 保留扩展点——未知键对端忽略，加法无害）；仅 otel 显式开且 client span 存活时
+ * 非空（trace.ts mcpToolSpan）——**缺省不注入，JSON-RPC 字节面不变**；tools/list 不注入
+ * （注册期无 span 上下文，登记）。解析/校验归 trace.ts（parseTraceparent fail-open），本层原样透传。
+ *
+ * 1.9（D-32 远程 MCP 头通道）：callTool 把 opts.traceparent 加法透传给 transport.send 第二参——
+ * 载体由传输层自选（HTTP 通道注入 `traceparent` 请求头〔W3C Trace Context 惯例〕；stdio 通道
+ * 忽略 opts，`params._meta` 载体不变）。`_meta` 注入口径一字节不动——otel 开时 HTTP 请求
+ * 双载体同值（头为主消费面，登记）；otel 关时双载体零注入（头面与字节面不变）。
+ */
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id: number;
+    method: string;
+    params?: unknown;
+}
+export interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: number;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    };
+}
+/**
+ * 客户端传输（CAR → MCP Server 方向）。M3-S11 双向分层：本接口为 client 侧对偶；
+ * server 侧（宿主 → CAR）见 src/host/hostGateway.ts 的 ServerTransport。
+ * 1.9-D32：send 加法可选第二参 opts（既有 `send(req)` 实现结构兼容零改动）。
+ */
+export interface ClientTransport {
+    send(req: JsonRpcRequest, opts?: {
+        traceparent?: string;
+    }): Promise<JsonRpcResponse>;
+    /** 进程/通道存活状态 */
+    alive(): boolean;
+    /** 主动终止 */
+    close(): void;
+}
+/** M1 兼容别名（M2 代码零改动；M4 评估移除） */
+export type McpTransport = ClientTransport;
+/**
+ * 服务端传输对偶（宿主 → CAR 方向，M3 多宿主）：宿主作为 MCP client 调用 CAR 暴露的 tool 面。
+ * 与 ClientTransport 语义对偶：CAR 不主动 send，仅响应 method 调用。
+ */
+export interface ServerTransport {
+    /** 宿主到达的 JSON-RPC 方法调用（由 HostGateway 分发到 10 tool 注册表） */
+    onRequest(method: string, params: unknown): Promise<JsonRpcResponse>;
+    alive(): boolean;
+    close(): void;
+}
+/** 疑似明文凭据检测（§3.2.5：env 值出现 sk- 等前缀即拒绝） */
+export declare function containsPlaintextCredential(env: Record<string, string>): string | null;
+export interface McpServerConfig {
+    serverId: string;
+    transport: ClientTransport;
+    /** 启动环境变量（禁明文凭据，凭据经 M8 凭据门运行时注入） */
+    env?: Record<string, string>;
+}
+export interface McpToolDefinition {
+    serverId: string;
+    name: string;
+    description?: string;
+    /** 未声明按 write 最高约束（T-22：安全默认） */
+    declaredSideEffect?: 'readonly' | 'write';
+    /** 工具入参 JSON Schema（MCP tools/list 原样捕获，M5 DEC-4 深度参数渲染消费源） */
+    inputSchema?: unknown;
+}
+export declare class McpGateway {
+    #private;
+    /** 登记并连接：拉起后发现工具并注册进能力矩阵（加载报告可见） */
+    register(cfg: McpServerConfig): Promise<McpToolDefinition[]>;
+    /** 能力矩阵视图（加载报告用） */
+    listTools(): McpToolDefinition[];
+    isAvailable(serverId: string): boolean;
+    /** 调用：走统一权限/审计链路（无旁路）；结果回填日志前必经 redact（调用方职责） */
+    callTool(serverId: string, tool: string, args: Record<string, unknown>, opts?: {
+        timeoutMs?: number; /** 1.8-D29：W3C traceparent（otel 显式开且 client span 存活时非空；缺省不注入 _meta） */
+        traceparent?: string;
+    }): Promise<{
+        ok: boolean;
+        result?: unknown;
+        error?: string;
+    }>;
+}

package/dist/mcp/gateway.js

@@ -0,0 +1,69 @@
+/** 疑似明文凭据检测（§3.2.5：env 值出现 sk- 等前缀即拒绝） */
+export function containsPlaintextCredential(env) {
+    const patterns = [/^sk-/, /^ghp_/, /^xox[bap]-/, /^AKIA/];
+    for (const [k, v] of Object.entries(env)) {
+        if (patterns.some(p => p.test(v)))
+            return `env "${k}" looks like a plaintext credential（经 M8 凭据门注入，禁止明文透传）`;
+    }
+    return null;
+}
+export class McpGateway {
+    #servers = new Map();
+    #tools = new Map();
+    #unavailable = new Set();
+    #nextId = 1;
+    /** 登记并连接：拉起后发现工具并注册进能力矩阵（加载报告可见） */
+    async register(cfg) {
+        if (this.#servers.has(cfg.serverId)) {
+            throw new Error(`CAR-E-MCP: serverId "${cfg.serverId}" already registered（登记制：重复注册显式报错）`);
+        }
+        const cred = cfg.env ? containsPlaintextCredential(cfg.env) : null;
+        if (cred)
+            throw new Error(`CAR-E-MCP: ${cred}`);
+        this.#servers.set(cfg.serverId, cfg);
+        const res = await cfg.transport.send({ jsonrpc: '2.0', id: this.#nextId++, method: 'tools/list' });
+        const tools = res.result.tools;
+        for (const t of tools) {
+            // T-22：未声明 sideEffect 按 write 最高约束收敛（安全默认，注册时强制）
+            this.#tools.set(`${cfg.serverId}:${t.name}`, {
+                serverId: cfg.serverId, name: t.name, description: t.description,
+                declaredSideEffect: t.sideEffect ?? 'write',
+                inputSchema: t.inputSchema,
+            });
+        }
+        return [...this.#tools.values()].filter(t => t.serverId === cfg.serverId);
+    }
+    /** 能力矩阵视图（加载报告用） */
+    listTools() { return [...this.#tools.values()]; }
+    isAvailable(serverId) { return this.#servers.has(serverId) && !this.#unavailable.has(serverId); }
+    /** 调用：走统一权限/审计链路（无旁路）；结果回填日志前必经 redact（调用方职责） */
+    async callTool(serverId, tool, args, opts = {}) {
+        const cfg = this.#servers.get(serverId);
+        if (!cfg)
+            throw new Error('CAR-A050001: unregistered MCP connection rejected（登记制）');
+        if (this.#unavailable.has(serverId)) {
+            // BD-02：崩溃/超时整体标记不可用——显式错误结果，不抛异常不阻断主链路
+            return { ok: false, error: `MCP server "${serverId}" unavailable (BD-02)` };
+        }
+        const key = `${serverId}:${tool}`;
+        if (!this.#tools.has(key))
+            return { ok: false, error: `unknown tool "${tool}" on "${serverId}"` };
+        try {
+            const res = await Promise.race([
+                // 1.9-D32：traceparent 加法透传第二参（载体归传输层——HTTP 头 / stdio 忽略）；
+                // `_meta` 注入 1.8-D29 口径不动（otel 开 = 双载体同值）
+                cfg.transport.send({
+                    jsonrpc: '2.0', id: this.#nextId++, method: 'tools/call',
+                    params: { name: tool, arguments: args, ...(opts.traceparent ? { _meta: { traceparent: opts.traceparent } } : {}) },
+                }, opts.traceparent ? { traceparent: opts.traceparent } : undefined),
+                new Promise((_, rej) => setTimeout(() => rej(new Error('mcp timeout')), opts.timeoutMs ?? 30_000)),
+            ]);
+            return { ok: true, result: res.result };
+        }
+        catch (e) {
+            // BD-02：崩溃/超时 → 整体不可用（不静默：错误事件由调用方落审计日志）
+            this.#unavailable.add(serverId);
+            return { ok: false, error: `MCP call failed, server marked unavailable (BD-02): ${String(e)}` };
+        }
+    }
+}

package/dist/mcp/httpClient.d.ts

@@ -0,0 +1,27 @@
+import type { ClientTransport } from './gateway.ts';
+export declare const MCP_PROTOCOL_VERSION = "2025-06-18";
+export interface HttpMcpServerSpec {
+    url: string;
+    /** 已展开的请求头（明文禁令与 ${ENV} 展开由 resolveMcpHeaders 承担——直接传入者自证合规） */
+    headers?: Record<string, string>;
+    /** 测试注入；缺省 30s（send 内建超时，与 stdio 同口径） */
+    timeoutMs?: number;
+}
+/** node:http(s) 响应的最小面（真实 res 兼容；测试可注入替身） */
+export interface RawHttpResponse {
+    status: number;
+    headers: Record<string, string | string[] | undefined>;
+    /** 流式响应体（node:http res 本身即 AsyncIterable<Uint8Array>；destroy 显式丢弃） */
+    body: AsyncIterable<Uint8Array> & {
+        destroy(): void;
+    };
+}
+/** node:http(s) POST 单发（1.4-BUG-2 口径：出站不走 undici；TLS 门由 createHttpMcpTransport 把守） */
+export declare function rawPost(url: string, headers: Record<string, string>, body: string, timeoutMs: number): Promise<RawHttpResponse>;
+/**
+ * ${ENV_VAR} 头引用展开（D-21）：值内任意位置的 `${NAME}` 均替换为 env.NAME（如
+ * `Bearer ${TOKEN}`）；env 缺席显式报错（fail-visible，禁静默空值）；字面值疑似明文凭据
+ * 直接拒绝（按原始值检查——展开值是凭据本身，引注入即目的）。
+ */
+export declare function resolveMcpHeaders(raw: Record<string, string>, env?: NodeJS.ProcessEnv): Record<string, string>;
+export declare function createHttpMcpTransport(spec: HttpMcpServerSpec): ClientTransport;