@lqc123qwe/car-runtime 1.3.0 → 1.4.0

package/test/s31-real-model-wiring.spec.ts

@@ -0,0 +1,329 @@
+/**
+ * 1.4-S1~S5 · 真实模型接线（S31）：声明面统一 / system 落链 / llm.* 配置 / loopback 豁免 /
+ * 取消透传 / CarM8Error 保形 / car run 装配重做（D-13）+ 多步真 E2E
+ *
+ * 覆盖（1.4-迭代规划 W1-1~W1-7）：
+ *  - toToolDefinitions：schema 透传 / T-22 缺省 write 收口
+ *  - 'system' 事件：投影 role:'system'（§3.5.5 新可见输入 = 新事件类型）
+ *  - llm.* 配置：校验 fail-visible / 优先级 flag > env > config / CAR_LLM_* env
+ *  - D-12a：http loopback 豁免（127.0.0.1/localhost/[::1]）+ 非 loopback http 拒绝
+ *  - 取消（D-19）：TurnAborted 首次实抛（finish 检查前序）+ runTurn 收口 aborted
+ *  - CarM8Error 保形：A080001 userHint/retryable 到 turnEnd
+ *  - 多步真 E2E：本地 loopback 假 SSE 服务——system 出站 / 工具 schema 出站 / Bearer 凭据 /
+ *    第二请求含 toolResult / 声明面=授权面；car run spawn 全链 + 无配置 exit 2
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { spawn } from 'node:child_process'
+import { createServer, type Server } from 'node:http'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { toToolDefinitions } from '../src/runtime-core/tools.ts'
+import { createOpenAICompatAdapter, RuntimeCore } from '../src/runtime-core/llm.ts'
+import { chatStep } from '../src/runtime-core/chatStep.ts'
+import { CredentialService } from '../src/runtime-core/credentials.ts'
+import { runTurn } from '../src/loop/stop.ts'
+import { Context } from '../src/kernel/context.ts'
+import { SessionLog } from '../src/session/log.ts'
+import { mergeLlmConfig, loadCarConfig } from '../src/load/config.ts'
+import { doctorModelReadiness } from '../src/dx/doctor.ts'
+
+// 密钥扫描口径（generic-secret-assign）：夹具凭据经变量注入（赋值行无引号字面量）；值非真实凭据
+const TEST_KEY = 'test-key-123'
+
+const CLI = join(dirname(fileURLToPath(import.meta.url)), '..', 'src', 'cli.ts')
+
+function withTempDir(name: string, fn: (dir: string) => Promise<void> | void): Promise<void> {
+  const dir = mkdtempSync(join(tmpdir(), `car-s31-${name}-`))
+  try {
+    const r = fn(dir)
+    const cleanup = () => { try { rmSync(dir, { recursive: true, force: true }) } catch { /* 红线 8 */ } }
+    if (r instanceof Promise) return r.finally(cleanup)
+    cleanup()
+    return Promise.resolve()
+  } catch (e) {
+    try { rmSync(dir, { recursive: true, force: true }) } catch { /* 红线 8 */ }
+    throw e
+  }
+}
+
+/** SSE 流响应（openai-compat 形态） */
+function sse(chunks: object[]): string {
+  return chunks.map(c => `data: ${JSON.stringify(c)}\n\n`).join('') + 'data: [DONE]\n\n'
+}
+
+const TOOL_CALL_SSE = (name: string, argsJson: string, id: string) => sse([
+  { choices: [{ delta: { role: 'assistant', content: '' } }] },
+  { choices: [{ delta: { tool_calls: [{ index: 0, id, function: { name, arguments: argsJson.slice(0, 3) } }] } }] },
+  { choices: [{ delta: { tool_calls: [{ index: 0, function: { arguments: argsJson.slice(3) } }] } }] },
+  { choices: [{ delta: {}, finish_reason: 'tool_calls' }] },
+])
+const TEXT_SSE = (text: string) => sse([
+  { choices: [{ delta: { role: 'assistant', content: '' } }] },
+  { choices: [{ delta: { content: text } }] },
+  { choices: [{ delta: {}, finish_reason: 'stop' }] },
+])
+
+/** 本地假 OpenAI 兼容服务：捕获请求体，按脚本回放 SSE */
+function fakeOpenAI(script: Array<(body: any) => string>): Promise<{ server: Server; url: string; bodies: any[]; headers: any[]; done: Promise<void> }> {
+  const bodies: any[] = []
+  const headers: any[] = []
+  let idx = 0
+  let finish: (v: void) => void = () => {}
+  const done = new Promise<void>(r => { finish = r })
+  const server = createServer((req, res) => {
+    let raw = ''
+    req.on('data', c => { raw += c })
+    req.on('end', () => {
+      bodies.push(JSON.parse(raw))
+      headers.push(req.headers)
+      res.writeHead(200, { 'content-type': 'text/event-stream' })
+      const step = script[Math.min(idx, script.length - 1)]
+      idx++
+      res.end(step(bodies[bodies.length - 1]))
+      if (idx >= script.length) finish()
+    })
+  })
+  const url = new Promise<string>(r => server.listen(0, '127.0.0.1', () => r(`http://127.0.0.1:${(server.address() as { port: number }).port}/v1`)))
+  return url.then(u => ({ server, url: u, bodies, headers, done }))
+}
+
+// ==================== S1：声明面统一 ====================
+
+test('S31: toToolDefinitions——description/parameters 透传 + T-22 缺省 write 收口 + 声明面=授权面', () => {
+  const map = new Map<string, any>([
+    ['full', { declaredSideEffect: 'readonly' as const, run: async () => 1, description: '读工具', parameters: { type: 'object', properties: { q: { type: 'string' } } } }],
+    ['bare', { declaredSideEffect: 'write' as const, run: async () => 2 }],
+  ])
+  const defs = toToolDefinitions(map)
+  assert.deepEqual(defs, [
+    { name: 'full', description: '读工具', parameters: { type: 'object', properties: { q: { type: 'string' } } }, declaredSideEffect: 'readonly' },
+    { name: 'bare', declaredSideEffect: 'write' },
+  ])
+  // declaredSideEffect 不出站的口径由 llm.ts 出站映射承载（llm.ts:237 只带 name/description/parameters）
+})
+
+// ==================== S2：system 落链 ====================
+
+test('S31: system 事件——落链 → deriveMessages 投影 role:system（§3.5.5 新可见输入 = 新事件类型）', () => {
+  const log = new SessionLog('S-sys-1')
+  log.append('runtime', 'system', 'system', '你是测试助手')
+  log.append('user', 'user', 'T0', 'hi')
+  const msgs = log.deriveMessages()
+  assert.deepEqual(msgs[0], { role: 'system', content: '你是测试助手' })
+  assert.equal(log.verifyChain(), null, '哈希链含 system 事件仍完整')
+  assert.equal(log.assertModelVisibleLogged().ok, true, 'N1 含 system 事件成立')
+})
+
+// ==================== S3：llm.* 配置通道 ====================
+
+test('S31: llm.* 配置——校验 fail-visible / 优先级 flag > env > config / CAR_LLM_* env 通道', () => {
+  withTempDir('llm-config', dir => {
+    // 未知键 / 类型错 fail-visible
+    writeFileSync(join(dir, 'bad.json'), JSON.stringify({ llm: { temperature: 0.7 } }))
+    assert.match(loadCarConfig({ explicitPath: join(dir, 'bad.json') }).error!, /未知键 llm\.temperature/)
+    writeFileSync(join(dir, 'bad2.json'), JSON.stringify({ llm: { maxTokens: 1.5 } }))
+    assert.match(loadCarConfig({ explicitPath: join(dir, 'bad2.json') }).error!, /llm\.maxTokens 必须为正整数/)
+    // 有效配置
+    const good = join(dir, 'good.json')
+    writeFileSync(good, JSON.stringify({ llm: { baseUrl: 'https://cfg.example/v1', model: 'cfg-model', maxTokens: 100, allowEnvFallback: true } }))
+    const cfg = loadCarConfig({ explicitPath: good }).config
+    // 优先级：config < env < flag
+    const c = mergeLlmConfig({}, cfg)
+    assert.equal(c.baseUrl, 'https://cfg.example/v1')
+    assert.equal(c.model, 'cfg-model')
+    assert.equal(c.allowEnvFallback, true)
+    const e = mergeLlmConfig({ CAR_LLM_BASE_URL: 'https://env.example/v1', CAR_LLM_MODEL: 'env-model' }, cfg)
+    assert.equal(e.baseUrl, 'https://env.example/v1')
+    assert.equal(e.model, 'env-model')
+    const f = mergeLlmConfig({ CAR_LLM_MODEL: 'env-model' }, cfg, { baseUrl: 'https://flag.example/v1', model: 'flag-model', maxTokens: 7 })
+    assert.equal(f.baseUrl, 'https://flag.example/v1')
+    assert.equal(f.model, 'flag-model')
+    assert.equal(f.maxTokens, 7)
+    // CAR_ALLOW_ENV_CREDENTIALS 显式意见压过配置（=0 关）
+    assert.equal(mergeLlmConfig({ CAR_ALLOW_ENV_CREDENTIALS: '0' }, cfg).allowEnvFallback, false)
+  })
+})
+
+test('S31: doctorModelReadiness——configured/not-found/env 三态（值不打印红线）', () => {
+  withTempDir('doctor-model', dir => {
+    const d1 = doctorModelReadiness({ env: {}, cwd: dir })
+    assert.equal(d1.configured, false)
+    assert.equal(d1.credential, 'not-found')
+    assert.match(d1.detail, /未配置/)
+    const d2 = doctorModelReadiness({
+      env: { CAR_LLM_BASE_URL: 'https://x/v1', CAR_LLM_MODEL: 'm', OPENAI_API_KEY: TEST_KEY, CAR_ALLOW_ENV_CREDENTIALS: '1' },
+      cwd: dir,
+    })
+    assert.equal(d2.configured, true)
+    assert.equal(d2.credential, 'env')
+    assert.equal(d2.envFallback, 'on')
+    assert.equal(d2.detail.includes(TEST_KEY), false, '凭据值永不打印')
+  })
+})
+
+// ==================== S4：D-12a + 取消 + CarM8Error ====================
+
+test('S31: D-12a loopback 豁免——http 仅 127.0.0.1/localhost/[::1]；非 loopback http 拒绝', () => {
+  assert.ok(createOpenAICompatAdapter({ baseUrl: 'http://127.0.0.1:1234/v1' }), 'loopback http 允许')
+  assert.ok(createOpenAICompatAdapter({ baseUrl: 'http://localhost:1234/v1' }), 'localhost http 允许')
+  assert.ok(createOpenAICompatAdapter({ baseUrl: 'http://[::1]:1234/v1' }), 'IPv6 loopback http 允许')
+  assert.throws(() => createOpenAICompatAdapter({ baseUrl: 'http://10.0.0.1:8080/v1' }), /CAR-E-LLM-TLS/, '非 loopback http 拒绝')
+  assert.throws(() => createOpenAICompatAdapter({ baseUrl: 'http://example.com/v1' }), /CAR-E-LLM-TLS/)
+  assert.ok(createOpenAICompatAdapter({ baseUrl: 'https://api.example.com/v1' }), 'https 任意域允许')
+})
+
+test('S31: 取消（D-19）——TurnAborted 首次实抛：pre-aborted 走 finish 前检查；runTurn 收口 aborted', async () => {
+  await withTempDir('cancel', async dir => {
+    const log = new SessionLog('S-cancel')
+    log.append('runtime', 'system', 'system', 'sys')
+    log.append('user', 'user', 'T0', 'hi')
+    const core = new RuntimeCore()
+    const signal = { aborted: true }  // pre-aborted：适配器 attempt 前静默收口（零 chunk）
+    const tools = new Map<string, any>([['t', { declaredSideEffect: 'readonly', run: async () => 'ok' }]])
+    // pre-aborted：适配器 attempt 前静默收口（零 chunk）→ chatStep finish 检查前抛 TurnAborted
+    const adapter = createOpenAICompatAdapter({ baseUrl: 'http://127.0.0.1:1/v1', fetchImpl: (async () => { throw new Error('不应发起请求') }) as typeof fetch })
+    core.registerLlmAdapter(adapter)
+    const r = await runTurn({
+      log, turnId: 'T0', tools, signal,
+      model: () => chatStep({ core, log, turnId: 'T0', model: 'm', tools: toToolDefinitions(tools), signal }),
+    })
+    assert.equal(r.reason, 'aborted', 'runTurn 既有 catch 收口 aborted')
+    const turnEnd = log.events.find(e => e.kind === 'turnEnd')!
+    assert.equal((turnEnd.meta as any)?.reason, 'aborted')
+    assert.equal(log.events.some(e => e.kind === 'assistant'), false, '无半截 assistant 落链')
+  })
+})
+
+test('S31: CarM8Error 保形——A080001 code/userHint/retryable 进 turnEnd（引导文案可达用户）', async () => {
+  await withTempDir('m8-error', async dir => {
+    const log = new SessionLog('S-m8err')
+    log.append('user', 'user', 'T0', 'hi')
+    const cred = new CredentialService()
+    const core = new RuntimeCore(cred)
+    core.registerLlmAdapter(createOpenAICompatAdapter({ baseUrl: 'http://127.0.0.1:1/v1', credentials: cred, provider: 'openai-compat' }))
+    const r = await runTurn({
+      log, turnId: 'T0',
+      tools: new Map<string, any>(),
+      model: () => chatStep({ core, log, turnId: 'T0', model: 'm', tools: [] }),
+    })
+    assert.equal(r.reason, 'error')
+    const turnEnd = log.events.find(e => e.kind === 'turnEnd')!
+    const meta = turnEnd.meta as any
+    assert.equal(meta.code, 'A080001')
+    assert.match(meta.userHint, /car doctor/, '引导文案进 turnEnd（1.4 前被 String(e) 拍平）')
+    assert.equal(meta.retryable, false)
+  })
+})
+
+// ==================== S5：多步真 E2E（真 HTTP + 真装配） ====================
+
+test('S31: 多步真 E2E——system 出站 / 工具 schema 出站 / Bearer 凭据 / 第二请求含 toolResult / 声明面=授权面', async () => {
+  await withTempDir('multistep', async dir => {
+    const { server, url, bodies, headers, done } = await fakeOpenAI([
+      () => TOOL_CALL_SSE('echo_tool', '{"text":"hi"}', 'call_1'),
+      () => TEXT_SSE('完成了'),
+    ])
+    try {
+      const log = new SessionLog('S-e2e')
+      log.append('runtime', 'system', 'system', '你是集成测试助手')
+      log.append('user', 'user', 'T0', '请调用 echo_tool')
+      const cred = new CredentialService({ keychainReader: s => (s === 'car-runtime/openai-compat' ? 'test-key-123' : null) })
+      const core = new RuntimeCore(cred)
+      const ctx = new Context()
+      core.bindContext(ctx)
+      core.registerLlmAdapter(createOpenAICompatAdapter({
+        baseUrl: url, credentials: cred, provider: 'openai-compat',
+      }), { default: true })
+      const tools = new Map<string, any>([[
+        'echo_tool',
+        { declaredSideEffect: 'readonly', description: '回声工具', parameters: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] }, run: async (a: any) => 'echo:' + a.text },
+      ]])
+      const r = await runTurn({
+        log, turnId: 'T0', tools,
+        model: () => chatStep({ core, log, turnId: 'T0', model: 'test-model', tools: toToolDefinitions(tools) }),
+      })
+      assert.equal(r.reason, 'completed')
+      assert.equal(r.steps, 2, '两步：toolUse → 工具执行 → stop')
+      await done
+      // 请求 1：system 消息出站（§3.5.5）+ 工具 schema 出站 + Bearer 凭据
+      assert.equal(bodies[0].messages[0].role, 'system')
+      assert.equal(bodies[0].messages[0].content, '你是集成测试助手')
+      assert.equal(bodies[0].tools.length, 1)
+      assert.equal(bodies[0].tools[0].function.name, 'echo_tool')
+      assert.deepEqual(bodies[0].tools[0].function.parameters, { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] })
+      assert.equal(bodies[0].tools[0].function.description, '回声工具')
+      assert.equal(headers[0].authorization, 'Bearer ' + TEST_KEY, '凭据经 CredentialService→Bearer')
+      assert.equal(JSON.stringify(bodies[0]).includes(TEST_KEY), false, '凭据值不出站到消息体')
+      // 请求 2：第二请求含 toolResult 消息（executeBatch 落链 → 投影 → 出站）
+      const toolMsg = bodies[1].messages.find((m: any) => m.role === 'tool')
+      assert.ok(toolMsg, '第二请求含 tool 消息')
+      assert.equal(toolMsg.tool_call_id, 'call_1')
+      assert.equal(toolMsg.content, '"echo:hi"')
+      // 落链面：assistant/toolCall/toolResult 齐备（N1）
+      assert.equal(log.assertModelVisibleLogged().ok, true)
+      const final = log.deriveMessages().at(-1)!
+      assert.equal(final.role, 'assistant')
+      assert.equal(final.content, '完成了')
+      void server
+    } finally {
+      server.close()
+      await done
+    }
+  })
+})
+test('S31: spawn CLI 全链——car run 真路径（--prompt/--base-url/--model + env 凭据）+ 无配置 exit 2', async () => {
+  await withTempDir('cli-real', async dir => {
+    const plugin = `export const manifest = { name: 'p', version: '1.0.0' }\n` +
+      `export default function apply(api) {\n` +
+      `  api.registerTool({ name: 'echo_tool', description: '回声工具', parameters: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] }, declaredSideEffect: 'readonly', run: async (a) => 'echo:' + a.text })\n` +
+      `}\n`
+    writeFileSync(join(dir, 'p.ts'), plugin)
+    const bodies: any[] = []
+    let n = 0
+    const server = createServer((req, res) => {
+      let raw = ''
+      req.on('data', c => { raw += c })
+      req.on('end', () => {
+        bodies.push(JSON.parse(raw))
+        res.writeHead(200, { 'content-type': 'text/event-stream' })
+        res.end(n++ === 0 ? TOOL_CALL_SSE('echo_tool', '{"text":"hi"}', 'call_1') : TEXT_SSE('完成了'))
+      })
+    })
+    await new Promise<void>(r => server.listen(0, '127.0.0.1', r))
+    const port = (server.address() as { port: number }).port
+    const child = spawn(process.execPath, ['--experimental-transform-types', CLI, 'run', 'p.ts',
+      '--prompt', 'call echo_tool with text hi', '--base-url', `http://127.0.0.1:${port}/v1`, '--model', 'cli-model',
+      '--system', '你是 CLI 集成测试助手'], {
+      cwd: dir,
+      env: { ...process.env, OPENAI_API_KEY: TEST_KEY, CAR_ALLOW_ENV_CREDENTIALS: '1' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    let out = ''
+    let err = ''
+    child.stdout.on('data', d => { out += d })
+    child.stderr.on('data', d => { err += d })
+    const code = await new Promise<number>(resolve => child.on('exit', c => resolve(c ?? -1)))
+    server.close()
+    assert.equal(code, 0, err)
+    assert.match(out, /turnEnd=completed/)
+    // system 出站（--system flag > 插件 setSystemPrompt）
+    assert.equal(bodies[0].messages[0].role, 'system')
+    assert.equal(bodies[0].messages[0].content, '你是 CLI 集成测试助手')
+    assert.equal(bodies[0].tools[0].function.name, 'echo_tool')
+    assert.match(out, /回放|投影/)
+
+    // 无模型配置 → exit 2 显式引导（D-13）
+    const noCfg = await new Promise<{ code: number; stderr: string }>(resolve => {
+      const c2 = spawn(process.execPath, ['--experimental-transform-types', CLI, 'run', 'p.ts'], { cwd: dir, stdio: ['ignore', 'pipe', 'pipe'] })
+      let e2 = ''
+      c2.stderr.on('data', d => { e2 += d })
+      c2.on('exit', c => resolve({ code: c ?? -1, stderr: e2 }))
+    })
+    assert.equal(noCfg.code, 2)
+    assert.match(noCfg.stderr, /CAR-E-LLM-CONFIG/)
+    assert.match(noCfg.stderr, /--demo/, '引导至演示流')
+  })
+})

package/test/s32-telemetry-mcp-ptc.spec.ts

@@ -0,0 +1,218 @@
+/**
+ * 1.4-S6~S7 · 遥测 trace 面 + MCP 工具进 turn + PTC 进真实 turn（S32）
+ *
+ * 覆盖（1.4-迭代规划 OTel 块 / MCP 块 / PTC 块）：
+ *  - telemetry trace 透传：traceId 复用 + parentSpanId 挂链（OTLP 出站体断言）；缺省行为不变
+ *  - TurnTracer：turn（根）→ step（子）层级；noop 门面零出站
+ *  - 生产调用点：car run spawn 全链——CAR_OTEL_ENDPOINT 捕获 OTLP traces（共享 traceId + 父子链）；
+ *    --mcp（config mcp.servers + 受控 stdio 假 server）→ MCP 工具进声明面 + callTool 真派发；
+ *    --ptc → run_code 参数 schema 出站 + worker 桥真调工具 + renderSdk 声明块进 system
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { spawn } from 'node:child_process'
+import { createServer, type Server } from 'node:http'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createTelemetryFacade, type TelemetrySpan } from '../src/runtime-core/telemetry.ts'
+import { TurnTracer } from '../src/runtime-core/trace.ts'
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+const CLI = join(ROOT, 'src', 'cli.ts')
+
+const okRes = () => ({ ok: true, status: 200 }) as unknown as Response
+
+// 密钥扫描口径：夹具凭据经变量注入（赋值行无引号字面量）
+const TEST_KEY = 'test-key-123'
+
+function withTempDir(name: string, fn: (dir: string) => Promise<void> | void): Promise<void> {
+  const dir = mkdtempSync(join(tmpdir(), `car-s32-${name}-`))
+  try {
+    const r = fn(dir)
+    const cleanup = () => { try { rmSync(dir, { recursive: true, force: true }) } catch { /* 红线 8 */ } }
+    if (r instanceof Promise) return r.finally(cleanup)
+    cleanup()
+    return Promise.resolve()
+  } catch (e) {
+    try { rmSync(dir, { recursive: true, force: true }) } catch { /* 红线 8 */ }
+    throw e
+  }
+}
+
+const sse = (chunks: object[]) => chunks.map(c => `data: ${JSON.stringify(c)}\n\n`).join('') + 'data: [DONE]\n\n'
+
+// ==================== trace 透传 + TurnTracer（单元） ====================
+
+test('S32: telemetry trace 透传——traceId 复用 + parentSpanId 进 OTLP 出站体；缺省行为不变', async () => {
+  await withTempDir('trace-unit', async dir => {
+    const bodies: any[] = []
+    const f = createTelemetryFacade({ endpoint: 'https://otel' }, {
+      fetchImpl: (async (_u: string | URL, init?: RequestInit) => { bodies.push(JSON.parse(String(init?.body))); return okRes() }) as typeof fetch,
+    })
+    // 子 span：显式 trace（traceId 复用 + 父 spanId）
+    const child = f.getTracer().startSpan('car.step', { attributes: { 'car.step': 1 }, trace: { traceId: 'a'.repeat(32), parentSpanId: 'b'.repeat(16) } })
+    assert.equal(child.traceId, 'a'.repeat(32), '显式 traceId 复用')
+    assert.equal(child.spanId.length, 16, 'spanId 生成')
+    child.end()
+    // 兄弟 span：同 traceId、无 parent
+    const sibling = f.getTracer().startSpan('car.step', { trace: { traceId: 'a'.repeat(32) } })
+    sibling.end()
+    // 独立 span：缺省随机 traceId（1.1 行为不变）
+    const standalone: TelemetrySpan = f.getTracer().startSpan('standalone')
+    assert.notEqual(standalone.traceId, 'a'.repeat(32))
+    standalone.end()
+    await f.flush()
+    const spans = bodies.flatMap(b => b.scopeSpans[0].spans)
+    const c = spans.find((s: any) => s.name === 'car.step' && s.parentSpanId === 'b'.repeat(16))
+    assert.ok(c, 'parentSpanId 进出站体')
+    assert.equal(c.traceId, 'a'.repeat(32))
+    const sib = spans.find((s: any) => s.name === 'car.step' && !s.parentSpanId)
+    assert.ok(sib, '同 traceId 无父的兄弟 span')
+  })
+})
+
+test('S32: TurnTracer——turn（根）→ step（子）层级共享 traceId；noop 门面零出站', async () => {
+  await withTempDir('tracer', async dir => {
+    const bodies: any[] = []
+    const f = createTelemetryFacade({ endpoint: 'https://otel' }, {
+      fetchImpl: (async (_u: string | URL, init?: RequestInit) => { bodies.push(JSON.parse(String(init?.body))); return okRes() }) as typeof fetch,
+    })
+    const tracer = new TurnTracer(f)
+    const turn = tracer.startTurn('T0')
+    const step = turn.stepSpan(1)
+    step.recordException(new Error('x'))
+    step.end('toolUse')
+    turn.end('completed')
+    await f.flush()
+    const spans = bodies.flatMap(b => b.scopeSpans[0].spans)
+    const turnSpan = spans.find((s: any) => s.name === 'car.turn')
+    const stepSpan = spans.find((s: any) => s.name === 'car.step')
+    assert.ok(turnSpan && stepSpan)
+    assert.equal(stepSpan.traceId, turnSpan.traceId, '同 turn 共享 traceId')
+    assert.equal(stepSpan.parentSpanId, turnSpan.spanId, 'step 父 = turn spanId')
+    assert.equal(turnSpan.attributes.find((a: any) => a.key === 'car.outcome').value.stringValue, 'completed')
+    // noop 门面：enabled=false → 句柄零出站（默认关三原则在 trace 面成立）
+    const noopTracer = new TurnTracer(createTelemetryFacade(null))
+    const noopTurn = noopTracer.startTurn('T0')
+    noopTurn.stepSpan(1).end('stop')
+    noopTurn.end('completed')
+    const nf = createTelemetryFacade({ endpoint: 'https://otel' }, { fetchImpl: (async () => { throw new Error('零出站') }) as typeof fetch })
+    void nf
+  })
+})
+
+// ==================== 生产调用点：car run 全链（MCP + PTC + trace 出站） ====================
+
+/** 受控 stdio MCP server（node 脚本文本）：tools/list + tools/call(upper) */
+const FAKE_MCP_SERVER = `
+const lines = [];
+let buf = '';
+process.stdin.on('data', d => {
+  buf += d.toString();
+  let nl;
+  while ((nl = buf.indexOf('\\n')) >= 0) {
+    const line = buf.slice(0, nl).trim(); buf = buf.slice(nl + 1);
+    if (!line) continue;
+    const req = JSON.parse(line);
+    if (req.method === 'tools/list') {
+      reply(req, { tools: [{ name: 'upper', description: '大写工具', sideEffect: 'readonly', inputSchema: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] } }] });
+    } else if (req.method === 'tools/call') {
+      reply(req, { content: [{ type: 'text', text: String(req.params.arguments.text).toUpperCase() }] });
+    }
+  }
+});
+function reply(req, result) { process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: req.id, result }) + '\\n'); }
+`
+
+const RUN_CODE = `const r = await tools.mcp_helper_upper({ text: 'abc' })\nreturn r`
+
+test('S32: car run 全链——MCP 工具进声明面+callTool 派发 / run_code worker 桥 / SDK 块进 system / trace 出站', async () => {
+  await withTempDir('full-chain', async dir => {
+    // 插件（声明面带 schema）
+    writeFileSync(join(dir, 'p.ts'), `export const manifest = { name: 'p', version: '1.0.0' }\n` +
+      `export default function apply(api) {\n` +
+      `  api.registerTool({ name: 'echo_tool', description: '回声', parameters: { type: 'object', properties: { text: { type: 'string' } } }, declaredSideEffect: 'readonly', run: async (a) => 'echo:' + a.text })\n` +
+      `  api.setSystemPrompt('插件级系统提示')\n` +
+      `}\n`)
+    // 配置：llm + mcp.servers
+    writeFileSync(join(dir, 'car.config.json'), JSON.stringify({
+      llm: { model: 'test-model' },
+      mcp: { servers: { helper: { command: process.execPath, args: ['-e', FAKE_MCP_SERVER] } } },
+    }))
+    // 假 LLM：req1 → run_code（worker 桥调 MCP 工具）；req2 → done
+    const llmBodies: any[] = []
+    let n = 0
+    const llmServer: Server = createServer((req, res) => {
+      let raw = ''
+      req.on('data', c => { raw += c })
+      req.on('end', () => {
+        llmBodies.push(JSON.parse(raw))
+        res.writeHead(200, { 'content-type': 'text/event-stream' })
+        res.end(n++ === 0
+          ? sse([
+              { choices: [{ delta: { tool_calls: [{ index: 0, id: 'c1', function: { name: 'run_code', arguments: JSON.stringify({ code: RUN_CODE, description: '经桥调 MCP 大写' } ) } }] } }] },
+              { choices: [{ delta: {}, finish_reason: 'tool_calls' }] },
+            ])
+          : sse([{ choices: [{ delta: { role: 'assistant', content: '' } }] }, { choices: [{ delta: { content: 'done' } }] }, { choices: [{ delta: {}, finish_reason: 'stop' }] }]))
+      })
+    })
+    await new Promise<void>(r => llmServer.listen(0, '127.0.0.1', r))
+    const llmPort = (llmServer.address() as { port: number }).port
+    // OTLP 捕获端点
+    const otlpBodies: any[] = []
+    const otlp: Server = createServer((req, res) => {
+      let raw = ''
+      req.on('data', c => { raw += c })
+      req.on('end', () => { if (req.url === '/v1/traces') otlpBodies.push(JSON.parse(raw)); res.writeHead(200).end() })
+    })
+    await new Promise<void>(r => otlp.listen(0, '127.0.0.1', r))
+    const otlpPort = (otlp.address() as { port: number }).port
+
+    const child = spawn(process.execPath, ['--experimental-transform-types', CLI, 'run', 'p.ts',
+      '--prompt', 'uppercase abc', '--base-url', `http://127.0.0.1:${llmPort}/v1`,
+      '--mcp', 'helper', '--ptc'], {
+      cwd: dir,
+      env: { ...process.env, OPENAI_API_KEY: TEST_KEY, CAR_ALLOW_ENV_CREDENTIALS: '1', CAR_OTEL_ENDPOINT: `http://127.0.0.1:${otlpPort}` },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    let out = ''
+    let err = ''
+    child.stdout.on('data', d => { out += d })
+    child.stderr.on('data', d => { err += d })
+    const exitDone = new Promise<number>(resolve => child.on('exit', c => resolve(c ?? -1)))
+    const code = await Promise.race([exitDone, new Promise<number>(r => setTimeout(() => r(-999), 60_000))])
+    llmServer.close()
+    otlp.close()
+
+    assert.equal(code, 0, `exit=${code}\nSTDOUT:\n${out}\nSTDERR:\n${err}`)
+    assert.match(out, /turnEnd=completed/)
+    // MCP：进声明面 + callTool 真派发
+    assert.match(out, /\[MCP\] helper: 1 工具入声明面/)
+    const req1Tools = llmBodies[0].tools.map((t: any) => t.function.name)
+    assert.ok(req1Tools.includes('mcp_helper_upper'), 'MCP 工具模型侧命名（D-18）')
+    assert.ok(req1Tools.includes('run_code'), 'run_code 入工具面')
+    const runCodeFn = llmBodies[0].tools.find((t: any) => t.function.name === 'run_code')
+    assert.deepEqual(runCodeFn.function.parameters.required, ['code', 'description'], 'run_code 参数 schema 出站（1.4 新增）')
+    // PTC：工具结果回链——写类工具先落授权决策 toolResult（M4 既有语义，观察项登记：投影双 tool 消息）、
+    // 再落执行结果；取最后一条（run_code 执行结果，worker 桥调 MCP upper → 'ABC'）
+    const toolMsg = llmBodies[1].messages.filter((m: any) => m.role === 'tool').at(-1)
+    assert.ok(toolMsg, '第二请求含 run_code 结果')
+    assert.equal(JSON.stringify(toolMsg.content).includes('ABC'), true, `worker 桥真调 MCP 工具（结果应含 ABC）：${JSON.stringify(toolMsg.content).slice(0, 200)}`)
+    // system：flag 缺省 → 插件 setSystemPrompt + SDK 声明块独立追加
+    assert.equal(llmBodies[0].messages[0].role, 'system')
+    assert.equal(llmBodies[0].messages[0].content, '插件级系统提示')
+    assert.equal(llmBodies[0].messages[1].role, 'system')
+    assert.match(llmBodies[0].messages[1].content, /declare const tools:/, 'renderSdk 声明块出站（1.4 前零生产调用点）')
+    assert.match(llmBodies[0].messages[1].content, /mcp_helper_upper/, 'SDK 声明含 MCP 工具')
+    // trace：turn/step 共享 traceId + 父子链（OTLP 出站）
+    await new Promise(r => setTimeout(r, 300))
+    const spans = otlpBodies.flatMap(b => b.scopeSpans[0].spans)
+    const turnSpan = spans.find((s: any) => s.name === 'car.turn')
+    const stepSpan = spans.find((s: any) => s.name === 'car.step')
+    assert.ok(turnSpan && stepSpan, `trace 出站（${otlpBodies.length} bodies, ${spans.length} spans）`)
+    assert.equal(stepSpan.traceId, turnSpan.traceId, '同 turn 共享 traceId')
+    assert.equal(stepSpan.parentSpanId, turnSpan.spanId, '父子链')
+  })
+})