@lqc123qwe/car-runtime 1.4.0 → 1.5.0

package/test/s33-anthropic-adapter.spec.ts

@@ -0,0 +1,354 @@
+/**
+ * 1.5-S1 · anthropic 适配器（S33）：Messages API 流式 SSE（D-20）
+ *
+ * 覆盖：
+ *  - 出站体形状：x-api-key / anthropic-version / system 顶层化（多条 \n\n 连接）/
+ *    toolResult → user tool_result（连续合并 + is_error）/ assistant tool_use /
+ *    tools input_schema / max_tokens 必填缺省 4096 + 显式覆盖
+ *  - stop_reason 映射（D-20 表）：end_turn/stop_sequence→stop、max_tokens→length、
+ *    tool_use→toolUse、refusal→aborted；未映射 fail-visible（raw 附 message）
+ *  - 流容错：ping/未知事件跳过；流内 error 事件 → error chunk；无 stop_reason → AL-05
+ *  - chatStep 集成：多 tool_use 块按 index 聚合 → toolUse 两条 ToolCall
+ *  - 基线同款：TLS 门（D-12a loopback）/ 凭据门 A080001 / 重试退避注入 / pre-aborted 取消零 chunk
+ *  - spawn E2E：car run --adapter-id anthropic 全链（生产调用点核查——1.5-GO-5）
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { spawn } from 'node:child_process'
+import { createServer } 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 { createAnthropicAdapter, RuntimeCore, assertTlsOrLoopback } from '../src/runtime-core/llm.ts'
+import { chatStep } from '../src/runtime-core/chatStep.ts'
+import { CredentialService } from '../src/runtime-core/credentials.ts'
+import { CarM8Error } from '../src/runtime-core/errors.ts'
+import type { LlmChunk } from '../src/runtime-core/types.ts'
+import { SessionLog } from '../src/session/log.ts'
+import { Context } from '../src/kernel/context.ts'
+import { runTurn } from '../src/loop/stop.ts'
+import { toToolDefinitions } from '../src/runtime-core/tools.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-s33-${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
+  }
+}
+
+function sseResponse(text: string): Response {
+  const enc = new TextEncoder()
+  const stream = new ReadableStream<Uint8Array>({
+    start(c) { c.enqueue(enc.encode(text)); c.close() },
+  })
+  return new Response(stream, { status: 200, headers: { 'content-type': 'text/event-stream' } })
+}
+
+const dataLine = (obj: unknown) => `data: ${JSON.stringify(obj)}\n\n`
+
+/** anthropic 流脚本 → SSE 文本（无 [DONE] 终结——anthropic 以 message_stop 收口，解析器 data-only 不依赖） */
+const anthropicSse = (events: object[]) => events.map(dataLine).join('')
+
+const TEXT_EVENTS = (text: string): object[] => [
+  { type: 'message_start', message: { role: 'assistant' } },
+  { type: 'content_block_start', index: 0, content_block: { type: 'text', text: '' } },
+  { type: 'content_block_delta', index: 0, delta: { type: 'text_delta', text } },
+  { type: 'content_block_stop', index: 0 },
+  { type: 'message_delta', delta: { stop_reason: 'end_turn' } },
+  { type: 'message_stop' },
+]
+
+const TOOLUSE_EVENTS = (blocks: Array<{ id: string; name: string; args: string }>, text?: string): object[] => {
+  const out: object[] = [{ type: 'message_start', message: { role: 'assistant' } }]
+  if (text) {
+    out.push(
+      { type: 'content_block_start', index: 0, content_block: { type: 'text', text: '' } },
+      { type: 'content_block_delta', index: 0, delta: { type: 'text_delta', text } },
+      { type: 'content_block_stop', index: 0 },
+    )
+  }
+  blocks.forEach((b, i) => {
+    const idx = text ? i + 1 : i
+    out.push(
+      { type: 'content_block_start', index: idx, content_block: { type: 'tool_use', id: b.id, name: b.name } },
+      { type: 'content_block_delta', index: idx, delta: { type: 'input_json_delta', partial_json: b.args } },
+      { type: 'content_block_stop', index: idx },
+    )
+  })
+  out.push({ type: 'message_delta', delta: { stop_reason: 'tool_use' } }, { type: 'message_stop' })
+  return out
+}
+
+async function drain(it: AsyncIterable<unknown>): Promise<unknown[]> {
+  const out: unknown[] = []
+  for await (const c of it) out.push(c)
+  return out
+}
+
+/** 无凭据服务（出站体形状单测用） */
+function adapterOf(fetchImpl: typeof fetch, extra: Record<string, unknown> = {}) {
+  return createAnthropicAdapter({ baseUrl: 'https://api.test', fetchImpl, ...extra })
+}
+
+// ==================== 出站体形状（D-20） ====================
+
+test('S33: anthropic 出站体——x-api-key/anthropic-version 头 + system 顶层化 + tools input_schema + max_tokens 缺省 4096', async () => {
+  const seen: Array<{ url: string; init: RequestInit }> = []
+  const adapter = adapterOf((async (url: string | URL, init?: RequestInit) => {
+    seen.push({ url: String(url), init: init! })
+    return sseResponse(anthropicSse(TEXT_EVENTS('ok')))
+  }) as typeof fetch)
+  await drain(adapter.chat({
+    model: 'claude-x',
+    messages: [
+      { role: 'system', content: '规则一' },
+      { role: 'system', content: '规则二' },
+      { role: 'user', content: 'hi' },
+    ],
+    tools: [{ name: 'echo', description: '回声', parameters: { type: 'object', properties: { t: { type: 'string' } } }, declaredSideEffect: 'readonly' }],
+  }))
+  assert.equal(seen.length, 1)
+  const { url, init } = seen[0]!
+  assert.ok(url.endsWith('/v1/messages'), '请求路径 {baseUrl}/v1/messages（官方 SDK base_url 同约定）')
+  const headers = init.headers as Record<string, string>
+  assert.equal(headers['x-api-key'], '', '无凭据服务时空 x-api-key（凭据门在适配器外单测覆盖）')
+  assert.equal(headers['anthropic-version'], '2023-06-01')
+  const body = JSON.parse(init.body as string)
+  assert.equal(body.model, 'claude-x')
+  assert.equal(body.stream, true)
+  assert.equal(body.max_tokens, 4096, 'D-20：Anthropic max_tokens 必填——req 缺省 4096')
+  assert.equal(body.system, '规则一\n\n规则二', 'system 消息提升顶层，多条 \\n\\n 连接')
+  assert.ok(!('system' in body.messages[0]), 'system 不再以消息形态出站')
+  assert.deepEqual(body.messages, [{ role: 'user', content: 'hi' }])
+  assert.deepEqual(body.tools, [{ name: 'echo', description: '回声', input_schema: { type: 'object', properties: { t: { type: 'string' } } } }], 'tools → input_schema；declaredSideEffect 不出站')
+})
+
+test('S33: anthropic 出站体——toolResult 合并单 user 多 tool_result + is_error + assistant tool_use + max_tokens 覆盖', async () => {
+  const seen: RequestInit[] = []
+  const adapter = adapterOf((async (_u: string | URL, init?: RequestInit) => {
+    seen.push(init!)
+    return sseResponse(anthropicSse(TEXT_EVENTS('done')))
+  }) as typeof fetch)
+  await drain(adapter.chat({
+    model: 'm',
+    maxTokens: 777,
+    messages: [
+      { role: 'user', content: '查天气' },
+      { role: 'assistant', content: { toolCall: { id: 'toolu_1', tool: 'weather', args: { city: '北京' } } } },
+      { role: 'toolResult', content: { id: 'toolu_1', result: '晴 25 度' } },
+      { role: 'toolResult', content: { id: 'toolu_2', error: 'boom' } },
+    ],
+    tools: [],
+  }))
+  const body = JSON.parse(seen[0]!.body as string)
+  assert.equal(body.max_tokens, 777, '显式 maxTokens 覆盖缺省')
+  assert.deepEqual(body.messages, [
+    { role: 'user', content: '查天气' },
+    { role: 'assistant', content: [{ type: 'tool_use', id: 'toolu_1', name: 'weather', input: { city: '北京' } }] },
+    { role: 'user', content: [
+      { type: 'tool_result', tool_use_id: 'toolu_1', content: '"晴 25 度"' },
+      { type: 'tool_result', tool_use_id: 'toolu_2', content: 'boom', is_error: true },
+    ] },
+  ], '连续 toolResult 合并单 user 多块；error → is_error')
+})
+
+// ==================== stop_reason 映射与流容错 ====================
+
+test('S33: stop_reason 映射——end_turn→stop / tool_use→toolUse（args 聚合）/ max_tokens→length / refusal→aborted', async () => {
+  const mk = (events: object[]) => adapterOf((async () => sseResponse(anthropicSse(events))) as typeof fetch)
+  const run = (events: object[]) => drain(mk(events).chat({ model: 'm', messages: [{ role: 'user', content: 'x' }], tools: [] }))
+
+  const stop = await run(TEXT_EVENTS('ok')) as LlmChunk[]
+  assert.equal(stop.at(-1)!.finishReason, 'stop')
+  assert.ok(stop.every(c => c.finishReason !== 'error'), '成功流零 error chunk')
+
+  const toolUse = await run(TOOLUSE_EVENTS([{ id: 'toolu_1', name: 'f', args: '{"a":1}' }])) as LlmChunk[]
+  assert.equal(toolUse.at(-1)!.finishReason, 'toolUse')
+  const startChunk = toolUse.find(c => c.toolCallDelta?.id)!
+  const deltaChunk = toolUse.find(c => c.toolCallDelta?.argumentsDelta)!
+  assert.equal(startChunk.toolCallDelta!.id, 'toolu_1', 'content_block_start 携带 id/name')
+  assert.equal(startChunk.toolCallDelta!.name, 'f')
+  assert.equal(deltaChunk.toolCallDelta!.argumentsDelta, '{"a":1}')
+
+  const len = await run([{ type: 'message_delta', delta: { stop_reason: 'max_tokens' } }]) as LlmChunk[]
+  assert.equal(len.at(-1)!.finishReason, 'length')
+
+  const abort = await run([{ type: 'message_delta', delta: { stop_reason: 'refusal' } }]) as LlmChunk[]
+  assert.equal(abort.at(-1)!.finishReason, 'aborted')
+
+  // stop_sequence 同映射 stop（登记口径）
+  const seq = await run([{ type: 'message_delta', delta: { stop_reason: 'stop_sequence' } }]) as LlmChunk[]
+  assert.equal(seq.at(-1)!.finishReason, 'stop')
+})
+
+test('S33: 未映射 stop_reason fail-visible（pause_turn 等）+ 流内 error 事件 + 无 stop_reason AL-05 兜底', async () => {
+  const mk = (events: object[]) => adapterOf((async () => sseResponse(anthropicSse(events))) as typeof fetch)
+  const run = (events: object[]) => drain(mk(events).chat({ model: 'm', messages: [{ role: 'user', content: 'x' }], tools: [] })) as Promise<LlmChunk[]>
+
+  const weird = await run([{ type: 'message_delta', delta: { stop_reason: 'pause_turn' } }])
+  assert.equal(weird.length, 1, 'fail-visible 单 chunk（sawFinish 命中无二次兜底）')
+  assert.equal(weird[0]!.finishReason, 'error')
+  assert.match(weird[0]!.error!.message, /pause_turn/, '原始 stop_reason 附 message（不吞没）')
+
+  const streamErr = await run([{ type: 'error', error: { type: 'overloaded_error', message: 'Overloaded' } }])
+  assert.equal(streamErr[0]!.finishReason, 'error')
+  assert.match(streamErr[0]!.error!.message, /Overloaded/)
+
+  const noFinish = await run([
+    { type: 'content_block_start', index: 0, content_block: { type: 'text' } },
+    { type: 'content_block_delta', index: 0, delta: { type: 'text_delta', text: 'half' } },
+    { type: 'ping' }, // 容错跳过
+    { type: 'message_stop' },
+  ])
+  assert.equal(noFinish.at(-1)!.finishReason, 'error')
+  assert.match(noFinish.at(-1)!.error!.message, /AL-05/, '流结束无 stop_reason = AL-05 显式化')
+})
+
+// ==================== chatStep 集成 + 基线同款 ====================
+
+test('S33: chatStep 集成——RuntimeCore 经 anthropic 适配器多 tool_use 块按 index 聚合为两条 ToolCall', async () => {
+  const adapter = adapterOf((async () => sseResponse(anthropicSse(TOOLUSE_EVENTS([
+    { id: 'toolu_1', name: 'get_weather', args: '{"city":"北京"}' },
+    { id: 'toolu_2', name: 'get_time', args: '{"tz":"UTC"}' },
+  ], '查两个')))) as typeof fetch)
+  const cred = new CredentialService({ keychainReader: () => null })
+  const core = new RuntimeCore(cred)
+  core.bindContext(new Context())
+  core.registerLlmAdapter(adapter, { default: true })
+  const log = new SessionLog('S-s33')
+  log.append('user', 'user', 'T0', 'x')
+  const r = await chatStep({ core, log, turnId: 'T0', model: 'm', tools: [] })
+  assert.equal(r.stopReason, 'toolUse')
+  assert.equal(r.text, '查两个')
+  assert.deepEqual(r.toolCalls, [
+    { id: 'toolu_1', tool: 'get_weather', args: { city: "北京" } },
+    { id: 'toolu_2', tool: 'get_time', args: { tz: 'UTC' } },
+  ], 'content_block_start id/name + input_json_delta 增量 → index 聚合')
+  assert.equal(log.assertModelVisibleLogged().ok, true)
+})
+
+test('S33: 基线同款——TLS 门（http 非 loopback 拒绝 / loopback 豁免）/ 凭据门 A080001 / 首块前 5xx 重试 / pre-aborted 零 chunk', async () => {
+  assertTlsOrLoopback('https://x.test')
+  assert.throws(() => createAnthropicAdapter({ baseUrl: 'http://api.test' }), /CAR-E-LLM-TLS/)
+  assert.doesNotThrow(() => createAnthropicAdapter({ baseUrl: 'http://127.0.0.1:9/v1' }), 'D-12a loopback 豁免同款')
+
+  // 凭据门：keychain 通道缺席 + env fallback 未开 → A080001（CarM8Error 保形）
+  const cred = new CredentialService({ keychainReader: () => null })
+  const adapter = adapterOf((async () => sseResponse(anthropicSse(TEXT_EVENTS('x')))) as typeof fetch, { credentials: cred })
+  await assert.rejects(
+    () => drain(adapter.chat({ model: 'm', messages: [{ role: 'user', content: 'x' }], tools: [] })),
+    (e: unknown) => e instanceof CarM8Error && (e as CarM8Error).code === 'A080001',
+  )
+
+  // 重试：首块前 5xx ×2 → 退避注入可观测 → 第三次成功（streamSsePost 引擎与 openai-compat 共用）
+  let attempts = 0
+  const sleeps: number[] = []
+  const retryAdapter = createAnthropicAdapter({
+    baseUrl: 'https://api.test',
+    retries: 2, backoffMs: [11, 22],
+    sleep: async ms => { sleeps.push(ms) },
+    fetchImpl: (async () => {
+      attempts++
+      if (attempts < 3) return new Response('boom', { status: 500 })
+      return sseResponse(anthropicSse(TEXT_EVENTS('ok')))
+    }) as typeof fetch,
+  })
+  const out = await drain(retryAdapter.chat({ model: 'm', messages: [{ role: 'user', content: 'x' }], tools: [] })) as LlmChunk[]
+  assert.equal(attempts, 3)
+  assert.deepEqual(sleeps, [11, 22], '指数退避注入可观测')
+  assert.equal(out.at(-1)!.finishReason, 'stop')
+
+  // 取消（D-19）：pre-aborted → 零 fetch 调用零 chunk
+  let called = 0
+  const cancelAdapter = adapterOf((async () => { called++; return sseResponse(anthropicSse(TEXT_EVENTS('x'))) }) as typeof fetch)
+  const chunks = await drain(cancelAdapter.chat({ model: 'm', messages: [{ role: 'user', content: 'x' }], tools: [], signal: { aborted: true } }))
+  assert.equal(chunks.length, 0)
+  assert.equal(called, 0, 'attempt 前取消——请求未发出')
+})
+
+test('S33: doctorModelReadiness provider 感知——adapterId anthropic → ANTHROPIC_API_KEY（值不打印）', () => {
+  withTempDir('doctor-anthropic', dir => {
+    writeFileSync(join(dir, 'car.config.json'), JSON.stringify({ llm: { baseUrl: 'https://api.anthropic.com', model: 'claude-x', adapterId: 'anthropic', allowEnvFallback: true } }))
+    const d1 = doctorModelReadiness({ env: { ANTHROPIC_API_KEY: TEST_KEY }, cwd: dir })
+    assert.equal(d1.configured, true)
+    assert.equal(d1.credential, 'env', 'anthropic provider 探测 ANTHROPIC_API_KEY')
+    assert.equal(d1.detail.includes(TEST_KEY), false, '凭据值永不打印')
+    // openai adapter 的凭据变量不算 anthropic 就绪
+    const d2 = doctorModelReadiness({ env: { OPENAI_API_KEY: TEST_KEY }, cwd: dir })
+    assert.equal(d2.credential, 'not-found', 'provider 变量面隔离')
+    // 显式 adapter 行在 detail
+    assert.match(d1.detail, /adapter=anthropic/)
+  })
+})
+
+// ==================== 多步真 E2E + spawn 生产调用点（1.5-GO-5） ====================
+
+test('S33: spawn CLI 全链——car run --adapter-id anthropic（x-api-key / system 顶层 / tool_result 第二请求）', async () => {
+  await withTempDir('cli-anthropic', 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[] = []
+    const headers: 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))
+        headers.push(req.headers)
+        res.writeHead(200, { 'content-type': 'text/event-stream' })
+        res.end(n++ === 0
+          ? anthropicSse(TOOLUSE_EVENTS([{ id: 'toolu_1', name: 'echo_tool', args: '{"text":"hi"}' }]))
+          : anthropicSse(TEXT_EVENTS('完成了')))
+      })
+    })
+    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',
+      '--adapter-id', 'anthropic',
+      '--prompt', 'call echo_tool with text hi', '--base-url', `http://127.0.0.1:${port}`, '--model', 'claude-cli',
+      '--system', '你是 CLI 集成测试助手'], {
+      cwd: dir,
+      env: { ...process.env, ANTHROPIC_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/)
+    // 请求 1：anthropic 出站体（system 顶层 / input_schema / x-api-key 凭据 / 版本头）
+    assert.equal(headers[0]['x-api-key'], TEST_KEY, '凭据经 CredentialService→x-api-key')
+    assert.equal(headers[0]['anthropic-version'], '2023-06-01')
+    assert.equal(bodies[0].system, '你是 CLI 集成测试助手', '--system 落链（system 事件）→ 顶层 system')
+    assert.equal(JSON.stringify(bodies[0]).includes(TEST_KEY), false, '凭据值不出站到消息体')
+    assert.equal(bodies[0].tools[0].name, 'echo_tool')
+    assert.equal(bodies[0].tools[0].input_schema.properties.text.type, 'string')
+    // 请求 2：assistant tool_use + user tool_result（D-20 映射回路）
+    const asst = bodies[1].messages.find((m: any) => m.role === 'assistant')
+    assert.deepEqual(asst.content, [{ type: 'tool_use', id: 'toolu_1', name: 'echo_tool', input: { text: 'hi' } }])
+    const tr = bodies[1].messages.find((m: any) => m.role === 'user' && Array.isArray(m.content))
+    assert.equal(tr.content[0].type, 'tool_result')
+    assert.equal(tr.content[0].tool_use_id, 'toolu_1')
+    assert.equal(tr.content[0].content, '"echo:hi"')
+  })
+})

