@lqc123qwe/car-runtime 1.4.0 → 1.5.0

package/src/load/config.ts

@@ -1,25 +1,31 @@
 /**
- * 1.1-S3 · 签名配置文件通道（sandbox.* 键位空间；部署设计 §4.5.5 载体落地）
+ * 1.1-S3 签名配置文件通道 → 1.5-S3 完整形态（car.config.ts + zod，D-22）
  *
  * 口径：
- *  - 载体 = car.config.json（D-11a ①，2026-09-27 裁决：零依赖 / 免代码求值 / fail-visible 简单；
- *    系统设计 §3.2 的 car.config.ts + zod configLoader 完整形态登记后续，届时迁移并保持键位兼容）
- *  - 键位空间（嵌套 JSON 渲染点分键名）：
- *      sandbox.unsigned.allow  （部署设计 §4.5.5 冻结键；= CAR_UNSIGNED_ALLOW 等价通道）
- *      sandbox.sig.enforce     （= CAR_SIG_ENFORCE）
- *      sandbox.sig.trustRoot   （= CAR_TRUST_ROOT；ed25519 公钥非凭据——CR-05「凭据禁入配置明文」不破）
- *    未登记键 / 类型错 / 坏 JSON 一律 CAR-E-CONFIG 显式拒绝（fail-visible，禁静默忽略——
- *    防拼写漂移导致的「配置写了但不生效」）
- *  - 优先级（1.1 规划 §3 S3）：flag > env > 配置文件 > 缺省。env 已定义即为显式意见
- *    （CAR_SIG_ENFORCE 非 '1' = 显式 warn，可压过配置 enforce；未定义才落到配置层）。
+ *  - 载体（D-22）：发现序 **car.config.ts > car.config.json**（同目录两者并存 = ts 胜出，
+ *    json 忽略——禁静默合并）；显式 --config 按扩展名分派（.ts 走 TS 载体，其余 JSON 解析）；
+ *    TS 载体 = 动态 import()（Node 原生类型剥离，插件加载同纪律——jiti 继续登记不引入）；
+ *    形态 = `export default {…}`（非对象/缺 default 显式报错）。
+ *  - **预热协议**：loadCarConfig 保持同步签名（doctor/resolveSigGate 等既有调用面不动）；
+ *    car.config.ts 须先经 warmCarConfig 异步预热入缓存（CLI 入口统一预热），未预热显式报错
+ *    （fail-visible，禁静默回退 json——「配置写了但不生效」的漂移面必须显式化）。
+ *  - 校验层 zod 化（D-11a ① 修订）：zod ^3 为首个常规运行时依赖（用户点名登记项）；
+ *    fail-visible 语义与 CAR-E-CONFIG 错误码保持，zod issues 渲染为 `路径 原因`（首个 issue）；
+ *    键位空间与 1.1/1.4 完全一致（sandbox.* / llm.* / mcp.*；mcp.servers 本迭代加 url/headers）。
+ *    未登记键 / 类型错 / 坏 JSON / 坏 TS 一律 CAR-E-CONFIG 显式拒绝（禁静默忽略）。
+ *  - 优先级（1.1 规划 §3 S3）：flag > env > 配置文件 > 缺省。env 已定义即为显式意见。
  *    无配置文件 + 无 env 时行为与 1.0 完全一致（warn / 无信任根 / 不豁免）。
- *  - 本模块只读配置与合并优先级；门禁判定在 sigGate/verifier。发现序：显式路径 > cwd car.config.json。
+ *  - 本模块只读配置与合并优先级；门禁判定在 sigGate/verifier。发现序：显式路径 > cwd。
+ *  - 代码求值面（D-22 登记）：car.config.ts 为本机文件信任边界（与插件同域；配置无签名机制）。
  */
 import { existsSync, readFileSync } from 'node:fs'
 import { isAbsolute, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { z } from 'zod'
 import type { SignatureGateOptions } from './sigGate.ts'
 
 export const CONFIG_FILENAME = 'car.config.json'
+export const CONFIG_TS_FILENAME = 'car.config.ts'
 
 export interface SandboxSigConfig {
   unsignedAllow?: boolean
@@ -36,17 +42,22 @@ export interface LlmConfig {
 }
 
 export interface McpServerSpec {
-  command: string
+  /** stdio 通道启动命令（与 url 互斥——1.5-S2 起二选一显式登记） */
+  command?: string
   args?: string[]
-  /** 启动环境变量（禁明文凭据——gateway.containsPlaintextCredential 注册时强制检查） */
+  /** 启动环境变量（禁明文凭据——gateway.containsPlaintextCredential 注册时强制检查；仅 command 通道适用） */
   env?: Record<string, string>
+  /** 1.5-S2（D-21）：远程 Streamable HTTP 通道（与 command 互斥） */
+  url?: string
+  /** 1.5-S2（D-21）：远程请求头；值支持 ${ENV_VAR} 引用（凭据禁令 CR-05；仅 url 通道适用） */
+  headers?: Record<string, string>
 }
 
 export interface CarConfig {
   sandbox?: SandboxSigConfig
   /** 1.4-S3（D-16）：模型接入配置键位空间；凭据禁入（CR-05）——只放端点/模型名/开关 */
   llm?: LlmConfig
-  /** 1.4-S7（D-18）：MCP server 登记面（--mcp <id> 显式启用；serverId → stdio 启动规格） */
+  /** 1.4-S7（D-18）：MCP server 登记面（--mcp <id> 显式启用） */
   mcp?: { servers: Record<string, McpServerSpec> }
 }
 
@@ -54,145 +65,202 @@ export interface ConfigLoadResult {
   /** 实际读取的配置文件路径（cwd 未发现时缺省——未发现是正常态非错误） */
   path?: string
   config: CarConfig
-  /** fail-visible：显式路径不存在 / 坏 JSON / 未登记键 / 类型错的原因（非空 = 调用方必须中止） */
+  /** fail-visible：显式路径不存在 / 坏 JSON / 坏 TS / 未登记键 / 类型错的原因（非空 = 调用方必须中止） */
   error?: string
 }
 
-/** 加载配置：显式路径（必须存在，否则报错）或 cwd 发现（未发现 = 正常态返回空配置） */
-export function loadCarConfig(opts: { explicitPath?: string; cwd?: string } = {}): ConfigLoadResult {
+// ==================== zod 校验层（1.5-S3 迁移；错误消息含 s31/s34 回归锚点） ====================
+
+// 叶子消息不含路径——渲染层统一拼 `${path} ${message}`（s31 锚点：'llm.maxTokens 必须为正整数'）
+const nonEmptyTrimmed = () =>
+  z.string({ invalid_type_error: '必须为非空字符串', required_error: '必须为非空字符串' })
+    .trim()
+    .refine(v => v.length > 0, { message: '必须为非空字符串' })
+
+const stringMap = () =>
+  z.record(z.string(), z.string({ invalid_type_error: '必须为字符串' }), { invalid_type_error: '必须为字符串映射', required_error: '必须为字符串映射' })
+
+const mcpServerSchema = z.object({
+  command: nonEmptyTrimmed().optional(),
+  url: nonEmptyTrimmed().refine(v => /^https?:\/\//.test(v), { message: '必须为 http(s) URL' }).optional(),
+  args: z.array(z.string({ invalid_type_error: '必须为字符串' }), { invalid_type_error: '必须为字符串数组' }).optional(),
+  env: stringMap().optional(),
+  headers: stringMap().optional(),
+}).strict().superRefine((obj, ctx) => {
+  const hasCommand = typeof obj.command === 'string' && !!obj.command
+  const hasUrl = typeof obj.url === 'string' && !!obj.url
+  if (hasCommand === hasUrl) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: [], message: '需要 command（stdio）或 url（远程 Streamable HTTP）恰好其一（互斥）' })
+    return
+  }
+  if (obj.args !== undefined && !hasCommand) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['args'], message: '仅 stdio 通道（command）适用' })
+  if (obj.env !== undefined && !hasCommand) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['env'], message: '仅 stdio 通道（command）适用' })
+  if (obj.headers !== undefined && !hasUrl) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['headers'], message: '仅远程通道（url）适用' })
+})
+
+const rawSchema = z.object({
+  sandbox: z.object({
+    unsigned: z.object({
+      allow: z.boolean({ invalid_type_error: '必须为布尔', required_error: '必须为布尔' }).optional(),
+    }).strict().optional(),
+    sig: z.object({
+      enforce: z.boolean({ invalid_type_error: '必须为布尔', required_error: '必须为布尔' }).optional(),
+      trustRoot: nonEmptyTrimmed().optional(),
+    }).strict().optional(),
+  }).strict().optional(),
+  llm: z.object({
+    baseUrl: nonEmptyTrimmed().optional(),
+    model: nonEmptyTrimmed().optional(),
+    adapterId: nonEmptyTrimmed().optional(),
+    maxTokens: z.number({ invalid_type_error: '必须为正整数', required_error: '必须为正整数' })
+      .refine(v => Number.isFinite(v) && Number.isInteger(v) && v > 0, { message: '必须为正整数' })
+      .optional(),
+    allowEnvFallback: z.boolean({ invalid_type_error: '必须为布尔', required_error: '必须为布尔' }).optional(),
+  }).strict().optional(),
+  mcp: z.object({
+    servers: z.record(z.string(), mcpServerSchema, { invalid_type_error: '必须为对象（serverId → 启动规格）' }),
+  }).strict().optional(),
+}, { invalid_type_error: '配置顶层必须为 JSON 对象' }).strict()
+
+/** 未登记键提示（渲染层拼 path）——与系统设计键位空间同步 */
+const KEY_SPACES = '登记键位：sandbox.* / llm.* / mcp.servers.*'
+
+/** zod issue → CAR-E-CONFIG 渲染（首个 issue；unrecognized_keys 按键路径展开） */
+function renderIssue(error: z.ZodError): string {
+  const iss = error.issues[0]!
+  if (iss.code === 'unrecognized_keys') {
+    const keys = (iss as unknown as { keys?: string[] }).keys ?? []
+    const keyPath = [...iss.path, keys[0] ?? '?'].join('.')
+    return iss.path.length
+      ? `CAR-E-CONFIG: 未知键 ${keyPath}（${KEY_SPACES}）`
+      : `CAR-E-CONFIG: 未知顶层键 "${keys[0] ?? '?'}"（${KEY_SPACES}）`
+  }
+  const p = iss.path.join('.')
+  return p ? `CAR-E-CONFIG: ${p} ${iss.message}` : `CAR-E-CONFIG: ${iss.message}`
+}
+
+/** zod 解析 → CarConfig（扁平渲染：sandbox 嵌套键拍平——mergeSignatureGate 消费形态不变） */
+function parseCarConfig(raw: unknown): { config: CarConfig; error?: string } {
+  const parsed = rawSchema.safeParse(raw)
+  if (!parsed.success) return { config: {}, error: renderIssue(parsed.error) }
+  const d = parsed.data
+  const out: CarConfig = {}
+  if (d.sandbox) {
+    const sb: SandboxSigConfig = {}
+    if (d.sandbox.unsigned?.allow !== undefined) sb.unsignedAllow = d.sandbox.unsigned.allow
+    if (d.sandbox.sig?.enforce !== undefined) sb.sigEnforce = d.sandbox.sig.enforce
+    if (d.sandbox.sig?.trustRoot !== undefined) sb.sigTrustRoot = d.sandbox.sig.trustRoot
+    out.sandbox = sb
+  }
+  if (d.llm) {
+    const llm: LlmConfig = {}
+    if (d.llm.baseUrl !== undefined) llm.baseUrl = d.llm.baseUrl
+    if (d.llm.model !== undefined) llm.model = d.llm.model
+    if (d.llm.adapterId !== undefined) llm.adapterId = d.llm.adapterId
+    if (d.llm.maxTokens !== undefined) llm.maxTokens = d.llm.maxTokens
+    if (d.llm.allowEnvFallback !== undefined) llm.allowEnvFallback = d.llm.allowEnvFallback
+    out.llm = llm
+  }
+  if (d.mcp) {
+    const servers: Record<string, McpServerSpec> = {}
+    for (const [sid, sv] of Object.entries(d.mcp.servers)) {
+      const spec: McpServerSpec = {}
+      if (sv.command !== undefined) spec.command = sv.command
+      if (sv.url !== undefined) spec.url = sv.url
+      if (sv.args !== undefined) spec.args = sv.args
+      if (sv.env !== undefined) spec.env = sv.env
+      if (sv.headers !== undefined) spec.headers = sv.headers
+      servers[sid] = spec
+    }
+    out.mcp = { servers }
+  }
+  return { config: out }
+}
+
+// ==================== 载体装载（JSON 同步 / TS 预热缓存） ====================
+
+/** car.config.ts 预热缓存（path → 装载结果；warmCarConfig 每次以新 epoch 查询串击穿模块缓存） */
+const tsCache = new Map<string, ConfigLoadResult>()
+let tsEpoch = 0
+
+/**
+ * 1.5-S3（D-22）：car.config.ts 载体预热（动态 import 与插件加载同纪律——Node 原生类型剥离，
+ * Node 22 须 --experimental-transform-types / Node ≥23.6 原生支持；报错文案引导）。
+ * CLI 入口统一预热；直接调用 loadCarConfig 的库方在存在 car.config.ts 时须先 await 本函数。
+ */
+export async function warmCarConfig(opts: { explicitPath?: string; cwd?: string } = {}): Promise<void> {
   let path: string | undefined
   if (opts.explicitPath) {
+    if (!opts.explicitPath.endsWith('.ts')) return // JSON 显式路径走同步通道，无需预热
     path = isAbsolute(opts.explicitPath) ? opts.explicitPath : join(opts.cwd ?? process.cwd(), opts.explicitPath)
+  } else {
+    const candidate = join(opts.cwd ?? process.cwd(), CONFIG_TS_FILENAME)
+    if (!existsSync(candidate)) return // cwd 发现序：无 ts 载体 = 无需预热（json 同步可读）
+    path = candidate
+  }
+  tsEpoch++
+  const result = await loadTsConfigFile(path, tsEpoch)
+  tsCache.set(path, result)
+}
+
+async function loadTsConfigFile(path: string, epoch: number): Promise<ConfigLoadResult> {
+  try {
+    const mod = (await import(`${pathToFileURL(path).href}?cfg-epoch=${epoch}`)) as { default?: unknown }
+    const raw = mod.default
+    if (raw === undefined) {
+      return { path, config: {}, error: `CAR-E-CONFIG: ${path} 缺 default export（car.config.ts 形态 = export default {…}）` }
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+      return { path, config: {}, error: `CAR-E-CONFIG: ${path} default export 必须为对象（配置顶层）` }
+    }
+    const v = parseCarConfig(raw)
+    return v.error ? { path, config: {}, error: v.error } : { path, config: v.config }
+  } catch (e) {
+    const err = e as { code?: string; message?: string }
+    const hint = err.code === 'ERR_UNKNOWN_FILE_EXTENSION' || /Unknown file extension|loader/i.test(err.message ?? '')
+      ? `——当前 Node 未启用 .ts 载体（须 --experimental-transform-types 或 Node ≥23.6 原生类型剥离）`
+      : ''
+    return { path, config: {}, error: `CAR-E-CONFIG: car.config.ts 载入失败（${err.message}）${hint}` }
+  }
+}
+
+/** 加载配置：显式路径（必须存在，否则报错）或 cwd 发现（未发现 = 正常态返回空配置） */
+export function loadCarConfig(opts: { explicitPath?: string; cwd?: string } = {}): ConfigLoadResult {
+  if (opts.explicitPath) {
+    const path = isAbsolute(opts.explicitPath) ? opts.explicitPath : join(opts.cwd ?? process.cwd(), opts.explicitPath)
+    if (path.endsWith('.ts')) {
+      const hit = tsCache.get(path)
+      if (hit) return hit
+      return { path, config: {}, error: `CAR-E-CONFIG: car.config.ts 未预热（CLI 入口自动 warmCarConfig；直接调用方须先 await warmCarConfig({ explicitPath })）` }
+    }
     if (!existsSync(path)) {
       return { path, config: {}, error: `CAR-E-CONFIG: 配置文件不存在：${path}（--config 显式指定的路径必须存在）` }
     }
-  } else {
-    path = join(opts.cwd ?? process.cwd(), CONFIG_FILENAME)
-    if (!existsSync(path)) return { config: {} }
+    return loadJsonConfigFile(path)
+  }
+  // cwd 发现序（D-22）：car.config.ts > car.config.json（并存 = ts 胜出，json 忽略）
+  const tsPath = join(opts.cwd ?? process.cwd(), CONFIG_TS_FILENAME)
+  if (existsSync(tsPath)) {
+    const hit = tsCache.get(tsPath)
+    if (hit) return hit
+    return { path: tsPath, config: {}, error: `CAR-E-CONFIG: car.config.ts 未预热（CLI 入口自动 warmCarConfig；直接调用方须先 await warmCarConfig({ cwd })）` }
   }
+  const jsonPath = join(opts.cwd ?? process.cwd(), CONFIG_FILENAME)
+  if (!existsSync(jsonPath)) return { config: {} }
+  return loadJsonConfigFile(jsonPath)
+}
+
+function loadJsonConfigFile(path: string): ConfigLoadResult {
   let raw: unknown
   try {
     raw = JSON.parse(readFileSync(path, 'utf-8'))
   } catch (e) {
     return { path, config: {}, error: `CAR-E-CONFIG: 配置文件解析失败（${(e as Error).message}）——坏 JSON 显式拒绝，不静默忽略` }
   }
-  const v = validate(raw)
+  const v = parseCarConfig(raw)
   return v.error ? { path, config: {}, error: v.error } : { path, config: v.config }
 }
 
