@lqc123qwe/car-runtime 1.9.0 → 1.10.0

package/dist/dx/doctor.d.ts

@@ -0,0 +1,62 @@
+export interface CredentialCheck {
+    name: string;
+    envVar: string;
+    present: boolean;
+    hint: string;
+}
+/** 凭据存在性检查：只报 present/not-set，永不输出值 */
+export declare function doctorCredentials(env?: NodeJS.ProcessEnv): CredentialCheck[];
+export interface ConnectivityResult {
+    status: 'PASS' | 'SKIPPED';
+    detail: string;
+    latencyMs: number;
+}
+/** M8 增强：keychain 通道状态（模型凭据读取面，§3.2.M8.2 凭据行）——能力探测口径，缺席显式降级不静默；离线可过 */
+export declare function doctorKeychain(opts?: {
+    platform?: NodeJS.Platform;
+}): {
+    available: boolean;
+    note: string;
+};
+export interface SignatureCheck {
+    /** 生效模式（flag > env > 配置 > 缺省 warn——DEC-1 ②；enforce 缺省翻转 2026-12-25 登记计划内变更） */
+    mode: 'warn' | 'enforce';
+    /** 信任根通道：absent=未配置（全部插件按 unsigned 处理）；valid=在场且可解析；invalid=在场但解析失败（enforce 下拒签风险） */
+    trustRoot: 'absent' | 'valid' | 'invalid';
+    /** 配置文件通道（1.1-S3）：absent=cwd 未发现；found=已发现且校验通过；invalid=发现但解析/校验失败（fail-visible） */
+    configFile: 'absent' | 'found' | 'invalid';
+    detail: string;
+}
+/** 1.1-S2 签名就绪检查：mode 生效值 + 信任根在场可解析性 + car.config.json 发现态（离线可过；值不打印） */
+export declare function doctorSignature(opts?: {
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    configPath?: string;
+}): SignatureCheck;
+export interface ModelReadinessCheck {
+    /** baseUrl + model 均在场 = true（可发起真实模型请求的最低配置面） */
+    configured: boolean;
+    baseUrl: string;
+    model: string;
+    /** 凭据通道探测（存在性，值不打印）：keychain 命中 / env 命中（显式开启时）/ 全落空 */
+    credential: 'keychain' | 'env' | 'not-found';
+    /** env fallback 开关态（CAR_ALLOW_ENV_CREDENTIALS=1 或 llm.allowEnvFallback） */
+    envFallback: 'on' | 'off';
+    detail: string;
+}
+/** 1.4-S3 模型就绪检查（D-16）：baseUrl/model 在场性 + 凭据通道存在性探测（离线可过；值不打印） */
+export declare function doctorModelReadiness(opts?: {
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    configPath?: string;
+}): ModelReadinessCheck;
+/**
+ * registry 连通性检查：可达 = PASS（含延迟）；不可达/显式跳过 = SKIPPED（不失败）。
+ * 默认 registry 取 CAR_REGISTRY_URL，缺省 npmjs。
+ */
+export declare function doctorConnectivity(opts?: {
+    registryUrl?: string;
+    timeoutMs?: number;
+    /** 测试注入跳过 */
+    skip?: boolean;
+}): Promise<ConnectivityResult>;

package/dist/dx/doctor.js