package/test/s34-mcp-remote-transport.spec.ts

@@ -0,0 +1,250 @@
+/**
+ * 1.5-S2 · 远程 MCP 传输（S34）：Streamable HTTP 客户端（D-21）
+ *
+ * 覆盖：
+ *  - 懒 initialize 握手：首次 send 前 initialize → notifications/initialized（恰好一次）；
+ *    Mcp-Session-Id 捕获与回传；无会话头 server 容许
+ *  - 响应形态双兼容：application/json 单响应 / text/event-stream 逐事件取本请求 id
+ *  - McpGateway 注册回路：tools/list → 声明面（T-22 缺省 write 不变）；tools/call 往返
+ *  - resolveMcpHeaders：${ENV} 插值（值内任意位置）/ env 缺席显式报错 / 字面明文凭据拒绝
+ *  - config 校验：command/url 互斥恰好其一 / url 形态 / 通道专属键（args/env 仅 command、headers 仅 url）
+ *  - spawn CLI 全链：car run --mcp <url server>（1.5-GO-5 生产调用点——真 initialize→tools/list→tools/call）
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { spawn } from 'node:child_process'
+import { createServer, type Server, type IncomingMessage } 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 { McpGateway, type JsonRpcRequest } from '../src/mcp/gateway.ts'
+import { createHttpMcpTransport, resolveMcpHeaders, MCP_PROTOCOL_VERSION } from '../src/mcp/httpClient.ts'
+import { loadCarConfig } from '../src/load/config.ts'
+
+// 密钥扫描口径（generic-secret-assign）：夹具凭据经变量注入；值非真实凭据
+const TEST_TOKEN = 'test-token-456'
+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-s34-${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
+  }
+}
+
+interface SeenReq { url: string; method: string; headers: IncomingMessage['headers']; body: any }
+
+/** 本地假远程 MCP server（Streamable HTTP）：记录请求，按 method 分派；tools/list 可选 SSE 形态 */
+function fakeMcpHttp(opts: { sseToolsList?: boolean; sessionId?: string | null; rejectAll?: boolean } = {}): Promise<{
+  server: Server; url: string; seen: SeenReq[]; close: () => Promise<void>
+}> {
+  const seen: SeenReq[] = []
+  const server = createServer((req, res) => {
+    let raw = ''
+    req.on('data', c => { raw += c })
+    req.on('end', () => {
+      const body = raw ? JSON.parse(raw) : {}
+      seen.push({ url: req.url ?? '', method: body.method ?? '', headers: req.headers, body })
+      if (opts.rejectAll) {
+        res.writeHead(403, { 'content-type': 'application/json' })
+        res.end(JSON.stringify({ error: 'forbidden' }))
+        return
+      }
+      const respondJson = (payload: unknown, status = 200, headers: Record<string, string> = {}) => {
+        res.writeHead(status, { 'content-type': 'application/json', ...headers })
+        res.end(JSON.stringify(payload))
+      }
+      const respondSse = (payload: unknown) => {
+        res.writeHead(200, { 'content-type': 'text/event-stream' })
+        res.end(`data: ${JSON.stringify(payload)}\n\n`)
+      }
+      if (body.method === 'initialize') {
+        respondJson({ jsonrpc: '2.0', id: body.id, result: { protocolVersion: MCP_PROTOCOL_VERSION, capabilities: {}, serverInfo: { name: 'fake-remote', version: '0.0.0' } } }, 200, opts.sessionId === null ? {} : { 'mcp-session-id': opts.sessionId ?? 'sess-fake-1' })
+        return
+      }
+      if (body.id === undefined) { res.writeHead(202).end(); return } // notification（notifications/initialized）
+      if (body.method === 'tools/list') {
+        const result = { tools: [{ name: 'remote_echo', description: '远程回声', inputSchema: { type: 'object', properties: { t: { type: 'string' } } } }] }
+        opts.sseToolsList ? respondSse({ jsonrpc: '2.0', id: body.id, result }) : respondJson({ jsonrpc: '2.0', id: body.id, result })
+        return
+      }
+      if (body.method === 'tools/call') {
+        respondJson({ jsonrpc: '2.0', id: body.id, result: { content: [{ type: 'text', text: 'remote-ok:' + JSON.stringify(body.params.arguments) }] } })
+        return
+      }
+      respondJson({ jsonrpc: '2.0', id: body.id, error: { code: -32601, message: 'method not found: ' + body.method } }, 404)
+    })
+  })
+  const urlP = new Promise<string>(r => server.listen(0, '127.0.0.1', () => r(`http://127.0.0.1:${(server.address() as { port: number }).port}`)))
+  return urlP.then(url => ({ server, url, seen, close: () => new Promise<void>(r => server.close(() => r())) }))
+}
+
+// ==================== 传输客户端 ====================
+
+test('S34: 懒 initialize 握手——首次 send 前 initialize→initialized 恰好一次 + 会话头捕获回传 + tools/list 注册', async () => {
+  const { server, url, seen, close } = await fakeMcpHttp()
+  try {
+    const transport = createHttpMcpTransport({ url })
+    const gw = new McpGateway()
+    const tools = await gw.register({ serverId: 'remote', transport })
+    assert.equal(tools.length, 1)
+    assert.equal(tools[0]!.name, 'remote_echo')
+    assert.equal(tools[0]!.declaredSideEffect, 'write', 'T-22：未声明 sideEffect 注册时强制 write（远程与 stdio 同口径）')
+    // 请求序：initialize → notifications/initialized → tools/list
+    assert.deepEqual(seen.map(r => r.method), ['initialize', 'notifications/initialized', 'tools/list'])
+    assert.equal(seen[0]!.body.params.protocolVersion, MCP_PROTOCOL_VERSION)
+    assert.equal(seen[0]!.body.params.clientInfo.name, 'car-runtime')
+    // 会话头：initialize 请求无（尚未捕获）→ 后续请求回传
+    assert.equal(seen[0]!.headers['mcp-session-id'], undefined)
+    assert.equal(seen[2]!.headers['mcp-session-id'], 'sess-fake-1')
+    // accept 双形态声明 + 二次 send 不再握手
+    assert.match(String(seen[0]!.headers.accept), /application\/json/)
+    assert.match(String(seen[0]!.headers.accept), /text\/event-stream/)
+    const r = await gw.callTool('remote', 'remote_echo', { t: 'hi' })
+    assert.equal(r.ok, true)
+    assert.deepEqual(seen.map(m => m.method), ['initialize', 'notifications/initialized', 'tools/list', 'tools/call'], 'initialize 恰好一次')
+    // 声明面=授权面：gateway 声明面含远程工具
+    assert.equal(gw.listTools().some(t => t.serverId === 'remote' && t.name === 'remote_echo'), true)
+    transport.close()
+  } finally {
+    await close()
+  }
+})
+
+test('S34: SSE 响应形态——tools/list 以 text/event-stream 回包逐事件取本请求 id；无会话头 server 容许', async () => {
+  const { server, url, seen, close } = await fakeMcpHttp({ sseToolsList: true, sessionId: null })
+  try {
+    const transport = createHttpMcpTransport({ url })
+    const gw = new McpGateway()
+    const tools = await gw.register({ serverId: 'r2', transport })
+    assert.equal(tools.length, 1, 'SSE 流内 tools/list 响应正确解析')
+    assert.equal(seen[2]!.headers['mcp-session-id'], undefined, '无会话头 server 不回传（容许）')
+    transport.close()
+  } finally {
+    await close()
+  }
+})
+
+test('S34: closed 传输显式拒绝 + HTTP 错误 fail-visible（阶段名在错误信息）', async () => {
+  const { server, url, close } = await fakeMcpHttp({ rejectAll: true })
+  try {
+    const transport = createHttpMcpTransport({ url })
+    transport.close()
+    await assert.rejects(() => transport.send({ jsonrpc: '2.0', id: 1, method: 'tools/list' }), /closed/)
+    const bad = createHttpMcpTransport({ url })
+    await assert.rejects(() => bad.send({ jsonrpc: '2.0', id: 1, method: 'tools/list' }), /HTTP 403.*initialize/)
+    bad.close()
+  } finally {
+    await close()
+  }
+})
+
+// ==================== headers 凭据规则（D-21 / CR-05） ====================
+
+test('S34: resolveMcpHeaders——${ENV} 值内插值 / env 缺席显式报错 / 字面明文凭据拒绝', () => {
+  const env = { CAR_MCP_TOKEN: TEST_TOKEN }
+  assert.deepEqual(resolveMcpHeaders({ authorization: `Bearer \${CAR_MCP_TOKEN}` }, env), { authorization: `Bearer ${TEST_TOKEN}` })
+  assert.deepEqual(resolveMcpHeaders({ 'x-flag': 'plain' }, env), { 'x-flag': 'plain' })
+  assert.throws(() => resolveMcpHeaders({ authorization: 'Bearer ${CAR_MCP_MISSING}' }, env), /CAR_MCP_MISSING.*未设置/, 'env 缺席 fail-visible')
+  assert.throws(() => resolveMcpHeaders({ 'x-api-key': `sk-literal-123456789` }, env), /plaintext credential/, '字面 sk- 值拒绝（CR-05 配置明文禁令）')
+})
+
+// ==================== config 校验（command/url 互斥 + 通道专属键） ====================
+
+test('S34: mcp.servers url/headers 键位——互斥恰好其一 / url 形态 / 通道专属键 fail-visible', () => {
+  const load = (raw: unknown) => {
+    const p = join(withTmp(), 'c.json')
+    writeFileSync(p, JSON.stringify(raw))
+    return loadCarConfig({ explicitPath: p })
+  }
+  const withTmp = () => mkdtempSync(join(tmpdir(), 'car-s34-cfg-'))
+  // command + url 同给 = 显式报错
+  assert.match(load({ mcp: { servers: { a: { command: 'node', url: 'https://x.test' } } } }).error!, /恰好其一/)
+  // 都缺 = 显式报错
+  assert.match(load({ mcp: { servers: { a: { args: ['x'] } } } }).error!, /恰好其一/)
+  // url 形态
+  assert.match(load({ mcp: { servers: { a: { url: 'ftp://x' } } } }).error!, /http\(s\) URL/)
+  // 通道专属键
+  assert.match(load({ mcp: { servers: { a: { url: 'https://x.test', args: ['x'] } } } }).error!, /args 仅 stdio 通道/)
+  assert.match(load({ mcp: { servers: { a: { url: 'https://x.test', env: { K: 'v' } } } } }).error!, /env 仅 stdio 通道/)
+  assert.match(load({ mcp: { servers: { a: { command: 'node', headers: { h: 'v' } } } } }).error!, /headers 仅远程通道/)
+  // 有效：url + headers
+  const ok = load({ mcp: { servers: { a: { url: 'https://x.test/mcp', headers: { authorization: 'Bearer ${T}' } } } } })
+  assert.equal(ok.error, undefined)
+  assert.deepEqual(ok.config.mcp?.servers?.a, { url: 'https://x.test/mcp', headers: { authorization: 'Bearer ${T}' } })
+  // 有效：command（存量键位兼容）
+  const ok2 = load({ mcp: { servers: { b: { command: 'node', args: ['s.js'] } } } })
+  assert.equal(ok2.error, undefined)
+})
+
+// ==================== spawn CLI 全链（1.5-GO-5） ====================
+
+test('S34: spawn CLI 全链——car run --mcp 远程 server（initialize→tools/list→tools/call 进 turn）', async () => {
+  await withTempDir('cli-remote', async dir => {
+    const { server, url: mcpUrl, seen, close } = await fakeMcpHttp()
+    let llmHits = 0
+    const llm = createServer((req, res) => {
+      let raw = ''
+      req.on('data', c => { raw += c })
+      req.on('end', () => {
+        void req
+        const sse = (events: object[]) => {
+          res.writeHead(200, { 'content-type': 'text/event-stream' })
+          res.end(events.map(e => `data: ${JSON.stringify(e)}\n\n`).join('') + 'data: [DONE]\n\n')
+        }
+        // 请求序驱动：首轮出 tool_calls（MCP 工具名在 tools[0].function.name——openai 出站体），
+        // 次轮收尾文本；同时校验 MCP 工具确实进了声明面
+        const n = llmHits++
+        if (n === 0) {
+          const body = JSON.parse(raw)
+          assert.equal(body.tools?.[0]?.function?.name, 'mcp_remote_remote_echo', 'MCP 远程工具进声明面')
+          sse([
+            { choices: [{ delta: { tool_calls: [{ index: 0, id: 'c1', function: { name: 'mcp_remote_remote_echo', arguments: '{"t":"hi"}' } }] } }] },
+            { choices: [{ delta: {}, finish_reason: 'tool_calls' }] },
+          ])
+          return
+        }
+        sse([
+          { choices: [{ delta: { content: 'remote 调用完成' } }] },
+          { choices: [{ delta: {}, finish_reason: 'stop' }] },
+        ])
+      })
+    })
+    await new Promise<void>(r => llm.listen(0, '127.0.0.1', r))
+    const llmPort = (llm.address() as { port: number }).port
+    writeFileSync(join(dir, 'empty.ts'), `export const manifest = { name: 'empty', version: '1.0.0' }\nexport default function apply() {}\n`)
+    writeFileSync(join(dir, 'car.config.json'), JSON.stringify({
+      llm: { baseUrl: `http://127.0.0.1:${llmPort}/v1`, model: 'm' },
+      mcp: { servers: { remote: { url: mcpUrl, headers: { authorization: `Bearer \${CAR_MCP_TOKEN}` } } } },
+    }))
+    const child = spawn(process.execPath, ['--experimental-transform-types', CLI, 'run', 'empty.ts',
+      '--prompt', 'call the remote echo tool with t=hi', '--mcp', 'remote'], {
+      cwd: dir,
+      env: { ...process.env, OPENAI_API_KEY: TEST_TOKEN, CAR_ALLOW_ENV_CREDENTIALS: '1', CAR_MCP_TOKEN: TEST_TOKEN },
+      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()
+    llm.close()
+    assert.equal(code, 0, err + out)
+    assert.match(out, /\[MCP\] remote: 1 工具入声明面/)
+    assert.match(out, /turnEnd=completed/)
+    // 远程 server 侧：真握手 + 调用（Authorization 头 ${ENV} 展开）
+    assert.deepEqual(seen.map(r => r.method), ['initialize', 'notifications/initialized', 'tools/list', 'tools/call'])
+    assert.equal(seen[3]!.headers.authorization, `Bearer ${TEST_TOKEN}`)
+    assert.deepEqual(seen[3]!.body.params, { name: 'remote_echo', arguments: { t: 'hi' } })
+    await close()
+  })
+})