@x-otto/cli 0.0.1-alpha.0

package/dist/bundled-extensions/plugin-otto-wire-protocols/src/anthropic-messages.ts

@@ -0,0 +1,916 @@
+import { createHash, randomUUID } from 'node:crypto'
+import Anthropic from '@anthropic-ai/sdk'
+import { ProviderError } from '@x-otto/shared'
+import { normalizeImageData, toAnthropicImageMime } from '@x-otto/interchange'
+import {
+  buildRequestHeaders,
+  sanitizeToolRoundtrips,
+  assertSystemNotificationPlacement,
+  degradedSystemNotificationText,
+  mergeConsecutiveSystemNotifications,
+  assembleAssistantMessage,
+  blocksContent,
+  initStreamUsage,
+  toolCallFromParsed,
+  recoverLiteralInvokeToolCalls,
+  registeredToolNames,
+  clampThinkingLevel,
+} from '@x-otto/provider'
+import { extractProviderUsageFromHeaders } from './anthropic-usage'
+import type {
+  AssistantMessage,
+  Message,
+  Model,
+  ResolvedAuth,
+  StopReason,
+  StreamContext,
+  StreamEvent,
+  StreamOptions,
+  SystemPromptSegment,
+  CacheRetention,
+  ProviderStream,
+  StreamBlock,
+  StreamUsage,
+  TokenDerivedHeader,
+} from '@x-otto/provider'
+
+/**
+ * RFC-185 D3：日志改走宿主注入端口（`AnthropicProviderOptions.logger`），插件源码禁止
+ * `createLogger` 自建——esbuild bundle 会复制出宿主管不着的第二份 pino 单例，trace 级
+ * 直写 stderr 破坏 TUI（findings-backlog「TUI 残影回归」根因环 1/2）。缺省 = no-op
+ * （红线：绝不 fallback 到 createLogger）。
+ */
+import type { WireProtocolLogger } from '@x-otto/provider'
+
+const noopLogger: WireProtocolLogger = { debug: () => {}, info: () => {}, warn: () => {}, error: () => {} }
+
+export type AnthropicCredentialResolver = () => Promise<string | undefined>
+export type AnthropicAuthResolver = () => Promise<ResolvedAuth | undefined>
+export type AnthropicBaseUrlResolver = () => Promise<string | undefined>
+
+async function resolveBaseUrl(
+  modelBaseUrl: string,
+  resolver?: AnthropicBaseUrlResolver,
+): Promise<string> {
+  const envUrl = process.env['ANTHROPIC_BASE_URL']
+  if (envUrl) {
+    return envUrl
+  }
+  if (resolver) {
+    const authUrl = await resolver()
+    if (authUrl) {
+      return authUrl
+    }
+  }
+  return modelBaseUrl
+}
+
+export function toBudgetTokens(level: string, maxOutputTokens: number): number {
+  // RFC-235：Anthropic 是 token 预算型（非 effort 关键字）。otto 档位 → maxOutput 百分比预算。
+  // 词表对齐 Claude Code（去 minimal 加 max）：low 25% / medium 50% / high 75% / xhigh 90% / max 95%。
+  let budget: number
+  switch (level) {
+    case 'low':
+      budget = Math.floor(maxOutputTokens * 0.25)
+      break
+    case 'high':
+      budget = Math.floor(maxOutputTokens * 0.75)
+      break
+    case 'xhigh':
+      budget = Math.floor(maxOutputTokens * 0.9)
+      break
+    case 'max':
+      budget = Math.floor(maxOutputTokens * 0.95)
+      break
+    default:
+      budget = Math.floor(maxOutputTokens * 0.5)
+  }
+  return Math.min(Math.max(budget, 1024), maxOutputTokens - 1)
+}
+
+/** thinking 配置的两种输出形态（由 model.thinkingMode 声明决定）。 */
+export type ThinkingConfig =
+  | { type: 'enabled'; budget_tokens: number }
+  | { type: 'adaptive' }
+
+export function buildThinkingConfig(
+  level: string | undefined,
+  reasoning: boolean,
+  maxOutputTokens: number,
+  thinkingMode?: 'enabled' | 'adaptive',
+): ThinkingConfig | undefined {
+  if (!reasoning || !level) {
+    return undefined
+  }
+  if (thinkingMode === 'adaptive') {
+    return { type: 'adaptive' }
+  }
+  if (maxOutputTokens <= 1024) {
+    return undefined
+  }
+  return { type: 'enabled', budget_tokens: toBudgetTokens(level, maxOutputTokens) }
+}
+
+/** adaptive 模式的 effort 值映射（output_config.effort）。 */
+function toAdaptiveEffort(level: string): 'low' | 'medium' | 'high' {
+  switch (level) {
+    case 'low': return 'low'
+    case 'medium': return 'medium'
+    case 'high': return 'high'
+    case 'xhigh': return 'high'
+    case 'max': return 'high'
+    default: return 'medium'
+  }
+}
+
+const CACHE_CONTROL = { type: 'ephemeral' as const }
+const CACHE_CONTROL_1H = { type: 'ephemeral' as const, ttl: '1h' as const }
+
+/**
+ * cacheRetention 选档 → ephemeral 断点（含 TTL）：
+ * - 'none' → null（不放任何断点，调用方据此跳过）；
+ * - 'short' / 缺省 → 5 分钟 TTL；
+ * - 'long' → 1 小时 TTL（SDK 0.88 原生 ttl，GA、无需 beta 头）。
+ * 返回 null（而非 undefined）以便与「参数省略走 5m 默认」区分。
+ */
+export function cacheControlFor(
+  retention?: CacheRetention,
+): Anthropic.CacheControlEphemeral | null {
+  if (retention === 'none') {
+    return null
+  }
+  return retention === 'long' ? CACHE_CONTROL_1H : CACHE_CONTROL
+}
+
+/**
+ * 断点③——会话前缀尾：最后一条消息的最后一个 content block 挂 cache_control。
+ * 仅对安全的块类型（text/tool_result/image）标记；string content 先升格为 block 数组。
+ * cacheControl=null（retention 'none'）→ 不放断点。参数省略默认 5m（保留旧直调行为）。
+ */
+export function withMessageCacheBreakpoint(
+  messages: Anthropic.MessageParam[],
+  cacheControl: Anthropic.CacheControlEphemeral | null = CACHE_CONTROL,
+): Anthropic.MessageParam[] {
+  const last = messages[messages.length - 1]
+  if (!last || !cacheControl) {
+    return messages
+  }
+
+  if (typeof last.content === 'string') {
+    if (last.content.length === 0) {
+      return messages
+    }
+    last.content = [{ type: 'text', text: last.content, cache_control: cacheControl }]
+    return messages
+  }
+
+  const lastBlock = last.content[last.content.length - 1]
+  if (
+    lastBlock &&
+    (lastBlock.type === 'text' || lastBlock.type === 'tool_result' || lastBlock.type === 'image') &&
+    !(lastBlock.type === 'text' && lastBlock.text.length === 0)
+  ) {
+    lastBlock.cache_control = cacheControl
+  }
+  return messages
+}
+
+/**
+ * 断点④——system 稳定前缀尾（动态）：把 system 转为 text block 数组，
+ * 在「最后一个 stable 段」之后挂 cache_control。volatile 段（如 phase context）
+ * 照发但落在断点之后，不进缓存前缀——因此其逐轮变化不会击穿 system / messages 缓存。
+ *
+ * - segments 缺省（仅 string）：整串视作单一 stable 段，断点落在尾部 == 旧行为。
+ * - 全 volatile（无 stable 段）/ cacheControl=null（retention 'none'）：不挂断点。
+ * - 空内容：返回 undefined，调用方省略 system 字段。
+ * 参数省略默认 5m（保留旧直调行为）。
+ */
+export function buildSystemBlocks(
+  systemPrompt: string,
+  segments?: SystemPromptSegment[],
+  cacheControl: Anthropic.CacheControlEphemeral | null = CACHE_CONTROL,
+): Anthropic.TextBlockParam[] | undefined {
+  const source: SystemPromptSegment[] =
+    segments && segments.length > 0 ? segments : systemPrompt ? [{ text: systemPrompt }] : []
+
+  const blocks = source.filter((s) => s.text.length > 0)
+  if (blocks.length === 0) {
+    return undefined
+  }
+
+  let breakpoint = -1
+  if (cacheControl) {
+    for (const [i, seg] of blocks.entries()) {
+      if ((seg.cache ?? 'stable') === 'stable') {
+        breakpoint = i
+      }
+    }
+  }
+
+  return blocks.map((seg, i) => ({
+    type: 'text' as const,
+    text: seg.text,
+    ...(i === breakpoint && cacheControl ? { cache_control: cacheControl } : {}),
+  }))
+}
+
+/**
+ * RFC-144 M2：mid-conversation system message 模型能力检测——据 Anthropic 官方文档
+ * （docs.anthropic.com/en/docs/build-with-claude/mid-conversation-system-messages，
+ * 2026-07 核实）"This feature is available on Claude Opus 4.8 only"，且不支持 Amazon
+ * Bedrock / Google Cloud（本函数只判模型本身，不判部署平台——otto 当前只走 Claude API
+ * 直连，平台判定不在范围内）。M0 已用真实 API 调用验证 `anthropic/claude-opus-4-8`
+ * 支持该特性（见 RFC-144 milestone M0 执行记录）。
+ *
+ * 不支持的模型走降级路径（决策 1 已述：`role:'user'` + 显式文本前缀），由调用方
+ * （`buildAnthropicMessages` 的 system_notification 分支）据此结果切换序列化形态。
+ */
+export function supportsMidConversationSystemMessage(model: Model): boolean {
+  return model.id === 'anthropic/claude-opus-4-8'
+}
+
+/**
+ * Anthropic 要求 `tool_use.id` / `tool_result.tool_use_id` 匹配 `^[a-zA-Z0-9_-]+$`
+ * （见 400 报错 `String should match pattern '^[a-zA-Z0-9_-]+$'`）。会话历史里的
+ * tool_call id 可能由其它 provider/网关生成，含点号、冒号、斜杠或非 ASCII 字符（例如跨
+ * provider 续聊、代理层重写的 id），直接透传就会被 Anthropic 拒绝整轮请求。
+ *
+ * 这里在 wire 边界做**确定性**清洗：合法 id 原样返回；非法 id 用其 sha256 摘要派生一个
+ * 稳定的合规 id。关键性质是纯函数——同一输入永远映射到同一输出，因此 assistant 的
+ * `tool_use.id` 与其配对的 `tool_result.tool_use_id` 各自独立清洗后仍然相等，roundtrip
+ * 配对不被破坏（不需要跨消息共享映射表）。
+ */
+const VALID_TOOL_USE_ID = /^[a-zA-Z0-9_-]+$/
+
+export function sanitizeToolUseId(id: string): string {
+  if (id.length > 0 && VALID_TOOL_USE_ID.test(id)) {
+    return id
+  }
+  return `toolu_x_${createHash('sha256').update(id).digest('hex').slice(0, 32)}`
+}
+
+/**
+ * `Message[]` → Anthropic `MessageParam[]`。
+ *
+ * `model` 可选（缺省走降级路径，见 `supportsMidConversationSystemMessage`）——保持向后
+ * 兼容：既有调用方（如未来新增的测试/工具）不传 model 时不会因新增必填参数而破坏编译。
+ *
+ * SDK 类型滞后说明（RFC-144 M2）：`@anthropic-ai/sdk@0.88.0` 的 `MessageParam.role` 类型声明
+ * 仅 `'user' | 'assistant'`，但 Anthropic 官方文档明确 API 本身接受 `{role:'system', ...}`
+ * 出现在 messages 数组中（M0 已用真实 API 调用验证）——这是 SDK 类型声明滞后于实际 API
+ * 能力的已知情况，用 `as Anthropic.MessageParam` 类型断言绕过，不代表真实类型契约。
+ */
+export function buildAnthropicMessages(messages: Message[], model?: Model): Anthropic.MessageParam[] {
+  const result: Anthropic.MessageParam[] = []
+  const nativeSystemMessageSupported = model ? supportsMidConversationSystemMessage(model) : false
+
+  // 2026-07 修正：Anthropic 官方约束"Consecutive system messages are not allowed"——原生
+  // 路径必须先把相邻的 system_notification 合并为一条，否则多个 lifecycleAsync 工具同轮
+  // 完成时会产出连续 system 消息，被 API 拒绝（400）。降级路径（role:'user'）不受此限制，
+  // 不合并（各自独立 user 消息，Anthropic 对连续 user 无限制）。
+  const normalized = nativeSystemMessageSupported
+    ? mergeConsecutiveSystemNotifications(messages)
+    : messages
+
+  // RFC-144 M2：放置规则断言——只有原生走 mid-conversation system message 的路径才受
+  // Anthropic 官方放置约束限制（降级路径 role:'user' 无此约束，断言在此处跑纯粹是
+  // 因为该模型能力已知支持，检查值得做；不支持的模型走断言意义不大但跑一次无害）。
+  // 对合并后的序列断言——合并已消除"连续 system_notification"这一类曾经的假阳性源。
+  assertSystemNotificationPlacement(normalized)
+
+  for (const msg of sanitizeToolRoundtrips(normalized)) {
+    if (msg.role === 'user') {
+      if (typeof msg.content === 'string') {
+        result.push({ role: 'user', content: msg.content })
+      } else {
+        const content: Array<Anthropic.TextBlockParam | Anthropic.ImageBlockParam> = []
+
+        for (const part of msg.content) {
+          if (part.type === 'text') {
+            if (part.text.length > 0) {
+              content.push({ type: 'text', text: part.text })
+            }
+          } else if (part.type === 'image') {
+            const { base64, mediaType, valid } = normalizeImageData(part.source, part.mime)
+            if (valid) {
+              content.push({
+                type: 'image',
+                source: {
+                  type: 'base64',
+                  media_type: toAnthropicImageMime(mediaType, base64),
+                  data: base64,
+                },
+              })
+            } else {
+              content.push({ type: 'text', text: '[image omitted: corrupted or empty data]' })
+            }
+          }
+        }
+
+        if (content.length > 0) {
+          result.push({ role: 'user', content })
+        }
+      }
+    } else if (msg.role === 'assistant') {
+      const content: Anthropic.ContentBlockParam[] = []
+
+      for (const part of msg.content) {
+        if (part.type === 'thinking') {
+          content.push({
+            type: 'thinking',
+            thinking: part.text,
+            signature: part.signature ?? '',
+          } as Anthropic.ThinkingBlockParam)
+        } else if (part.type === 'text') {
+          if (part.text.trim()) {
+            content.push({ type: 'text', text: part.text })
+          }
+        } else if (part.type === 'tool_call') {
+          content.push({
+            type: 'tool_use',
+            id: sanitizeToolUseId(part.id),
+            name: part.name,
+            input: part.arguments,
+          })
+        }
+      }
+
+      if (content.length > 0) {
+        result.push({ role: 'assistant', content })
+      }
+    } else if (msg.role === 'tool_result') {
+      const toolContent: Array<Anthropic.TextBlockParam | Anthropic.ImageBlockParam> = []
+
+      for (const c of msg.content) {
+        if (c.type === 'text') {
+          if (c.text.length > 0) {
+            toolContent.push({ type: 'text', text: c.text })
+          }
+        } else if (c.type === 'image') {
+          const { base64, mediaType, valid } = normalizeImageData(c.source, c.mime)
+          if (valid) {
+            toolContent.push({
+              type: 'image',
+              source: {
+                type: 'base64',
+                media_type: toAnthropicImageMime(mediaType, base64),
+                data: base64,
+              },
+            })
+          } else {
+            toolContent.push({ type: 'text', text: '[image omitted: corrupted or empty data]' })
+          }
+        }
+      }
+
+      result.push({
+        role: 'user',
+        content: [
+          {
+            type: 'tool_result',
+            tool_use_id: sanitizeToolUseId(msg.toolCallId),
+            content: toolContent,
+            ...(msg.isError ? { is_error: true } : {}),
+          },
+        ],
+      })
+    } else if (msg.role === 'system_notification') {
+      // RFC-144 M2：lifecycleAsync 工具完成通知——支持原生特性的模型走 mid-conversation
+      // system message（结构化保留"运营方权威"语义）；不支持的模型降级为 role:'user' +
+      // 显式前缀（放置约束见函数头注释；追加时机天然满足"紧跟 tool_result 之后"，因为
+      // work-loop.ts 的落库时机固定在下一次 runTurn 之前的静默期，见 RFC-144 硬约束 5）。
+      if (nativeSystemMessageSupported) {
+        result.push({ role: 'system', content: msg.content } as unknown as Anthropic.MessageParam)
+      } else {
+        result.push({ role: 'user', content: degradedSystemNotificationText(msg.content) })
+      }
+    }
+  }
+
+  // RFC-144 M2 补充修复（2026-07）：Anthropic mid-conversation system message 放置约束
+  // 的第二半（后继约束）——system 消息必须是数组末尾或紧接一个 assistant turn。
+  // assertSystemNotificationPlacement 在内部层面已检测到此违规并 warn，但 fail-soft 不阻断——
+  // 原生支持 mid-conversation system message 的模型仍可能在 wire 格式中产生
+  // [...assistant, system, user, ...] 这类违规序列（当 lifecycleAsync 工具在上一轮模型
+  // 响应后才完成、紧接着用户发送了新消息时），被 Anthropic 400 拒绝。
+  // 修复：对 wire 结果做一次后扫描，将放置违规的 system 消息降级为 role:'user' + 前缀
+  // （与此前非原生模型的降级路径同一序列化形态，不引入新格式）。
+  if (nativeSystemMessageSupported) {
+    for (let i = 0; i < result.length; i++) {
+      // SDK 的 MessageParam.role 类型声明仅 'user'|'assistant'，但实际 wire 中可能有
+      // 'system'（Anthropic SDK 类型滞后于 API 能力，同 buildAnthropicMessages 内
+      // push 时的 as unknown as MessageParam 注释）。
+      if ((result[i] as unknown as { role: string }).role === 'system') {
+        const next = result[i + 1]
+        if (next && next.role !== 'assistant') {
+          const text = typeof result[i]!.content === 'string' ? (result[i]!.content as string) : ''
+          result[i] = { role: 'user', content: degradedSystemNotificationText(text) }
+        }
+      }
+    }
+  }
+
+  return result
+}
+
+function mapStopReason(reason: string | null | undefined): StopReason {
+  switch (reason) {
+    case 'end_turn':
+      return 'end_turn'
+    case 'max_tokens':
+      return 'max_tokens'
+    case 'tool_use':
+      return 'tool_use'
+    case 'stop_sequence':
+      return 'stop_sequence'
+    case 'refusal':
+      return 'refusal'
+    default:
+      return 'end_turn'
+  }
+}
+
+interface AnthropicStreamState extends StreamUsage {
+  model: string
+  blocks: Map<number, StreamBlock>
+  stopReason: StopReason
+}
+
+function initStreamState(modelId: string): AnthropicStreamState {
+  return {
+    ...initStreamUsage(),
+    model: modelId,
+    blocks: new Map(),
+    stopReason: 'end_turn',
+  }
+}
+
+function buildAssistantMessage(state: AnthropicStreamState, final = false): AssistantMessage {
+  return assembleAssistantMessage(
+    { api: 'anthropic-messages', provider: 'anthropic', model: state.model },
+    blocksContent(state.blocks, final),
+    state,
+    state.stopReason,
+  )
+}
+
+function dispatchStreamEvent(
+  event: Anthropic.MessageStreamEvent,
+  state: AnthropicStreamState,
+): StreamEvent[] {
+  switch (event.type) {
+    case 'message_start': {
+      const u = event.message.usage
+      state.inputTokens = u.input_tokens
+      state.outputTokens = u.output_tokens
+      if (u.cache_read_input_tokens != null) {
+        state.cacheReadTokens = u.cache_read_input_tokens
+      }
+      if (u.cache_creation_input_tokens != null) {
+        state.cacheWriteTokens = u.cache_creation_input_tokens
+      }
+      return []
+    }
+
+    case 'content_block_start': {
+      const index = event.index
+      const block = event.content_block
+
+      if (block.type === 'text') {
+        state.blocks.set(index, { kind: 'text', text: '' })
+        return [{ type: 'text_start', index, partial: buildAssistantMessage(state) }]
+      } else if (block.type === 'thinking') {
+        state.blocks.set(index, { kind: 'thinking', text: '', signature: '' })
+        return [{ type: 'thinking_start', index, partial: buildAssistantMessage(state) }]
+      } else if (block.type === 'tool_use') {
+        state.blocks.set(index, {
+          kind: 'tool_call',
+          id: block.id,
+          name: block.name,
+          argumentsJson: '',
+        })
+        return [{ type: 'tool_call_start', index, partial: buildAssistantMessage(state) }]
+      }
+      return []
+    }
+
+    case 'content_block_delta': {
+      const index = event.index
+      const delta = event.delta
+      const block = state.blocks.get(index)
+
+      if (delta.type === 'text_delta' && block?.kind === 'text') {
+        block.text += delta.text
+        return [{
+          type: 'text_delta',
+          index,
+          delta: delta.text,
+          partial: buildAssistantMessage(state),
+        }]
+      } else if (delta.type === 'thinking_delta' && block?.kind === 'thinking') {
+        block.text += delta.thinking
+        return [{
+          type: 'thinking_delta',
+          index,
+          delta: delta.thinking,
+          partial: buildAssistantMessage(state),
+        }]
+      } else if (delta.type === 'signature_delta' && block?.kind === 'thinking') {
+        block.signature = (block.signature ?? '') + delta.signature
+        return []
+      } else if (delta.type === 'input_json_delta' && block?.kind === 'tool_call') {
+        block.argumentsJson += delta.partial_json
+        return [{
+          type: 'tool_call_delta',
+          index,
+          delta: delta.partial_json,
+          partial: buildAssistantMessage(state),
+        }]
+      }
+      return []
+    }
+
+    case 'content_block_stop': {
+      const index = event.index
+      const block = state.blocks.get(index)
+
+      if (block?.kind === 'text') {
+        return [{
+          type: 'text_end',
+          index,
+          content: block.text,
+          partial: buildAssistantMessage(state),
+        }]
+      } else if (block?.kind === 'thinking') {
+        return [{
+          type: 'thinking_end',
+          index,
+          content: block.text,
+          partial: buildAssistantMessage(state),
+        }]
+      } else if (block?.kind === 'tool_call') {
+        return [{
+          type: 'tool_call_end',
+          index,
+          toolCall: toolCallFromParsed(block.id, block.name, block.argumentsJson),
+          partial: buildAssistantMessage(state),
+        }]
+      }
+      return []
+    }
+
+    case 'message_delta': {
+      state.outputTokens = event.usage.output_tokens
+      // RFC-019 修复：message_delta 的 usage 是累积快照，input/cache 字段在服务端工具
+      // （web_search/code_execution 等）产出后追加到 prompt 时会重新下发且与 message_start
+      // 不同（官方 streaming 文档 web_search 示例：input_tokens 2679→10682）。
+      // 官方 SDK 自身的 MessageStream 累积器（accumulateMessage）对这三个字段做同款的
+      // "非 null 才覆盖"合并——此前仅取 message_start 快照会在服务端工具场景下把
+      // inputTokens/cacheReadTokens/cacheWriteTokens 钉死在过时值，连带 R1 命中率算错。
+      if (event.usage.input_tokens != null) {
+        state.inputTokens = event.usage.input_tokens
+      }
+      if (event.usage.cache_creation_input_tokens != null) {
+        state.cacheWriteTokens = event.usage.cache_creation_input_tokens
+      }
+      if (event.usage.cache_read_input_tokens != null) {
+        state.cacheReadTokens = event.usage.cache_read_input_tokens
+      }
+      state.stopReason = mapStopReason(event.delta.stop_reason)
+      return []
+    }
+
+    case 'message_stop':
+      return []
+  }
+}
+
+/**
+ * 请求定制点入参（RFC-140 D-copilot-spoof-split：厂商专属行为下沉插件）。
+ * `auth` 供定制器判断鉴权模式（如"仅 OAuth 模式才定制"）；`sessionId` 是本
+ * provider 实例进程内稳定的会话标识（同一实例每次请求复用同一个值）。
+ */
+export interface AnthropicRequestCustomizeInput {
+  auth: ResolvedAuth
+  sessionId: string
+}
+
+/**
+ * system 文本块的最小结构类型（有意不用 `Anthropic.TextBlockParam` SDK 具体类型）：
+ * 定制器的宿主实现方（如 `packages/coding/src/plugin/`）不该被迫依赖 `@anthropic-ai/sdk`
+ * 只为了满足一个类型签名——两者结构兼容（本类型字段是 `Anthropic.TextBlockParam` 的子集），
+ * 调用方传入/接收 SDK 真实类型的值时无需转换，TypeScript 结构化类型系统天然兼容。
+ */
+export interface AnthropicSystemTextBlock {
+  type: 'text'
+  text: string
+  cache_control?: unknown
+}
+
+/** 定制点可覆盖的三个请求维度——与真实 SDK 调用形状对齐，均可选、缺省不改变默认行为。 */
+export interface AnthropicRequestCustomization {
+  /** 附加/覆盖的 SDK 客户端默认请求头（如身份伪装头）。 */
+  defaultHeaders?: Record<string, string>
+  /** system 数组变换（如插入身份前缀块）；接收当前 blocks，返回替换后的 blocks。 */
+  transformSystemBlocks?: (
+    blocks: AnthropicSystemTextBlock[] | undefined,
+  ) => AnthropicSystemTextBlock[] | undefined
+  /** 附加的 body.metadata 字段（如 user_id 结构）。 */
+  metadata?: Record<string, unknown>
+}
+
+export interface AnthropicProviderOptions {
+  resolveKey?: AnthropicCredentialResolver
+  resolveAuth?: AnthropicAuthResolver
+  resolveBaseUrl?: AnthropicBaseUrlResolver
+  /**
+   * 请求定制点（RFC-140 D-copilot-spoof-split，取代此前的 `enableClaudeCodeSpoof` 布尔开关）：
+   * `createAnthropicProvider` 是**任意**声明 `wireApi: 'anthropic-messages'` 的插件共用的
+   * 通用协议工厂（`provider-loader.ts` `buildFactory`）——本文件不认识"Claude Code"这个
+   * 具体厂商概念，只暴露一个通用回调，由调用方（插件）决定要不要、如何定制请求（伪装
+   * 身份头/system 前缀/metadata，或其他厂商特定需求）。
+   *
+   * `extensions/plugin-anthropic` 通过此参数注入 Claude Code 客户端伪装逻辑（绕 Anthropic
+   * 对订阅 OAuth token 的客户端分类器限流）——伪装成官方 Claude Code CLI 这一行为只对
+   * "连接 api.anthropic.com、用 Claude Pro/Max 订阅 OAuth token"这一具体场景成立且必要。
+   * 第三方 `anthropic-messages` 兼容端点（代理网关、企业自建实例等）不传本参数，默认零定制、
+   * 零伪装——不再需要显式传 `false` 来"关闭"（本就没有内置的厂商专属行为可关）。
+   */
+  customizeRequest?: (input: AnthropicRequestCustomizeInput) => AnthropicRequestCustomization
+  /**
+   * RFC-270 缺陷 1（P0）：静态额外 headers（如 manifest 声明的 `x-llm-appcode` 企业网关
+   * 路由标识）。此前本 Options **完全没有这个字段**——`plugin.ts` 的 adapter 也因此未透传
+   * `input.headers`，声明式 provider 给本协议写的 headers 被静默丢弃且不报错。该缺陷长期
+   * 未被发现，是因为唯一的真实用例 `anthropic-version` 恰好被 @anthropic-ai/sdk 自身硬编码
+   * 补上（`client.js` buildRequest），掩盖了丢弃。
+   */
+  headers?: Record<string, string>
+  /** RFC-122 D3：JWT claim 派生 headers（同缺陷 1，此前本协议未支持）。 */
+  tokenDerivedHeaders?: TokenDerivedHeader[]
+  /** RFC-270 D3：manifest 显式声明后，允许自定义头覆盖鉴权头（企业网关换鉴权）。 */
+  allowAuthHeaderOverride?: boolean
+  /** RFC-185 D3：宿主注入的日志端口，缺省 no-op（见文件头 noopLogger 注释）。 */
+  logger?: WireProtocolLogger
+}
+
+class AnthropicStream implements ProviderStream {
+  readonly id = 'anthropic-messages'
+  readonly displayName = 'Anthropic'
+
+  /**
+   * 进程内稳定的会话 id——供 `customizeRequest` 定制器使用（如订阅 OAuth 形状匹配的
+   * X-Claude-Code-Session-Id / metadata）。本文件不解读其含义，只透传给定制器。
+   */
+  private readonly requestSessionId = randomUUID()
+
+  constructor(
+    private readonly resolveCredential?: AnthropicCredentialResolver,
+    private readonly baseUrlResolver?: AnthropicBaseUrlResolver,
+    private readonly authResolver?: AnthropicAuthResolver,
+    /** 见 `AnthropicProviderOptions.customizeRequest` 注释。缺省 = 零定制。 */
+    private readonly customizeRequest?: (input: AnthropicRequestCustomizeInput) => AnthropicRequestCustomization,
+    private readonly logger: WireProtocolLogger = noopLogger,
+    /** 见 `AnthropicProviderOptions.headers`（RFC-270 缺陷 1 修复）。 */
+    private readonly staticHeaders?: Record<string, string>,
+    private readonly tokenDerivedHeaders?: TokenDerivedHeader[],
+    private readonly allowAuthHeaderOverride?: boolean,
+  ) {}
+
+  /**
+   * 统一鉴权解析（RFC-140 D5，`ProviderStream.resolveAuth`）：优先 resolveAuth（含
+   * mode/beta）；回退到旧的字符串 resolveKey（视为 api_key）；最后回退 ANTHROPIC_API_KEY env。
+   */
+  async resolveAuth(_model: Model): Promise<ResolvedAuth> {
+    if (this.authResolver) {
+      const auth = await this.authResolver()
+      if (auth?.token) {
+        return auth
+      }
+    }
+
+    if (this.resolveCredential) {
+      const key = await this.resolveCredential()
+      if (key) {
+        return { token: key, mode: 'api_key' }
+      }
+    }
+
+    const envKey = process.env['ANTHROPIC_API_KEY']
+    if (envKey) {
+      return { token: envKey, mode: 'api_key' }
+    }
+
+    throw new ProviderError(
+      'Missing Anthropic API key. Set ANTHROPIC_API_KEY or configure via auth file.',
+      { code: 'PROVIDER_AUTH_MISSING' },
+    )
+  }
+
+  private async buildRequestParams(
+    model: Model,
+    context: StreamContext,
+    auth: ResolvedAuth,
+  ): Promise<{ client: Anthropic; requestParams: Anthropic.MessageStreamParams; baseURL: string }> {
+    const baseURL = await resolveBaseUrl(model.baseUrl, this.baseUrlResolver)
+    // RFC-140 D-copilot-spoof-split：本文件不再判断"是否 oauth 才伪装"——那是具体厂商
+    // （如 plugin-anthropic 的 Claude Code 伪装）的业务逻辑，交给 customizeRequest 定制器
+    // 自行按 input.auth.mode 判断要不要返回定制内容。未提供定制器 = 零调用零开销。
+    const customization = this.customizeRequest?.({ auth, sessionId: this.requestSessionId })
+
+    /*
+     * RFC-270 缺陷 1（P0）+ D1：统一头管线，**filter-output 形态**。
+     *
+     * 本协议经 @anthropic-ai/sdk 出站，鉴权由 SDK 构造参数（apiKey/authToken）承担、不进
+     * 管线——因此不传 `auth` 档。鉴权保护必须靠"交给 SDK 前剥离"而非"最后写入"：SDK 内部
+     * 合并链是 `内部默认 < authHeaders < defaultHeaders < options.headers`（后写覆盖，见
+     * @anthropic-ai/sdk internal/headers.js），otto 交给它的 defaultHeaders 排在 SDK 鉴权头
+     * **之后**、能覆盖它，write-last 在这条路径物理不成立。管线在 `auth` 缺省时照常执行
+     * ②③④ 档的鉴权族剥离，正是为此。
+     *
+     * 两个 auth 分支统一走同一份头（此前仅 oauth 分支传 defaultHeaders，api_key 分支完全
+     * 不传——即使定制器返回了头也会丢，是缺陷 1 的次生项）。
+     */
+    const defaultHeaders = buildRequestHeaders({
+      staticHeaders: this.staticHeaders,
+      tokenDerived: this.tokenDerivedHeaders?.length
+        ? { headers: this.tokenDerivedHeaders, token: auth.token }
+        : undefined,
+      customized: customization?.defaultHeaders,
+      allowAuthHeaderOverride: this.allowAuthHeaderOverride,
+      logger: this.logger,
+      diagnosticLabel: `anthropic-messages:${model.provider}`,
+    })
+    const headerOptions = Object.keys(defaultHeaders).length > 0 ? { defaultHeaders } : {}
+
+    // 代理接线：**刻意不在这里传 `fetchOptions.dispatcher`**（RFC-288 D0a 修订，重要事项规则 11）。
+    //
+    // 本仓的代理由 `installGlobalProxyDispatcher`（`@x-otto/shared`）经 undici 全局 dispatcher
+    // 统一接管，Anthropic SDK 内部的 `fetch` 自动经代理，无需此处显式传参——已在真实 Node
+    // 运行时实测确认（非仅测试环境）。
+    //
+    // 为什么不能传：Node 22 内置 fetch 用的是 Node 自带的 undici **6.23**
+    // （`process.versions.undici`），而 `@x-otto/shared` 依赖的是 undici **8.7**。
+    // `createDispatcher()` 造出的是 8.7 的 `ProxyAgent` 实例，把它交给内置 fetch 会抛
+    // `UND_ERR_INVALID_ARG: invalid onRequestStart method`——**配了代理的用户会直接请求失败**，
+    // 比"不走代理"更糟。`setGlobalDispatcher` 之所以能跨版本工作，是因为它写的是 Node 的
+    // `globalThis` 共享槽；per-request 的 `dispatcher` 走的却是严格实例校验，两者不同路。
+    //
+    // 若将来要恢复 per-client 接线，必须先让 shared 的 undici 与 Node 内置版本对齐，
+    // 并补一条**真发请求**的回归（只断言构造参数抓不到这类失败——这正是本缺陷曾溜过 M0 的原因）。
+    const client =
+      auth.mode === 'oauth'
+        ? new Anthropic({
+            apiKey: null,
+            authToken: auth.token,
+            baseURL,
+            maxRetries: 0,
+            ...headerOptions,
+          })
+        : new Anthropic({
+            apiKey: auth.token,
+            baseURL,
+            maxRetries: 0,
+            ...headerOptions,
+          })
+
+    const cacheControl = cacheControlFor(context.cacheRetention)
+
+    const tools: Anthropic.Tool[] = context.tools
+      ? context.tools.map((t) => ({
+          name: t.name,
+          description: t.description,
+          input_schema: (t.parameters.toJSONSchema?.() ?? {}) as Anthropic.Tool['input_schema'],
+        }))
+      : []
+    const lastTool = tools[tools.length - 1]
+    if (lastTool && cacheControl) {
+      lastTool.cache_control = cacheControl
+    }
+
+    const effectiveMaxTokens = context.maxTokens ?? model.maxOutputTokens
+    const thinkingConfig = buildThinkingConfig(
+      // RFC-235：按模型声明的 thinkingLevels 降级后再算预算（clamp 单一真源）。
+      context.thinkingLevel ? clampThinkingLevel(context.thinkingLevel, model.thinkingLevels) : undefined,
+      model.reasoning,
+      effectiveMaxTokens,
+      model.thinkingMode,
+    )
+
+    let systemBlocks = buildSystemBlocks(
+      context.systemPrompt,
+      context.systemPromptSegments,
+      cacheControl,
+    )
+    if (customization?.transformSystemBlocks) {
+      // 定制点契约刻意用 AnthropicSystemTextBlock（SDK 无关最小结构）而非 Anthropic.TextBlockParam，
+      // 使宿主实现方（如 coding/plugin/）不必依赖 @anthropic-ai/sdk。两者结构兼容（前者是后者的
+      // 字段子集），此处是唯一需要接回 SDK 具体类型的边界点。
+      systemBlocks = customization.transformSystemBlocks(systemBlocks) as Anthropic.TextBlockParam[] | undefined
+    }
+
+    const requestParams: Anthropic.MessageStreamParams = {
+      model: model.name,
+      max_tokens: effectiveMaxTokens,
+      ...(systemBlocks ? { system: systemBlocks } : {}),
+      messages: withMessageCacheBreakpoint(buildAnthropicMessages(context.messages, model), cacheControl),
+      ...(tools.length > 0 ? { tools } : {}),
+      ...(context.temperature !== undefined && !model.reasoning
+        ? { temperature: context.temperature }
+        : {}),
+      ...(thinkingConfig ? { thinking: thinkingConfig } : {}),
+      // adaptive 模式：网关要求顶层 output_config.effort 控制推理投入（与 thinking.type.adaptive 配对）。
+      ...(thinkingConfig?.type === 'adaptive' && context.thinkingLevel
+        ? { output_config: { effort: toAdaptiveEffort(clampThinkingLevel(context.thinkingLevel, model.thinkingLevels)) } }
+        : {}),
+      ...(customization?.metadata ? { metadata: customization.metadata } : {}),
+    }
+
+    return { client, requestParams, baseURL }
+  }
+
+  async *converse(
+    model: Model,
+    context: StreamContext,
+    options: StreamOptions,
+    signal: AbortSignal,
+  ): AsyncIterable<StreamEvent> {
+    const auth = await this.resolveAuth(model)
+    const { client, requestParams, baseURL } = await this.buildRequestParams(model, context, auth)
+
+    const state = initStreamState(model.id)
+    let started = false
+
+    this.logger.debug({ model: model.id, baseURL }, 'Starting Anthropic stream')
+
+    try {
+      const stream = client.messages.stream(requestParams, {
+        signal,
+        ...(options.timeout !== undefined ? { timeout: options.timeout } : {}),
+      })
+
+      for await (const event of stream) {
+        if (!started) {
+          started = true
+          yield { type: 'start', partial: buildAssistantMessage(state) }
+        }
+        yield* dispatchStreamEvent(event, state)
+      }
+
+      // 成功路径 usage 快照：仅 Anthropic OAuth 订阅计划的响应带 anthropic-ratelimit-unified-*
+      // 头族（API key 走标准 RPM/TPM，headers 里没有该头族 → extractProviderUsageFromHeaders
+      // 返回 null，天然实现"API key 不显示"）。stream.response 在流正常结束后仍可访问
+      // （SDK MessageStream #response 一经 _connected() 设置不再清空，见调研）。
+      const providerUsage = extractProviderUsageFromHeaders(stream.response?.headers)
+      const doneMessage = buildAssistantMessage(state, true)
+      yield {
+        type: 'done',
+        reason: doneMessage.stopReason,
+        // RFC-232（终局修正）：跨 wire 协议救回"模型把工具调用写成字面文本 XML"违约响应
+        // （见 stream-state.ts recoverLiteralInvokeToolCalls 头注释）。判据内部短路，
+        // 无违约态时零开销（引用相等，不构造新对象）。
+        message: recoverLiteralInvokeToolCalls(doneMessage, registeredToolNames(context.tools)),
+        providerUsage,
+      }
+    } catch (error) {
+      if (error instanceof Anthropic.APIError) {
+        yield {
+          type: 'error',
+          error: new ProviderError(`Anthropic API error ${error.status}: ${error.message}`, {
+            code: 'PROVIDER_API_ERROR',
+            cause: error,
+            // 把 SDK 的 HTTP status/headers 转成 ProviderError 的 typed 字段
+            // （CodedError.status/headers），使 classifyStreamError 直接读 typed、不必沿 cause 链下挖。
+            status: error.status,
+            headers: error.headers,
+            // SDK 解析响应体 `error.error.type`（如 "authentication_error"/"permission_error"）
+            // 到 APIError.type——机器可读的失效根因分类，供 stream.auth-failed 记录"为什么失效"
+            // （而不只是"401 unauthorized"这种笼统文案，见 CodedError.errorType 注释）。
+            errorType: error.type ?? undefined,
+          }),
+        }
+      } else if (error instanceof Error) {
+        yield { type: 'error', error }
+      } else {
+        yield {
+          type: 'error',
+          error: new ProviderError('Unknown Anthropic stream error', {
+            code: 'PROVIDER_STREAM_ERROR',
+          }),
+        }
+      }
+    }
+  }
+}
+
+export function createAnthropicProvider(options: AnthropicProviderOptions = {}): ProviderStream {
+  return new AnthropicStream(
+    options.resolveKey,
+    options.resolveBaseUrl,
+    options.resolveAuth,
+    options.customizeRequest,
+    options.logger,
+    options.headers,
+    options.tokenDerivedHeaders,
+    options.allowAuthHeaderOverride,
+  )
+}