@lqc123qwe/car-runtime 1.3.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
@@ -27,84 +33,234 @@ export interface SandboxSigConfig {
   sigTrustRoot?: string
 }
 
+export interface LlmConfig {
+  baseUrl?: string
+  model?: string
+  adapterId?: string
+  maxTokens?: number
+  allowEnvFallback?: boolean
+}
+
+export interface McpServerSpec {
+  /** stdio 通道启动命令（与 url 互斥——1.5-S2 起二选一显式登记） */
+  command?: string
+  args?: string[]
+  /** 启动环境变量（禁明文凭据——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> 显式启用） */
+  mcp?: { servers: Record<string, McpServerSpec> }
 }
 
 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') {
-      return { config: {}, error: `CAR-E-CONFIG: 未知顶层键 "${k}"（1.1 登记键位空间仅 sandbox.*）` }
-    }
-    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'
@@ -112,6 +268,34 @@ export interface ResolvedSignatureGate {
   unsignedAllow: boolean
 }
 
+/**
+ * 1.4-S3（D-16）：模型接入配置合并（flag > env > 配置 > 缺省）。
+ * env 已定义为显式意见（压过配置），未定义落配置层——与 mergeSignatureGate 同纪律。
+ * 凭据不在此层（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
+  if (env.CAR_LLM_BASE_URL) baseUrl = env.CAR_LLM_BASE_URL
+  if (flags.baseUrl) baseUrl = flags.baseUrl
+  let model = cfg.llm?.model
+  if (env.CAR_LLM_MODEL) model = env.CAR_LLM_MODEL
+  if (flags.model) model = flags.model
+  let adapterId = cfg.llm?.adapterId
+  if (flags.adapterId) adapterId = flags.adapterId
+  let maxTokens = cfg.llm?.maxTokens
+  if (flags.maxTokens !== undefined) maxTokens = flags.maxTokens
+  let allowEnvFallback = cfg.llm?.allowEnvFallback === true
+  if (env.CAR_ALLOW_ENV_CREDENTIALS !== undefined) allowEnvFallback = env.CAR_ALLOW_ENV_CREDENTIALS === '1'
+  return {
+    ...(baseUrl ? { baseUrl } : {}),
+    ...(model ? { model } : {}),
+    ...(adapterId ? { adapterId } : {}),
+    ...(maxTokens !== undefined ? { maxTokens } : {}),
+    allowEnvFallback,
+  }
+}
+
 /**
  * 优先级合并（flag > env > 配置 > 缺省）：产出装载签名门选项。
  * flagEnforce = CLI --sig-enforce；env 已定义即为显式意见（压过配置），未定义落配置层。

package/src/load/loader.ts

@@ -85,24 +85,38 @@ export function parseManifest(raw: unknown, file = '<manifest>'): Manifest {
   return m
 }
 
-export interface ToolReg { name: string; run: (args: any) => Promise<unknown> }
+export interface ToolReg {
+  name: string
+  run: (args: any) => Promise<unknown>
+  // —— 1.4-S1 声明面加法（进模型 ToolDefinition；缺省收口见 runtime-core/tools.ts T-22）——
+  /** 工具描述（进模型 function.description） */
+  description?: string
+  /** 入参 JSON Schema（进模型 function.parameters） */
+  parameters?: unknown
+  /** 副作用声明（缺省 write 收口——T-22 同款：未声明按最高约束） */
+  declaredSideEffect?: 'readonly' | 'write'
+}
 export interface CommandReg { name: string; run: (args: string[]) => Promise<void> }
 export interface PluginApi {
   registerTool(tool: ToolReg): void
   registerCommand(cmd: CommandReg): void
   getRegisteredTools(): ToolReg[]
+  /** 1.4-S2：插件设定 system prompt（session 级；last-wins；bindCore 时冲刷进宿主收集器，落 'system' 事件） */
+  setSystemPrompt(text: string): void
 }
 
 interface HostBinding {
   registerTool?(tool: ToolReg): void
   registerCommand?(cmd: CommandReg): void
   getRegisteredTools(): ToolReg[]
+  setSystemPrompt?(text: string): void
 }
 
 class ApiImpl {
   #host: HostBinding | undefined
   #pendingTools: ToolReg[] = []
   #pendingCommands: CommandReg[] = []
+  #pendingSystemPrompt: string | null = null
   registerTool(tool: ToolReg): void {
     if (this.#host?.registerTool) { this.#host.registerTool(tool); return }
     this.#pendingTools.push(tool) // 注册类动作始终可用：Stub 期收集，bind 后冲刷
@@ -111,6 +125,10 @@ class ApiImpl {
     if (this.#host?.registerCommand) { this.#host.registerCommand(cmd); return }
     this.#pendingCommands.push(cmd)
   }
+  setSystemPrompt(text: string): void {
+    if (this.#host?.setSystemPrompt) { this.#host.setSystemPrompt(text); return }
+    this.#pendingSystemPrompt = text // last-wins：多次设定取最后一次
+  }
   getRegisteredTools(): ToolReg[] {
     // 依赖宿主绑定的能力查询：bindCore 前一调用即抛错（Stub 显式失败）
     if (!this.#host) throw new Error('CAR-STUB: "getRegisteredTools" called before bindCore（启动期显式失败换运行期时序正确）')
@@ -120,8 +138,10 @@ class ApiImpl {
     this.#host = host
     for (const t of this.#pendingTools) host.registerTool?.(t)
     for (const c of this.#pendingCommands) host.registerCommand?.(c)
+    if (this.#pendingSystemPrompt !== null) host.setSystemPrompt?.(this.#pendingSystemPrompt)
     this.#pendingTools = []
     this.#pendingCommands = []
+    this.#pendingSystemPrompt = null
   }
 }
 

package/src/loop/stop.ts

@@ -12,6 +12,7 @@
  *  - 取消：未派发调用补记成对事件（toolCall + 合成错误 toolResult），日志无缺口
  */
 import type { SessionLog } from '../session/log.ts'
+import { CarM8Error } from '../runtime-core/errors.ts'
 
 export type StepOutcome = 'completed' | 'max-tokens' | 'null'
 export type TurnEndReason = 'completed' | 'max-tokens' | 'aborted' | 'error' | 'blocked' | 'interrupted'
@@ -23,6 +24,9 @@ export interface ToolDef {
   concludesTurn?: boolean
   terminate?: boolean
   run(args: Record<string, unknown>): Promise<unknown>
+  // —— 1.4-S1 声明面加法（进模型 ToolDefinition；执行面与声明面同一对象——声明面=授权面红线）——
+  description?: string
+  parameters?: unknown
 }
 /** 模型单步响应（provider 形态；stopReason 为不可变透传——ADR-001） */
 export interface ModelStep {
@@ -193,7 +197,14 @@ export async function runTurn(opts: {
       trail.push({ seq, reason: 'aborted' })
       return { reason: 'aborted', steps, endReasonTrail: trail }
     }
-    const seq = log.append('runtime', 'turnEnd', turnId, null, { reason: 'error', detail: String(e) }).seq
+    // 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/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
+}