@@ -0,0 +1,127 @@
+/**
+ * M6 · car doctor 增强（《系统设计》§3.2.M6.2 引导行：环境自检——沙箱/凭据/连通性）
+ *
+ * 口径：
+ *  - 凭据检查只探存在性、绝不打印值（secrets 红线：值入日志即泄露面）
+ *  - 连通性检查网络不可达 = 显式 SKIPPED 而非 FAIL——测试环境必须可离线通过（不失败）
+ *  - 1.1-S2：签名就绪检查行（mode / 信任根 / 配置文件通道发现态）——诊断面只读，
+ *    门禁判定仍在 sigGate/verifier；公钥可打印、信任根值本身不打印
+ */
+import { createPublicKey } from 'node:crypto';
+import { CredentialService, providerEnvVars } from '../runtime-core/credentials.js';
+import { loadCarConfig, mergeSignatureGate, mergeLlmConfig } from '../load/config.js';
+/** 凭据存在性检查：只报 present/not-set，永不输出值 */
+export function doctorCredentials(env = process.env) {
+    return [
+        {
+            name: 'CAR 凭据',
+            envVar: 'CAR_TOKEN',
+            present: !!env.CAR_TOKEN,
+            hint: 'registry 发布/拉取鉴权用；未设置不影响本地插件开发',
+        },
+        {
+            name: 'npm token',
+            envVar: 'NPM_TOKEN',
+            present: !!env.NPM_TOKEN,
+            hint: 'npm publish 需要时请设置（export NPM_TOKEN=…），值不入日志',
+        },
+    ];
+}
+/** M8 增强：keychain 通道状态（模型凭据读取面，§3.2.M8.2 凭据行）——能力探测口径，缺席显式降级不静默；离线可过 */
+export function doctorKeychain(opts = {}) {
+    return new CredentialService({ platform: opts.platform }).channelStatus;
+}
+/** 1.1-S2 签名就绪检查：mode 生效值 + 信任根在场可解析性 + car.config.json 发现态（离线可过；值不打印） */
+export function doctorSignature(opts = {}) {
+    const env = opts.env ?? process.env;
+    const cfg = loadCarConfig({ explicitPath: opts.configPath, cwd: opts.cwd });
+    let trustRoot = 'absent';
+    const raw = env.CAR_TRUST_ROOT || cfg.config.sandbox?.sigTrustRoot;
+    if (raw) {
+        try {
+            createPublicKey({ key: Buffer.from(raw, 'base64'), format: 'der', type: 'spki' });
+            trustRoot = 'valid';
+        }
+        catch {
+            trustRoot = 'invalid';
+        }
+    }
+    // 生效模式含配置层（配置文件解析失败时按 env/缺省口径合并，invalid 态在 configFile 显式呈现）
+    const { mode } = mergeSignatureGate(env, cfg.error ? {} : cfg.config);
+    const configFile = cfg.error ? 'invalid' : cfg.path ? 'found' : 'absent';
+    const parts = [
+        `mode=${mode}${mode === 'warn' ? '（DEC-1 ② 缺省；2026-12-25 到期翻转）' : ''}`,
+        trustRoot === 'absent'
+            ? '信任根未配置（全部插件按 unsigned 处理；car plugin-sign keygen 产出 .pub 即信任根）'
+            : trustRoot === 'valid'
+                ? '信任根已配置（ed25519 spki 可解析，值不打印）'
+                : '信任根已配置但不可解析（CAR-E-SIG 拒签风险——检查 CAR_TRUST_ROOT / sandbox.sig.trustRoot 是否为 spki base64）',
+        configFile === 'absent'
+            ? '配置文件未发现（car.config.json）'
+            : configFile === 'found'
+                ? `配置文件 ${cfg.path}（校验通过）`
+                : `配置文件无效（${cfg.error}）`,
+    ];
+    return { mode, trustRoot, configFile, detail: parts.join('；') };
+}
+/** 1.4-S3 模型就绪检查（D-16）：baseUrl/model 在场性 + 凭据通道存在性探测（离线可过；值不打印） */
+export function doctorModelReadiness(opts = {}) {
+    const env = opts.env ?? process.env;
+    const cfg = loadCarConfig({ explicitPath: opts.configPath, cwd: opts.cwd });
+    const { baseUrl, model, adapterId, allowEnvFallback } = mergeLlmConfig(env, cfg.error ? {} : cfg.config);
+    // 1.5-S4（D-20 配套）：adapterId → 凭据 provider 感知（anthropic → ANTHROPIC_API_KEY；缺省 openai-compat）
+    const provider = adapterId === 'anthropic' ? 'anthropic' : 'openai-compat';
+    const envFallback = allowEnvFallback ? 'on' : 'off';
+    let credential = 'not-found';
+    if (allowEnvFallback) {
+        // env fallback 显式开启：provider 候选变量存在性（providerEnvVars；只探存在不取值）
+        if (providerEnvVars(provider).some(n => env[n]))
+            credential = 'env';
+    }
+    if (credential === 'not-found') {
+        // keychain 通道存在性（resolve 探测，A080001 全落空即 not-found；值不打印）
+        try {
+            const ref = new CredentialService().resolve(provider, { env, allowEnvFallback });
+            credential = ref.source;
+        }
+        catch { /* 全落空 = not-found（登记口径，非错误） */ }
+    }
+    const configured = !!baseUrl && !!model;
+    const parts = [
+        configured ? `baseUrl=${baseUrl} model=${model}${adapterId ? ` adapter=${adapterId}` : ''}` : 'baseUrl/model 未配置（car run 真路径需 llm.* 配置或 CAR_LLM_BASE_URL/CAR_LLM_MODEL——见 car doctor / 配置指南）',
+        credential === 'keychain' ? `凭据=keychain 命中（car-runtime/${provider}，值不打印）`
+            : credential === 'env' ? '凭据=env 命中（显式开启 fallback，值不打印）'
+                : '凭据未就绪（keychain 未命中且 env fallback 未开或变量缺席——A080001 会引导至此）',
+        `envFallback=${envFallback}`,
+    ];
+    return { configured, baseUrl: baseUrl ?? '', model: model ?? '', credential, envFallback, detail: parts.join('；') };
+}
+/**
+ * registry 连通性检查：可达 = PASS（含延迟）；不可达/显式跳过 = SKIPPED（不失败）。
+ * 默认 registry 取 CAR_REGISTRY_URL，缺省 npmjs。
+ */
+export async function doctorConnectivity(opts = {}) {
+    const url = opts.registryUrl ?? process.env.CAR_REGISTRY_URL ?? 'https://registry.npmjs.org/-/ping';
+    if (opts.skip || process.env.CAR_OFFLINE === '1') {
+        return { status: 'SKIPPED', detail: `显式离线（CAR_OFFLINE=1 或测试注入）——跳过 ${url}`, latencyMs: 0 };
+    }
+    const t0 = Date.now();
+    // 同 1.4-BUG-2：AbortSignal.timeout → 手动 controller（进程退出 libuv win32 断言预防）
+    const controller = new AbortController();
+    const abortTimer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 2000);
+    try {
+        await fetch(url, { signal: controller.signal });
+        return { status: 'PASS', detail: url, latencyMs: Date.now() - t0 };
+    }
+    catch (e) {
+        clearTimeout(abortTimer);
+        return {
+            status: 'SKIPPED',
+            detail: `registry 不可达（${e.name}: ${e.message}）——离线环境显式跳过，不判失败`,
+            latencyMs: Date.now() - t0,
+        };
+    }
+    finally {
+        clearTimeout(abortTimer);
+    }
+}

