@lqc123qwe/car-runtime 1.2.0 → 1.4.0

package/src/load/config.ts

@@ -27,8 +27,27 @@ export interface SandboxSigConfig {
   sigTrustRoot?: string
 }
 
+export interface LlmConfig {
+  baseUrl?: string
+  model?: string
+  adapterId?: string
+  maxTokens?: number
+  allowEnvFallback?: boolean
+}
+
+export interface McpServerSpec {
+  command: string
+  args?: string[]
+  /** 启动环境变量（禁明文凭据——gateway.containsPlaintextCredential 注册时强制检查） */
+  env?: 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 启动规格） */
+  mcp?: { servers: Record<string, McpServerSpec> }
 }
 
 export interface ConfigLoadResult {
@@ -68,8 +87,77 @@ function validate(raw: unknown): { config: CarConfig; error?: string } {
   }
   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 (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 必须为对象' }
@@ -112,6 +200,34 @@ export interface ResolvedSignatureGate {
   unsignedAllow: boolean
 }
 
+/**
+ * 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）。
+ */
+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/stdioClient.ts

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

package/src/ptc/runCode.ts

@@ -116,6 +116,16 @@ export function makePtcToolDefinition(opts: { tools: Map<string, ToolBridge>; au
   return {
     name: 'run_code',
     description: '执行一段 erasable TypeScript 程序（PTC）——程序体内经 tools.<name>(args) 调用已注册工具',
+    // 1.4-S7：run_code 入参 schema（进模型声明面——此前无 parameters，模型看不到 code/description 形状）
+    parameters: {
+      type: 'object',
+      properties: {
+        code: { type: 'string', description: 'erasable TS 程序体（async 函数体；经 tools.<name>(args) 调用已注册工具）' },
+        description: { type: 'string', description: '本段程序的一句话描述（审计留痕）' },
+      },
+      required: ['code', 'description'],
+      additionalProperties: false,
+    },
     // T-22 语义：PTC 与 bash 同信任级别 → 强制 write 最高约束（不可声明为 readonly）
     declaredSideEffect: 'write' as const,
     run: async (args: { code: string; description: string; toolCallId?: string }) => {

package/src/runtime-core/chatStep.ts

@@ -15,7 +15,7 @@
  *     由 runTurn 落 turnEnd）；工具调用事件由 runTurn executeBatch 落（本层不重复）。
  */
 import type { SessionLog } from '../session/log.ts'
-import type { ModelStep, ToolCall } from '../loop/stop.ts'
+import { TurnAborted, type ModelStep, type ToolCall } from '../loop/stop.ts'
 import type { RuntimeCore } from './llm.ts'
 import type { ToolDefinition } from './types.ts'
 import { StreamRedactor } from './redaction.ts'
@@ -32,6 +32,8 @@ export interface ChatStepOptions {
   tools: ToolDefinition[]
   maxTokens?: number
   adapterId?: string
+  /** 1.4-S4（D-19）：turn 取消信号——chunk 间隙与流结束后（finish 检查前）检查，命中抛 TurnAborted */
+  signal?: { aborted: boolean }
 }
 
 /** ModelStep 加法扩展：脱敏计数留痕（S15 secretsRedacted 同名口径） */
@@ -49,7 +51,7 @@ export async function chatStep(opts: ChatStepOptions): Promise<ChatStepResult> {
   // 2. 请求消息 = 投影（角色系统：user/assistant/toolResult 与 LlmRequest 对齐；
   //    assistant 工具调用以 { toolCall } content 形态原样透传——deriveMessages 投影即模型可见流）
   const messages = log.deriveMessages().map(m => ({
-    role: m.role as 'user' | 'assistant' | 'toolResult',
+    role: m.role as 'system' | 'user' | 'assistant' | 'toolResult',
     content: m.content,
   }))
 
@@ -66,9 +68,12 @@ export async function chatStep(opts: ChatStepOptions): Promise<ChatStepResult> {
     tools,
     ...(maxTokens != null ? { maxTokens } : {}),
     ...(adapterId ? { adapterId } : {}),
+    ...(opts.signal ? { signal: opts.signal } : {}),
     ...(opts.log.sessionId ? { metadata: { sessionId: opts.log.sessionId, turnId, traceId: `${opts.log.sessionId}:${turnId}` } } : {}),
   })
   for await (const chunk of stream) {
+    // 1.4-S4（D-19）：chunk 间隙取消——此刻 assistant 尚未落链（流完才 append），无半截消息
+    if (opts.signal?.aborted) throw new TurnAborted()
     if (chunk.delta !== undefined) text += redactor.push(chunk.delta)
     if (chunk.toolCallDelta) {
       const idx = chunk.toolCallDelta.index ?? 0
@@ -81,6 +86,9 @@ export async function chatStep(opts: ChatStepOptions): Promise<ChatStepResult> {
     if (chunk.error) errorDetail = chunk.error.message
     if (chunk.finishReason !== undefined) stopReason = chunk.finishReason === 'aborted' ? 'error' : chunk.finishReason
   }
+  // 1.4-S4（D-19）：finish 检查前先查取消（适配器取消路径静默收口无 finishReason——
+  // 必须先于此处的契约兜底，否则取消被误判为适配器违规）
+  if (opts.signal?.aborted) throw new TurnAborted()
   if (stopReason === undefined) {
     // 适配器层已保证首 finishReason（AL-05）；防御性兜底显式化
     throw new Error('CAR-E-LLM-FINISH: 流结束无 finishReason（适配器契约违规）')

package/src/runtime-core/llm.ts

@@ -199,7 +199,13 @@ export function createOpenAICompatAdapter(opts: OpenAICompatOptions): LlmAdapter
   const id = opts.id ?? 'openai-compat'
   const baseUrl = opts.baseUrl.replace(/\/+$/, '')
   if (!baseUrl.startsWith('https://')) {
-    throw new Error(`CAR-E-LLM-TLS: baseUrl 必须 https（TLS 强制，§3.2.M8.4；本地明文部署请经 TLS 代理或自建适配器）`)
+    // 1.4-S4（D-12a，1.2 规划期裁决）：http 仅豁免 loopback——本地模型服务（Ollama 等）与
+    // 本地 E2E；非回环地址维持 TLS 强制（§3.2.M8.4）。豁免集显式列举，不扩大到局域网。
+    let loopback = false
+    try { const host = new URL(baseUrl).hostname.replace(/^\[|\]$/g, ''); loopback = host === '127.0.0.1' || host === 'localhost' || host === '::1' } catch { /* 解析失败 = 非法 URL，按非回环拒绝 */ }
+    if (!loopback) {
+      throw new Error(`CAR-E-LLM-TLS: baseUrl 必须 https（TLS 强制，§3.2.M8.4）；http 仅豁免 loopback（127.0.0.1/[::1]/localhost，D-12a）——远程明文部署请经 TLS 代理或自建适配器`)
+    }
   }
   const url = `${baseUrl}/chat/completions`
   const fetchImpl = opts.fetchImpl ?? fetch
@@ -210,6 +216,9 @@ export function createOpenAICompatAdapter(opts: OpenAICompatOptions): LlmAdapter
   const backoffMs = opts.backoffMs ?? [1_000, 2_000]
 
   const toOpenAI = (req: LlmRequest, apiKey: string) => ({
+    // 1.4-BUG-1：method: 'POST' 缺失——M8 最小实现潜伏缺陷（注入式 fetch 的单测忽略 method，
+    // 真 undici 对 GET+body 直接拒绝）；car run 真路径接线时暴露（生产调用点核查产出）
+    method: 'POST',
     headers: {
       'content-type': 'application/json',
       authorization: `Bearer ${apiKey}`,
@@ -250,6 +259,8 @@ export function createOpenAICompatAdapter(opts: OpenAICompatOptions): LlmAdapter
       const payload = toOpenAI(req, apiKey)
 
       for (let attempt = 0; ; attempt++) {
+        // 1.4-S4（D-19）：外部取消 ≠ 失败——attempt 前检查，静默收口（无 chunk、无 retry）
+        if (req.signal?.aborted) return
         const controller = new AbortController()
         const started = Date.now()
         let firstByteSeen = false
@@ -267,6 +278,9 @@ export function createOpenAICompatAdapter(opts: OpenAICompatOptions): LlmAdapter
           if (!res.body) throw new Retryable('响应无 body 流')
           let sawFinish = false
           for await (const chunk of parseSseStream(res.body)) {
+            // 1.4-S4（D-19）：chunk 间隙检查取消——abort 连接并静默收口（不产 error chunk，
+            // 不违反 finishReason 不可变；上层 chatStep 以自身 signal 检查抛 TurnAborted）
+            if (req.signal?.aborted) { controller.abort(); return }
             if (!firstByteSeen) { firstByteSeen = true; clearTimeout(firstByteTimer) }
             if (chunk.finishReason !== undefined) sawFinish = true
             yield chunk
@@ -279,6 +293,8 @@ export function createOpenAICompatAdapter(opts: OpenAICompatOptions): LlmAdapter
           }
           return
         } catch (e) {
+          // 1.4-S4（D-19）：外部取消（abort 连锁的 fetch 异常）≠ 失败——静默收口，不走 retry
+          if (req.signal?.aborted) return
           const beforeFirstByte = !firstByteSeen
           clearTimeout(firstByteTimer)
           // 首块前失败 = 网络错误/429/5xx/首字节超时（§3.5.4 重试条件全集）——未消费任何

package/src/runtime-core/telemetry.ts

@@ -4,7 +4,8 @@
  * 口径（§3.2.M8.5 关键约束，逐条落地）：
  *  - 默认关：无端点配置时不初始化任何 exporter——无配置 = noop 句柄 + 零出站（可机器断言）；
  *  - 显式开：用户配置端点即视为开启（CAR_OTEL_ENDPOINT 或显式 config 传入）；
- *  - 端点归用户：数据只发往用户自配 E-05；OTLP/HTTP JSON（fetch），导出超时 5s；
+ *  - 端点归用户：数据只发往用户自配 E-05；OTLP/HTTP JSON（node:http(s) 出站——1.4-BUG-2：全局
+ *    fetch/undici 在 win32 进程退出时触发 libuv 断言崩溃），导出超时 5s；
  *    1.2-S3 生产级策略（D-12b 口径修订，2026-09-27）：**0 重试 → 有界重试 ≤2**（仅 429/5xx/
  *    网络错误，退避 1s/2s；4xx 业务错不重试）——重试耗尽静默丢弃 + droppedExports 计数，
  *    永不抛错（BD-05「不抛错、不落审计」收紧保持）；隐私三原则不变（数据仍只发用户自配端点）；
@@ -22,6 +23,8 @@
  *    不引入 @opentelemetry/* 依赖（项目零依赖红线，README engines 纪律）。
  */
 import { randomBytes } from 'node:crypto'
+import { request as httpRequest } from 'node:http'
+import { request as httpsRequest } from 'node:https'
 
 export type SamplingSpec = 'always_on' | 'always_off' | { ratio: number }
 
@@ -55,10 +58,16 @@ export interface TelemetrySpan {
   recordException(err: unknown): this
   end(): void
   readonly traceId: string
+  /** 1.4-S6：子 span 挂链需要父 spanId（TurnTracer turn→step 层级） */
+  readonly spanId: string
 }
 
 export interface TelemetryTracer {
-  startSpan(name: string, opts?: { attributes?: Record<string, string | number | boolean> }): TelemetrySpan
+  startSpan(name: string, opts?: {
+    attributes?: Record<string, string | number | boolean>
+    /** 1.4-S6：trace 透传（traceId 复用 + parentSpanId 挂链）；缺省 = 新独立 trace */
+    trace?: { traceId: string; parentSpanId?: string }
+  }): TelemetrySpan
 }
 
 export interface TelemetryCounter {
@@ -102,6 +111,7 @@ const noopSpan = (): TelemetrySpan => ({
   recordException() { return noopSpan() },
   end() {},
   traceId: '',
+  spanId: '',
 })
 const NOOP_TRACER: TelemetryTracer = { startSpan: () => noopSpan() }
 const NOOP_METER: TelemetryMeter = { createCounter: () => ({ add() {} }) }
@@ -164,7 +174,25 @@ export function createTelemetryFacade(
     }
   }
 
-  const fetchImpl = opts.fetchImpl ?? fetch
+  // 1.4-BUG-2：出站默认走 node:http(s)（非全局 fetch/undici）——win32 上 undici socket +
+  // 进程退出触发 libuv 断言崩溃（UV_HANDLE_CLOSING, 0xC0000409，Node 23.5 实测、22 不复现）；
+  // 测试仍可注入 fetchImpl（缝保留）。res.resume() 排空响应体（连接干净归还）。
+  const fetchImpl = opts.fetchImpl ?? ((url: string | URL, init?: RequestInit): Promise<{ ok: boolean; status: number }> => new Promise(resolve => {
+    try {
+      const u = String(url)
+      const mod = u.startsWith('https:') ? httpsRequest : httpRequest
+      const req = mod(u, { method: init?.method ?? 'GET', headers: init?.headers as Record<string, string> | undefined }, res => {
+        res.resume()
+        res.on('end', () => {
+          const st = res.statusCode ?? 0
+          resolve({ ok: st >= 200 && st < 300, status: st })
+        })
+      })
+      req.setTimeout(timeoutMs, () => req.destroy(new Error('timeout')))
+      req.on('error', () => resolve({ ok: false, status: 599 })) // 网络/超时错误 → 599 可重试类
+      req.end(init?.body ?? null)
+    } catch { resolve({ ok: false, status: 599 }) }
+  }))
   const now = opts.now ?? Date.now
   const sleep = config?.sleep ?? (ms => new Promise<void>(r => setTimeout(r, ms)))
   const timeoutMs = config?.exportTimeoutMs ?? 5_000
@@ -194,12 +222,16 @@ export function createTelemetryFacade(
    */
   const exportOtlp = async (path: string, body: unknown): Promise<boolean> => {
     for (let attempt = 0; ; attempt++) {
+      // 1.4-BUG-2：AbortSignal.timeout 的内部定时器在进程退出时触发 libuv win32 断言崩溃
+      // （UV_HANDLE_CLOSING, 0xC0000409）——改手动 AbortController + clearTimeout 确定性清理
+      const controller = new AbortController()
+      const abortTimer = setTimeout(() => controller.abort(), timeoutMs)
       try {
         const res = await fetchImpl(endpoint + path, {
           method: 'POST',
           headers: baseHeaders,
           body: JSON.stringify(body),
-          signal: AbortSignal.timeout(timeoutMs),
+          signal: controller.signal,
         })
         if (res.ok) return true
         if ((res.status === 429 || res.status >= 500) && attempt < retryLimit) {
@@ -214,6 +246,8 @@ export function createTelemetryFacade(
           continue
         }
         return false
+      } finally {
+        clearTimeout(abortTimer)
       }
     }
   }
@@ -277,9 +311,10 @@ export function createTelemetryFacade(
   const activeTracer: TelemetryTracer = {
     startSpan(name, startOpts) {
       const record: SpanRecord = {
-        traceId: randomBytes(16).toString('hex'),
+        // 1.4-S6：trace 透传（traceId 复用 + parentSpanId 挂链）——缺省仍为独立随机 trace（1.1 行为不变）
+        traceId: startOpts?.trace?.traceId ?? randomBytes(16).toString('hex'),
         spanId: randomBytes(8).toString('hex'),
-        parentSpanId: null,
+        parentSpanId: startOpts?.trace?.parentSpanId ?? null,
         name,
         startMs: now(),
         endMs: 0,
@@ -287,6 +322,7 @@ export function createTelemetryFacade(
       }
       return {
         get traceId() { return record.traceId },
+        get spanId() { return record.spanId },
         setAttribute(key, value) { record.attributes[key] = value; return this },
         addEvent(evtName, attrs) { record.attributes[`event.${evtName}`] = attrs ? JSON.stringify(attrs) : evtName; return this },
         recordException(err) { record.attributes['exception.message'] = String((err as Error)?.message ?? err); return this },

package/src/runtime-core/tools.ts

@@ -0,0 +1,27 @@
+/**
+ * 1.4-S1 · 工具声明面转换（执行面 Map → 模型声明面 ToolDefinition[]）
+ *
+ * 口径（1.4 规划 W1-3 / D-18 / T-22 / 声明面=授权面红线）：
+ *  - **执行面与声明面同一对象**：ToolDef（loop/stop.ts，declaredSideEffect+run）即声明来源——
+ *    插件注册的 ToolReg 经 bindCore 收集后直接进本转换器，模型看到的工具集合 = 授权门放行的集合
+ *    （多渲一个 = 无授权执行面，少渲一个 = 授权白给——PTC SDK 同款红线）；
+ *  - T-22 收口：declaredSideEffect 缺省 write（未声明按最高约束——mcp/gateway.ts 注册点同款）；
+ *  - 跨源同名显式报错（禁静默覆盖）：Map 键即名字，插件/MCP 工具合并由调用方先行去重——
+ *    本转换器对重名（Map 键重复不可能，但 ToolDef.name 与键不一致时）显式报错；
+ *  - declaredSideEffect 不出站（llm.ts 出站映射只带 name/description/parameters——权限面只进权限门）。
+ */
+import type { ToolDef } from '../loop/stop.ts'
+import type { ToolDefinition } from './types.ts'
+
+export function toToolDefinitions(tools: Map<string, ToolDef>): ToolDefinition[] {
+  const out: ToolDefinition[] = []
+  for (const [name, t] of tools) {
+    out.push({
+      name,
+      ...(t.description !== undefined ? { description: t.description } : {}),
+      ...(t.parameters !== undefined ? { parameters: t.parameters } : {}),
+      declaredSideEffect: t.declaredSideEffect ?? 'write',
+    })
+  }
+  return out
+}

package/src/runtime-core/trace.ts

@@ -0,0 +1,63 @@
+/**
+ * 1.4-S6 · Turn 级 trace 面（W1 遥测未入链收尾）：turn span 包全程、step span 挂每次 model() 调用
+ *
+ * 口径（1.4 规划 W1 遥测块 / telemetry.ts 头注释）：
+ *  - 层级：turn（根 span，traceId 在此生成）→ step（parentSpanId = turn.spanId）——同一 turn 共享 trace；
+ *  - **挂点在装配层**（car run 的 model 回调闭包），loop 层零改动——遥测治理属调用方（telemetry.ts
+ *    「内容治理属调用方」口径）；设计微调登记：规划原文「runTurn opts.telemetry 注入面」改为装配层
+ *    闭包挂点，语义等价（turn/step 层级与出站面不变），loop 层保持纯停止语义；
+ *  - attributes 零内容面：turn_id/step 序号/outcome 枚举——无会话内容/提示词/路径。
+ */
+import { randomBytes } from 'node:crypto'
+import type { TelemetryFacade } from './telemetry.ts'
+
+export interface StepSpanHandle {
+  end(outcome: string): void
+  recordException(e: unknown): void
+}
+
+export interface TurnSpanHandle {
+  traceId: string
+  spanId: string
+  end(outcome: string): void
+  stepSpan(step: number): StepSpanHandle
+}
+
+export class TurnTracer {
+  readonly #facade: TelemetryFacade | null
+
+  constructor(facade: TelemetryFacade | null | undefined) {
+    // 默认关（无端点）= noop 句柄（零出站零积累——telemetry 三原则）
+    this.#facade = facade?.enabled ? facade : null
+  }
+
+  startTurn(turnId: string): TurnSpanHandle {
+    if (!this.#facade) {
+      return { traceId: '', spanId: '', end() {}, stepSpan: () => ({ end() {}, recordException() {} }) }
+    }
+    const tracer = this.#facade.getTracer()
+    const traceId = randomBytes(16).toString('hex')
+    const turn = tracer.startSpan('car.turn', { attributes: { 'car.turn_id': turnId }, trace: { traceId } })
+    return {
+      traceId,
+      spanId: turn.spanId,
+      end(outcome) {
+        turn.setAttribute('car.outcome', outcome)
+        turn.end()
+      },
+      stepSpan(step: number): StepSpanHandle {
+        const s = tracer.startSpan('car.step', {
+          attributes: { 'car.turn_id': turnId, 'car.step': step },
+          trace: { traceId, parentSpanId: turn.spanId },
+        })
+        return {
+          end(outcome) {
+            s.setAttribute('car.outcome', outcome)
+            s.end()
+          },
+          recordException(e) { s.recordException(e) },
+        }
+      },
+    }
+  }
+}

package/src/runtime-core/types.ts

@@ -19,9 +19,12 @@ export interface LlmRequest {
   tools: ToolDefinition[]
   maxTokens?: number
   metadata?: { sessionId: string; turnId: string; traceId: string }
-  // —— 规格外加法扩展（登记：M8 收口文档 §4）——
+  // —— 规格外加法扩展（登记：M8 收口文档 §4 / 1.4-S4）——
   /** 多适配器在册时显式路由；缺省用默认适配器 */
   adapterId?: string
+  /** 1.4-S4（D-19）：turn 取消信号（runTurn 的 {aborted} 形态透传）——适配器在 attempt 前 /
+   *  chunk 间隙检查；外部取消 ≠ 失败（不 retry、不产 error chunk，静默收口由 chatStep 抛 TurnAborted） */
+  signal?: { aborted: boolean }
 }
 
 /** 工具调用流式增量（跨 chunk 聚合出完整 ToolCall） */