-/** 手写校验（fail-visible；零依赖红线——不引 zod，D-11a ①） */
-function validate(raw: unknown): { config: CarConfig; error?: string } {
-  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
-    return { config: {}, error: 'CAR-E-CONFIG: 配置顶层必须为 JSON 对象' }
-  }
-  const out: CarConfig = {}
-  for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
-    if (k !== 'sandbox' && k !== 'llm' && k !== 'mcp') {
-      return { config: {}, error: `CAR-E-CONFIG: 未知顶层键 "${k}"（登记键位空间：sandbox.* / llm.* / mcp.*）` }
-    }
-    if (k === 'mcp') {
-      if (typeof v !== 'object' || v === null || Array.isArray(v)) {
-        return { config: {}, error: 'CAR-E-CONFIG: mcp 必须为对象' }
-      }
-      const top = v as Record<string, unknown>
-      if (Object.keys(top).some(x => x !== 'servers')) {
-        return { config: {}, error: `CAR-E-CONFIG: 未知键 mcp.${Object.keys(top).find(x => x !== 'servers')}（登记键位：mcp.servers）` }
-      }
-      const serversRaw = top.servers
-      if (typeof serversRaw !== 'object' || serversRaw === null || Array.isArray(serversRaw)) {
-        return { config: {}, error: 'CAR-E-CONFIG: mcp.servers 必须为对象（serverId → 启动规格）' }
-      }
-      const servers: Record<string, McpServerSpec> = {}
-      for (const [sid, sv] of Object.entries(serversRaw as Record<string, unknown>)) {
-        if (typeof sv !== 'object' || sv === null || Array.isArray(sv)) {
-          return { config: {}, error: `CAR-E-CONFIG: mcp.servers.${sid} 必须为对象` }
-        }
-        const spec = sv as Record<string, unknown>
-        if (typeof spec.command !== 'string' || !spec.command.trim()) {
-          return { config: {}, error: `CAR-E-CONFIG: mcp.servers.${sid}.command 必须为非空字符串` }
-        }
-        const parsed: McpServerSpec = { command: spec.command.trim() }
-        if (spec.args !== undefined) {
-          if (!Array.isArray(spec.args) || spec.args.some(a => typeof a !== 'string')) {
-            return { config: {}, error: `CAR-E-CONFIG: mcp.servers.${sid}.args 必须为字符串数组` }
-          }
-          parsed.args = spec.args as string[]
-        }
-        if (spec.env !== undefined) {
-          if (typeof spec.env !== 'object' || spec.env === null || Array.isArray(spec.env) || Object.values(spec.env).some(x => typeof x !== 'string')) {
-            return { config: {}, error: `CAR-E-CONFIG: mcp.servers.${sid}.env 必须为字符串映射` }
-          }
-          parsed.env = spec.env as Record<string, string>
-        }
-        const unknownKey = Object.keys(spec).find(x => x !== 'command' && x !== 'args' && x !== 'env')
-        if (unknownKey) {
-          return { config: {}, error: `CAR-E-CONFIG: 未知键 mcp.servers.${sid}.${unknownKey}（登记键位：command / args / env）` }
-        }
-        servers[sid] = parsed
-      }
-      out.mcp = { servers }
-      continue
-    }
-    if (k === 'llm') {
-      if (typeof v !== 'object' || v === null || Array.isArray(v)) {
-        return { config: {}, error: 'CAR-E-CONFIG: llm 必须为对象' }
-      }
-      const llm: LlmConfig = {}
-      for (const [lk, lv] of Object.entries(v as Record<string, unknown>)) {
-        if (lk === 'baseUrl' || lk === 'model' || lk === 'adapterId') {
-          if (typeof lv !== 'string' || !lv.trim()) return { config: {}, error: `CAR-E-CONFIG: llm.${lk} 必须为非空字符串` }
-          if (lk === 'baseUrl') llm.baseUrl = lv.trim()
-          else if (lk === 'model') llm.model = lv.trim()
-          else llm.adapterId = lv.trim()
-        } else if (lk === 'maxTokens') {
-          if (typeof lv !== 'number' || !Number.isFinite(lv) || lv <= 0 || !Number.isInteger(lv)) {
-            return { config: {}, error: 'CAR-E-CONFIG: llm.maxTokens 必须为正整数' }
-          }
-          llm.maxTokens = lv
-        } else if (lk === 'allowEnvFallback') {
-          if (typeof lv !== 'boolean') return { config: {}, error: 'CAR-E-CONFIG: llm.allowEnvFallback 必须为布尔' }
-          llm.allowEnvFallback = lv
-        } else {
-          return { config: {}, error: `CAR-E-CONFIG: 未知键 llm.${lk}（登记键位：llm.baseUrl / llm.model / llm.adapterId / llm.maxTokens / llm.allowEnvFallback）` }
-        }
-      }
-      out.llm = llm
-      continue
-    }
-    if (typeof v !== 'object' || v === null || Array.isArray(v)) {
-      return { config: {}, error: 'CAR-E-CONFIG: sandbox 必须为对象' }
-    }
-    const sb: SandboxSigConfig = {}
-    for (const [sk, sv] of Object.entries(v as Record<string, unknown>)) {
-      if (sk === 'unsigned') {
-        if (typeof sv !== 'object' || sv === null || Array.isArray(sv)) return { config: {}, error: 'CAR-E-CONFIG: sandbox.unsigned 必须为对象' }
-        for (const [uk, uv] of Object.entries(sv as Record<string, unknown>)) {
-          if (uk !== 'allow') return { config: {}, error: `CAR-E-CONFIG: 未知键 sandbox.unsigned.${uk}（登记键位：sandbox.unsigned.allow）` }
-          if (typeof uv !== 'boolean') return { config: {}, error: 'CAR-E-CONFIG: sandbox.unsigned.allow 必须为布尔' }
-          sb.unsignedAllow = uv
-        }
-      } else if (sk === 'sig') {
-        if (typeof sv !== 'object' || sv === null || Array.isArray(sv)) return { config: {}, error: 'CAR-E-CONFIG: sandbox.sig 必须为对象' }
-        for (const [gk, gv] of Object.entries(sv as Record<string, unknown>)) {
-          if (gk === 'enforce') {
-            if (typeof gv !== 'boolean') return { config: {}, error: 'CAR-E-CONFIG: sandbox.sig.enforce 必须为布尔' }
-            sb.sigEnforce = gv
-          } else if (gk === 'trustRoot') {
-            if (typeof gv !== 'string' || !gv.trim()) return { config: {}, error: 'CAR-E-CONFIG: sandbox.sig.trustRoot 必须为非空字符串（ed25519 spki base64）' }
-            sb.sigTrustRoot = gv.trim()
-          } else {
-            return { config: {}, error: `CAR-E-CONFIG: 未知键 sandbox.sig.${gk}（登记键位：sandbox.sig.enforce / sandbox.sig.trustRoot）` }
-          }
-        }
-      } else {
-        return { config: {}, error: `CAR-E-CONFIG: 未知 sandbox 键 "${sk}"（1.1 登记键位：sandbox.unsigned.* / sandbox.sig.*）` }
-      }
-    }
-    out.sandbox = sb
-  }
-  return { config: out }
-}
-
 /** 合并产出（mode/unsignedAllow 恒有值——比 SignatureGateOptions 的可选字段更窄，doctor 等消费方免缺省分支） */
 export interface ResolvedSignatureGate {
   mode: 'warn' | 'enforce'
@@ -203,8 +271,8 @@ export interface ResolvedSignatureGate {
 /**
  * 1.4-S3（D-16）：模型接入配置合并（flag > env > 配置 > 缺省）。
  * env 已定义为显式意见（压过配置），未定义落配置层——与 mergeSignatureGate 同纪律。
- * 凭据不在此层（CR-05）：走 CredentialService（keychain → env OPENAI_API_KEY/CAR_LLM_API_KEY，
- * env fallback 需显式开启 = CAR_ALLOW_ENV_CREDENTIALS=1 或 llm.allowEnvFallback）。
+ * 凭据不在此层（CR-05）：走 CredentialService（keychain → env OPENAI_API_KEY/ANTHROPIC_API_KEY/
+ * CAR_LLM_API_KEY，env fallback 需显式开启 = CAR_ALLOW_ENV_CREDENTIALS=1 或 llm.allowEnvFallback）。
  */
 export function mergeLlmConfig(env: NodeJS.ProcessEnv, cfg: CarConfig, flags: { baseUrl?: string; model?: string; adapterId?: string; maxTokens?: number } = {}): LlmConfig {
   let baseUrl = cfg.llm?.baseUrl

package/src/mcp/httpClient.ts

@@ -0,0 +1,176 @@
+/**
+ * 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 登记不追溯）。
+ */
+import { request as httpRequest } from 'node:http'
+import { request as httpsRequest } from 'node:https'
+import type { ClientTransport, JsonRpcRequest, JsonRpcResponse } from './gateway.ts'
+import { containsPlaintextCredential } from './gateway.ts'
+import { assertTlsOrLoopback } from '../runtime-core/llm.ts'
+
+export 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 function rawPost(url: string, headers: Record<string, string>, body: string, timeoutMs: number): Promise<RawHttpResponse> {
+  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 as unknown as RawHttpResponse['body'],
+      })
+    })
+    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: Record<string, string>, env: NodeJS.ProcessEnv = process.env): Record<string, string> {
+  const out: Record<string, string> = {}
+  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: string) => {
+      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: HttpMcpServerSpec): ClientTransport {
+  // D-12a TLS 门（与 LLM 适配器同款）：https 直接通过；http 仅豁免 loopback
+  assertTlsOrLoopback(spec.url.replace(/\/+$/, ''))
+  const timeoutMs = spec.timeoutMs ?? 30_000
+  let sessionId: string | null = null
+  let initialized = false
+  let initPromise: Promise<void> | null = null
+  let closed = false
+
+  const baseHeaders = (): Record<string, string> => ({
+    'content-type': 'application/json',
+    'accept': 'application/json, text/event-stream',
+    ...(sessionId ? { 'mcp-session-id': sessionId } : {}),
+    ...spec.headers,
+  })
+
+  /** 流全读（JSON 响应） */
+  async function readAll(res: RawHttpResponse): Promise<Buffer> {
+    const parts: Buffer[] = []
+    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: RawHttpResponse, id: number): Promise<JsonRpcResponse> {
+    const decoder = new TextDecoder()
+    let buf = ''
+    try {
+      for await (const chunk of res.body) {
+        buf += decoder.decode(chunk, { stream: true })
+        let nl: number
+        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: any
+          try { evt = JSON.parse(data) } catch { continue }
+          if (evt?.id === id) return evt as JsonRpcResponse
+        }
+      }
+    } finally {
+      try { res.body.destroy() } catch { /* 流已自然结束 */ }
+    }
+    throw new Error('CAR-E-MCP: SSE 流结束未见本请求响应（阶段：read-response）')
+  }
+
+  async function postAndRead(body: unknown, matchId: number | null, phase: string): Promise<JsonRpcResponse> {
+    const res = await rawPost(spec.url, baseHeaders(), 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')) as JsonRpcResponse
+    return json
+  }
+
+  /** 懒 initialize 握手（首次 send 前恰好一次）：initialize → 会话头捕获 → notifications/initialized */
+  async function doInitialize(): Promise<void> {
+    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）`)
+    }
+  }
+
+  const transport: ClientTransport = {
+    send(req: JsonRpcRequest): Promise<JsonRpcResponse> {
+      return (async (): Promise<JsonRpcResponse> => {
+        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')
+      })()
+    },
+    alive: () => !closed,
+    close: () => { closed = true },
+  }
+  return transport
+}

package/src/runtime-core/chatStep.ts

@@ -48,11 +48,17 @@ export async function chatStep(opts: ChatStepOptions): Promise<ChatStepResult> {
     throw new Error(`CAR-E-N1: 模型请求前快照与日志投影失配 @ atSeq=${asserted.failedAt}（Model-visible means logged 违规）`)
   }
 
-  // 2. 请求消息 = 投影（角色系统：user/assistant/toolResult 与 LlmRequest 对齐；
-  //    assistant 工具调用以 { toolCall } content 形态原样透传——deriveMessages 投影即模型可见流）
+  // 2. 请求消息 = 投影（角色系统：user/assistant/toolResult 与 LlmRequest 对齐）；
+  //    toolCall 事件投影形态为 { role:'assistant', toolCall }（log.ts 口径）——此处归一化为
+  //    content {toolCall} 载荷（适配器历史回路映射的唯一消费源）。
+  //    1.5-BUG-1：此前仅透传 m.content，toolCall 属性被丢弃——工具调用历史在后续请求
+  //    静默消失（真实 provider 对无 tool_calls 前驱的 tool 消息直接 400）；anthropic E2E
+  //    生产调用点核查（1.5-GO-5）暴露，openai-compat 同样受益。
   const messages = log.deriveMessages().map(m => ({
     role: m.role as 'system' | 'user' | 'assistant' | 'toolResult',
-    content: m.content,
+    content: (m as unknown as { toolCall?: unknown }).toolCall !== undefined
+      ? { toolCall: (m as unknown as { toolCall: unknown }).toolCall }
+      : m.content,
   }))
 
   // 4. 流式消费（3. 凭据解析在适配器首块前，A080001 由此传播）

package/src/runtime-core/credentials.ts

@@ -37,6 +37,11 @@ const PROVIDER_ENV_VARS: Record<string, string[]> = {
 }
 const GENERIC_ENV_VARS = ['CAR_LLM_API_KEY']
 
+/** provider 候选 env 变量（doctor 存在性探测等诊断面复用；值永不打印） */
+export function providerEnvVars(provider: string): string[] {
+  return [...(PROVIDER_ENV_VARS[provider] ?? []), ...GENERIC_ENV_VARS]
+}
+
 /** keychain 服务名（命名空间隔离：car-runtime/<provider>） */
 export function keychainService(provider: string): string {
   return `car-runtime/${provider}`
@@ -102,7 +107,7 @@ export class CredentialService {
 
     const allowEnv = opts.allowEnvFallback === true || env.CAR_ALLOW_ENV_CREDENTIALS === '1'
     if (allowEnv) {
-      const candidates = [...(PROVIDER_ENV_VARS[provider] ?? []), ...GENERIC_ENV_VARS]
+      const candidates = providerEnvVars(provider)
       for (const name of candidates) {
         searched.push(`env:${name}`)
         if (env[name]) {