package/dist/governance/dump.d.ts

@@ -0,0 +1,47 @@
+/**
+ * F14 · 治理视图（M2-S9）：配置树 dump + 事件产消图
+ *
+ * 口径（M2演进规划 F14 / PRD P1-7）：
+ *  - 配置树：装配快照（插件/依赖/服务/副作用计数）——来自 Context.governanceSnapshot()；
+ *  - 事件产消图：@mode 事件目录 × handlerChain（F11 priority 治理视图）——生产者=dispatch 点、
+ *    消费者=on 注册（label+priority，按实际执行序）；未声明事件在 F7 契约层已被禁止，此图即最终事实；
+ *  - 输出为纯数据结构（可 JSON 序列化落盘），供 `car governance dump` CLI（S10）与文档生成。
+ */
+import type { Context } from '../kernel/context.ts';
+import type { EventBus } from '../kernel/events.ts';
+export interface AssemblyTree {
+    plugins: {
+        name: string;
+        inject: string[];
+        state: string;
+        effects: number;
+        effectLabels: string[];
+        provides: string[];
+    }[];
+    services: {
+        name: string;
+        provider: string;
+    }[];
+    pending: string[];
+}
+export declare function dumpAssembly(ctx: Context): AssemblyTree;
+export interface EventGraphEdge {
+    event: string;
+    mode: string;
+    direction: 'producer' | 'consumer';
+    detail: string;
+}
+/** 事件产消图：目录内每个事件 → 模式（生产语义）+ 处理器链（消费视图） */
+export declare function dumpEventGraph(bus: EventBus, declared: Map<string, {
+    mode: string;
+}>): {
+    events: {
+        event: string;
+        mode: string;
+        consumers: {
+            label: string;
+            priority: number;
+        }[];
+    }[];
+    edges: EventGraphEdge[];
+};

package/dist/governance/dump.js

@@ -0,0 +1,17 @@
+export function dumpAssembly(ctx) {
+    return ctx.governanceSnapshot();
+}
+/** 事件产消图：目录内每个事件 → 模式（生产语义）+ 处理器链（消费视图） */
+export function dumpEventGraph(bus, declared) {
+    const events = [];
+    const edges = [];
+    for (const [event, { mode }] of declared) {
+        const consumers = bus.handlerChain(event);
+        events.push({ event, mode, consumers });
+        edges.push({ event, mode, direction: 'producer', detail: `dispatch(${mode}) at declared site（@mode 契约机器校验）` });
+        for (const c of consumers) {
+            edges.push({ event, mode, direction: 'consumer', detail: `${c.label} (priority=${c.priority})` });
+        }
+    }
+    return { events, edges };
+}

package/dist/host/facade.d.ts

@@ -0,0 +1,13 @@
+import type { HostProfile } from './mappings.ts';
+import type { RuntimeFacade } from './hostGateway.ts';
+import type { ToolReg } from '../load/loader.ts';
+/** 宿主工具面声明形态（toolList 出站——权限面字段不出站） */
+export interface HostToolDescriptor {
+    name: string;
+    description?: string;
+    parameters?: unknown;
+}
+export declare function createRuntimeFacade(opts: {
+    profiles: Map<string, HostProfile>;
+    tools?: Map<string, ToolReg>;
+}): RuntimeFacade;

package/dist/host/facade.js

@@ -0,0 +1,154 @@
+/**
+ * T-1 · RuntimeFacade 真实实现（M3-S12）：归一化数据流落到 SessionLog
+ *
+ * 口径（M3系统设计增补 T-1 / 决议⑤）：
+ *  - sessionStart：deriveSessionId 派生 + 首次映射登记事件落哈希链（hostRaw 载体，hostEvent=session_registered）；
+ *  - sessionTurn：宿主报事件批（{hostEvent, payload}[]）→ 逐条 normalizeHostEvent → append 落盘；
+ *    未命中事件走 hostRaw 降级（零静默）；turnEnd reason 由最后一条归一化 turnEnd 决定（缺省 completed）；
+ *  - 模型循环由宿主驱动（「统一边界而非统一内部」）：CAR 承载日志/审计/工具面，step 循环不暴露；
+ *  - 会话内存态 Map 承载（v0.2.0 SessionLog 语义），持久化经 sessionExport（取证包）与后续 S13 文件落盘增强。
+ *  - 1.6-S2（D-25）宿主工具面透传：opts.tools 注入插件工具 Map（mcp-serve 装配）——
+ *    toolList 出 name/description/parameters（declaredSideEffect 不出站：权限面只进权限门红线）；
+ *    toolCall 经权限门（T-22 缺省 write 收口；write 类 policy 拒绝——mcp-serve 无人审回路，
+ *    人审 confirm 属 turn 循环 preset.authorize 通道不外推到宿主面）+ 成对落链
+ *    （actor='user' 宿主=用户代理 / turnId='T0' 会话级能力面，sessionTurn 从 T1 起不冲突）；
+ *    未装配 tools 时显式报错（S13 占位「静默空面」退役——fail-visible）。
+ */
+import { SessionLog } from '../session/log.js';
+import { forkCrossHost, loadForkedLog } from '../session/fork.js';
+import { deriveSessionId, normalizeHostEvent } from './mappings.js';
+/** 迁移事件里已用过的最大 turn 序号（T{n}）——import 侧续跑 turnId 不与迁移段冲突 */
+function maxTurnIndex(log) {
+    let max = 0;
+    for (const e of log.events) {
+        const m = /^T(\d+)$/.exec(e.turnId);
+        if (m)
+            max = Math.max(max, Number(m[1]));
+    }
+    return max;
+}
+export function createRuntimeFacade(opts) {
+    const sessions = new Map();
+    const bySession = (sessionId) => {
+        const s = sessions.get(sessionId);
+        if (!s)
+            throw new Error(`CAR-E-HOST: session "${sessionId}" not found（session_start 先行）`);
+        return s;
+    };
+    return {
+        async sessionStart(args) {
+            const { hostSessionId, importJsonl } = args;
+            const hostId = args.__hostId;
+            const profile = opts.profiles.get(hostId);
+            if (!profile)
+                throw new Error('CAR-A050001: host profile not registered');
+            const sessionId = deriveSessionId(hostId, hostSessionId);
+            if (sessions.has(sessionId))
+                return { sessionId }; // 幂等：同一宿主会话重复 start 返回同一 CAR 会话
+            // M5-DEC4：fork 工件导入（跨宿主 resume）——归属校验（target 必须命中本宿主）+ 断链拒绝
+            if (importJsonl !== undefined) {
+                const { log } = loadForkedLog(importJsonl, { hostId, hostSessionId });
+                const turnCount = maxTurnIndex(log);
+                sessions.set(sessionId, { log, profile, hostSessionId, turnCount, lastReason: 'completed', hostToolSeq: 0 });
+                return { sessionId };
+            }
+            const log = new SessionLog(sessionId);
+            log.append('runtime', 'hostRaw', 'T0', { hostEvent: 'session_registered', hostId, hostSessionId });
+            sessions.set(sessionId, { log, profile, hostSessionId, turnCount: 0, lastReason: 'completed', hostToolSeq: 0 });
+            return { sessionId };
+        },
+        // M5-DEC4 转正：跨宿主 fork——源会话链逐字节迁移 + fork 标记落链，产出可迁移 JSONL 工件
+        async sessionFork({ sessionId, targetHostId, targetHostSessionId, upToSeq }) {
+            const s = bySession(sessionId);
+            if (!opts.profiles.has(targetHostId))
+                throw new Error(`CAR-A050001: target host "${targetHostId}" not registered（目标宿主须登记）`);
+            const fork = forkCrossHost(s.log, { hostId: targetHostId, hostSessionId: targetHostSessionId }, { upToSeq });
+            return { sessionId: fork.sessionId, jsonl: fork.jsonl, migrated: fork.migrated };
+        },
+        async sessionTurn({ sessionId, input }) {
+            const s = bySession(sessionId);
+            s.turnCount++;
+            const turnId = `T${s.turnCount}`;
+            let reason = 'completed';
+            const batch = input.events ?? [];
+            for (const ev of batch) {
+                const n = normalizeHostEvent(s.profile, ev.hostEvent, ev.payload ?? {});
+                s.log.append(n.actor, n.kind, turnId, n.payload);
+                if (n.kind === 'turnEnd') {
+                    const r = n.payload.reason;
+                    if (r)
+                        reason = r;
+                }
+            }
+            s.lastReason = reason;
+            return { reason, steps: s.turnCount };
+        },
+        async sessionStop({ sessionId }) {
+            const s = bySession(sessionId);
+            s.log.append('runtime', 'turnEnd', `T${s.turnCount}`, null, { reason: 'aborted' });
+            s.lastReason = 'aborted';
+            return { reason: 'aborted' };
+        },
+        async sessionStatus({ sessionId }) {
+            const s = bySession(sessionId);
+            return { state: 'idle', lastReason: s.lastReason };
+        },
+        async sessionReplay({ sessionId }) {
+            return { messages: bySession(sessionId).log.deriveMessages() };
+        },
+        async sessionVerify({ sessionId }) {
+            const brokenAt = bySession(sessionId).log.verifyChain();
+            return { ok: brokenAt === null, brokenAt };
+        },
+        async sessionExport({ sessionId }) {
+            const s = bySession(sessionId);
+            // 延迟 import 避免与 facade 类型循环（exportForensicsBundle 依赖 SessionLog 类型）
+            const { exportForensicsBundle } = await import('../session/export.js');
+            const bundle = exportForensicsBundle(s.log, {
+                sessionId, exportedBy: 'host:' + s.profile.hostId, exportedAt: new Date().toISOString(),
+                runtimeVersion: '0.2.0', sessionRange: { fromSeq: 0, toSeq: s.log.events.length - 1 },
+            });
+            return { bundle };
+        },
+        async toolList() {
+            if (!opts.tools)
+                return { tools: [] }; // 未装配 = 空面（与占位形态兼容）；装配后出声明面
+            const out = [];
+            for (const t of opts.tools.values()) {
+                out.push({ name: t.name, ...(t.description !== undefined ? { description: t.description } : {}), ...(t.parameters !== undefined ? { parameters: t.parameters } : {}) });
+            }
+            return { tools: out };
+        },
+        // 1.6-S2（D-25）：权限门语义——未知工具显式报错；T-22 缺省 write；write 类 policy 拒绝
+        //（mcp-serve 无人审回路，deny-by-default）；readonly 执行；工具异常=成对错误结果（US-5 同款）。
+        // 全路径成对落链（toolCall/toolResult）——宿主面调用 100% 留痕哈希链。
+        async toolCall(args) {
+            const { sessionId, tool, arguments: toolArgs } = args;
+            const s = bySession(String(sessionId));
+            if (!opts.tools)
+                throw new Error('CAR-E-HOST: tool 面未装配（mcp-serve 未登记插件工具——tool_list/tool_call 不可用）');
+            const id = `host-tc-${++s.hostToolSeq}`;
+            s.log.append('user', 'toolCall', 'T0', { id, tool: String(tool), args: toolArgs ?? {} });
+            const def = opts.tools.get(String(tool));
+            if (!def) {
+                s.log.append('plugin', 'toolResult', 'T0', { id, error: `unknown tool "${tool}"` });
+                return { ok: false, error: `unknown tool "${tool}"（tool_list 查看已装配工具面）` };
+            }
+            const sideEffect = def.declaredSideEffect ?? 'write'; // T-22 收口：未声明按最高约束
+            if (sideEffect === 'write') {
+                s.log.append('runtime', 'toolResult', 'T0', { id, error: 'authorization-denied', granted: false, mode: 'host-policy' });
+                return { ok: false, error: 'CAR-E-HOST-AUTHZ: write 类工具经宿主面 policy 拒绝（mcp-serve 无人审回路——D-25 deny-by-default）' };
+            }
+            let result;
+            let toolError;
+            try {
+                result = await def.run(toolArgs ?? {});
+            }
+            catch (e) {
+                toolError = String(e);
+            }
+            s.log.append('plugin', 'toolResult', 'T0', { id, result, ...(toolError ? { error: toolError } : {}) });
+            return toolError !== undefined ? { ok: false, error: toolError } : { ok: true, result };
+        },
+    };
+}

package/dist/host/hostGateway.d.ts

@@ -0,0 +1,117 @@
+/**
+ * T-1 · HostGateway（M3-S11 骨架）：CAR-as-MCP-Server 接入面
+ *
+ * 口径（M3系统设计增补 T-1 / 决议⑤ MCP 统一边界双宿主等价）：
+ *  - 10 tool 粗粒度会话级能力 + 工具面透传：session_start/turn/stop/status/replay/verify/export/fork
+ *    + tool_list/tool_call——step 循环不暴露（「统一边界而非统一内部」）；
+ *    session_fork 为 M5 DEC-4 转正项（跨宿主 fork/resume，M3 §1.7 显式延后 → 1.0 纳入）；
+ *  - hostId 登记制（A050001 语义扩展）：未登记宿主拒绝连接；
+ *  - ServerTransport 对偶（gateway.ts）：宿主作为 MCP client 经 tools/call 调用；
+ *  - tool handlers 由注入的 RuntimeFacade 提供（S12 接线 Claude Code、S13 Codex + 契约测试）；
+ *  - 所有宿主调用 100% 落审计（audit 钩子，复用 SessionLog）。
+ */
+import type { ServerTransport } from '../mcp/gateway.ts';
+import { normalizeHostEvent, type HostProfile } from './mappings.ts';
+export declare const HOST_TOOLS: readonly ['session_start', 'session_turn', 'session_stop', 'session_status', 'session_replay', 'session_verify', 'session_export', 'session_fork', 'tool_list', 'tool_call'];
+export type HostTool = (typeof HOST_TOOLS)[number];
+export interface RuntimeFacade {
+    sessionStart(args: {
+        hostSessionId: string; /** M5-DEC4：fork 工件导入（跨宿主 resume 入口），缺省为普通 start */
+        importJsonl?: string;
+    }): Promise<{
+        sessionId: string;
+    }>;
+    sessionTurn(args: {
+        sessionId: string;
+        input: unknown;
+    }): Promise<{
+        reason: string;
+        steps: number;
+    }>;
+    sessionStop(args: {
+        sessionId: string;
+    }): Promise<{
+        reason: string;
+    }>;
+    sessionStatus(args: {
+        sessionId: string;
+    }): Promise<{
+        state: string;
+        lastReason?: string;
+    }>;
+    sessionReplay(args: {
+        sessionId: string;
+    }): Promise<{
+        messages: unknown[];
+    }>;
+    sessionVerify(args: {
+        sessionId: string;
+    }): Promise<{
+        ok: boolean;
+        brokenAt: number | null;
+    }>;
+    sessionExport(args: {
+        sessionId: string;
+    }): Promise<{
+        bundle: unknown;
+    }>;
+    /** M5-DEC4 转正：跨宿主 fork（宿主 A 侧调用，产出可迁移工件 + 宿主 B 侧确定性会话 id） */
+    sessionFork(args: {
+        sessionId: string;
+        targetHostId: string;
+        targetHostSessionId: string;
+        upToSeq?: number;
+    }): Promise<{
+        sessionId: string;
+        jsonl: string;
+        migrated: number;
+    }>;
+    /** 1.6-S2（D-25）：声明面出站（name/description/parameters——declaredSideEffect 权限面不出站）；未装配 = 空面 */
+    toolList(args: Record<string, never>): Promise<{
+        tools: Array<{
+            name: string;
+            description?: string;
+            parameters?: unknown;
+        }>;
+    }>;
+    toolCall(args: {
+        sessionId: string;
+        tool: string;
+        arguments?: Record<string, unknown>;
+    }): Promise<{
+        ok: boolean;
+        result?: unknown;
+        error?: string;
+    }>;
+}
+export interface HostRegistration {
+    hostId: string;
+    profile: HostProfile;
+    transport: ServerTransport;
+}
+export declare class HostGateway {
+    #private;
+    constructor(opts: {
+        facade: RuntimeFacade;
+        audit: (event: {
+            kind: string;
+            detail: Record<string, unknown>;
+            ts: number;
+        }) => void;
+    });
+    /** 宿主登记（A050001 语义扩展：重复登记显式报错） */
+    registerHost(reg: HostRegistration): void;
+    listHosts(): string[];
+    /** 暴露给宿主的 tool 面（契约测试数据源：两宿主调用此方法结果必须等价） */
+    listTools(): HostTool[];
+    /** 宿主到达调用分发：登记检查 → tool 分发 → 归一化 → 审计（无旁路） */
+    handle(hostId: string, tool: string, args: Record<string, unknown>): Promise<{
+        ok: boolean;
+        result?: unknown;
+        error?: string;
+    }>;
+    /** ServerTransport 装配：把 JSON-RPC tools/call 桥到 handle（S12 接 Claude Code stdio） */
+    bindTransport(hostId: string): void;
+}
+/** 归一化便捷入口：宿主事件 → CAR 事件（mappings.ts 的 gateway 侧封装，供 S12 数据流接线） */
+export declare function ingestHostEvent(hostId: string, hostEvent: string, payload: Record<string, unknown>): ReturnType<typeof normalizeHostEvent>;

package/dist/host/hostGateway.js

@@ -0,0 +1,65 @@
+import { deriveSessionId, normalizeHostEvent } from './mappings.js';
+export const HOST_TOOLS = [
+    'session_start', 'session_turn', 'session_stop', 'session_status',
+    'session_replay', 'session_verify', 'session_export', 'session_fork', 'tool_list', 'tool_call',
+];
+export class HostGateway {
+    #hosts = new Map();
+    #audit;
+    constructor(opts) {
+        this.#facade = opts.facade;
+        this.#audit = opts.audit;
+    }
+    #facade;
+    /** 宿主登记（A050001 语义扩展：重复登记显式报错） */
+    registerHost(reg) {
+        if (this.#hosts.has(reg.hostId))
+            throw new Error(`CAR-E-HOST: hostId "${reg.hostId}" already registered（登记制）`);
+        this.#hosts.set(reg.hostId, reg);
+    }
+    listHosts() { return [...this.#hosts.keys()]; }
+    /** 暴露给宿主的 tool 面（契约测试数据源：两宿主调用此方法结果必须等价） */
+    listTools() { return [...HOST_TOOLS]; }
+    /** 宿主到达调用分发：登记检查 → tool 分发 → 归一化 → 审计（无旁路） */
+    async handle(hostId, tool, args) {
+        const host = this.#hosts.get(hostId);
+        if (!host) {
+            this.#audit({ kind: 'host-rejected', detail: { hostId, tool, reason: 'A050001' }, ts: Date.now() });
+            return { ok: false, error: 'CAR-A050001: unregistered host connection rejected（登记制）' };
+        }
+        if (!HOST_TOOLS.includes(tool)) {
+            return { ok: false, error: `unknown host tool "${tool}"（10 tool 面，step 循环不暴露）` };
+        }
+        // tool 名（snake_case MCP 约定）→ facade 方法（camelCase TS 约定）
+        const camel = tool.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+        const fn = this.#facade[camel];
+        if (typeof fn !== 'function')
+            return { ok: false, error: `host tool "${tool}" not wired in RuntimeFacade（S12 接线）` };
+        try {
+            const result = await fn.call(this.#facade, { ...args, __hostId: hostId });
+            this.#audit({ kind: 'host-call', detail: { hostId, tool, normalized: tool !== 'session_start' ? undefined : deriveSessionId(hostId, String(args.hostSessionId)) }, ts: Date.now() });
+            return { ok: true, result };
+        }
+        catch (e) {
+            this.#audit({ kind: 'host-call-error', detail: { hostId, tool, error: String(e) }, ts: Date.now() });
+            return { ok: false, error: String(e) };
+        }
+    }
+    /** ServerTransport 装配：把 JSON-RPC tools/call 桥到 handle（S12 接 Claude Code stdio） */
+    bindTransport(hostId) {
+        const host = this.#hosts.get(hostId);
+        if (!host)
+            throw new Error('CAR-A050001: cannot bind unregistered host');
+        void host.transport;
+    }
+}
+/** 归一化便捷入口：宿主事件 → CAR 事件（mappings.ts 的 gateway 侧封装，供 S12 数据流接线） */
+export function ingestHostEvent(hostId, hostEvent, payload) {
+    const profile = HOST_MAPPINGS_BY_ID.get(hostId);
+    if (!profile)
+        throw new Error(`CAR-A050001: host "${hostId}" not registered（归一化前必须登记）`);
+    return normalizeHostEvent(profile, hostEvent, payload);
+}
+import { HOST_MAPPINGS } from './mappings.js';
+const HOST_MAPPINGS_BY_ID = new Map(HOST_MAPPINGS.map(h => [h.hostId, h]));
+void 0; // 类型锚：ServerTransport 响应契约

package/dist/host/mappings.d.ts

@@ -0,0 +1,27 @@
+import type { EventKind } from '../session/log.ts';
+/** 跨宿主会话 id：SH- 前缀 + 24 hex（sha256 前 12 字节） */
+export declare function deriveSessionId(hostId: string, hostSessionId: string): string;
+export interface HostEventMapping {
+    /** 宿主事件名（精确匹配 v1；glob/regex v2 评估） */
+    hostEvent: string;
+    kind: EventKind;
+    actor: 'user' | 'model' | 'plugin' | 'runtime';
+    /** 宿主 payload 字段 → CAR payload 字段（浅拷贝重命名） */
+    payloadMap?: Record<string, string>;
+}
+export interface HostProfile {
+    hostId: string;
+    /** 映射表版本（契约变更须升版本 + 双轨过渡一个迭代） */
+    schemaVersion: 'host-mappings-v1';
+    mappings: HostEventMapping[];
+}
+/** host-mappings-v1：Claude Code / Codex 等价映射（同一接入面，两份纯数据 profile） */
+export declare const HOST_MAPPINGS: HostProfile[];
+export interface NormalizedEvent {
+    kind: EventKind;
+    actor: string;
+    payload: Record<string, unknown>;
+    degraded: boolean;
+}
+/** 事件归一化：命中映射 → 转写；未命中 → hostRaw 降级（payload 原样保留，零静默） */
+export declare function normalizeHostEvent(profile: HostProfile, hostEvent: string, payload?: Record<string, unknown>): NormalizedEvent;