@twinsearth/dsh-master 0.0.0-stage → 3.2.8

package/worker/index.ts

@@ -0,0 +1,334 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+
+/**
+ * dsh-superagent-worker preset 的 Cordis 入口（v3.2.3）。
+ *
+ * 运行在分身 VM 内。Router 派发时注入 `DSH_MASTER_TICKET`，同时注入：
+ *   * `DSH_MASTER_STREAM_URL` / `DSH_MASTER_STREAM_TOKEN`：Worker→Router 实时事件通道；
+ * fork 宿主加载本 preset 后会自动跑一次 Agent Loop（可用 DSH_MASTER_WORKER_AUTORUN=0 关闭）。
+ *
+ * 角色安全：只允许 `DSH_FANG_ROLE=fork` 且非元宝运行态（`DSH_FANG_ESSENCE!=1`）执行；
+ * 在母体/元主即使误装也不会运行 Worker。
+ */
+
+import type { TicketPayload, WorkerDeps, WorkerResult, WorkerSink } from './types.ts'
+import { SuperAgentWorker, normalizeTicket } from './agent-loop.ts'
+import { createSandboxTools } from './tools.ts'
+import { createHttpLlmClient } from './llm-http.ts'
+import { createHttpSink } from './sink-http.ts'
+import { createGithubPrClient } from './github-pr.ts'
+
+export const name = 'dsh-master-superagent-loop'
+// 依赖房主核心服务：Cordis 会等 dshMaster 就绪后再 apply，保证本行能注册到核心。
+export const inject = ['dshMaster']
+
+export interface CordisLoggerLike {
+  info?(message: string): void
+  warn?(message: string): void
+  error?(message: string): void
+}
+
+export interface CordisLike {
+  logger?: CordisLoggerLike
+  llm?: { chat(request: unknown): Promise<unknown> }
+  tools?: { register?(tool: unknown): unknown; getSchemas?(names: string[]): unknown[]; execute?(name: string, args: unknown): unknown }
+  get?(name: string): unknown
+  on?(event: string, handler: (payload: unknown) => void): unknown
+  emit?(event: string, payload: unknown): void
+  effect?(dispose: () => void): void
+}
+
+export interface WorkerEnvOptions {
+  env?: Record<string, string | undefined>
+  workspace?: string
+  model?: string
+  llm?: WorkerDeps['llm']
+  limits?: WorkerDeps['limits']
+  sink?: WorkerSink
+}
+
+let autoStartedTicket = ''
+
+function envOf(options: WorkerEnvOptions): Record<string, string | undefined> {
+  return options.env ?? process.env
+}
+
+/**
+ * VM 隔离证明：只有明确声明 `DSH_MASTER_VM_ISOLATION=attested` 才允许 Shell（P0-2 fail-closed）。
+ * 瓮城在已证明隔离的分身里注入该变量；普通进程不会自动获得。
+ */
+export function vmIsolationAttested(env: Record<string, string | undefined>): boolean {
+  return String(env.DSH_MASTER_VM_ISOLATION ?? '').trim().toLowerCase() === 'attested'
+}
+
+function prClientFromEnv(env: Record<string, string | undefined>) {
+  const token = String(env.DSH_MASTER_GITHUB_TOKEN ?? '').trim()
+  const repo = String(env.DSH_MASTER_GITHUB_REPO ?? '').trim()
+  if (!token || !repo) return undefined
+  return createGithubPrClient({ token, repo, apiBase: env.DSH_MASTER_GITHUB_API_BASE, baseBranch: env.DSH_MASTER_GITHUB_BASE })
+}
+
+function consoleLogger(): WorkerDeps['logger'] {
+  return {
+    info: (message: string) => { process.stderr.write(message + '\n') },
+    warn: (message: string) => { process.stderr.write('[warn] ' + message + '\n') },
+    error: (message: string) => { process.stderr.write('[error] ' + message + '\n') },
+  }
+}
+
+/** 收集需要从日志/步骤中抹掉的具体 secret 值（key 只在 Worker 进程内使用）。 */
+export function secretValuesOf(env: Record<string, string | undefined>): string[] {
+  // v3.2.5：不只列白名单——任何形如 *_API_KEY / *_TOKEN / *_SECRET / *_PASSWORD 的长值
+  // 都进脱敏表，避免新增凭据（DSH_MASTER_LLM_API_KEY / DSH_MASTER_GITHUB_TOKEN）漏脱敏。
+  const NAMED = [
+    'WORKER_LLM_API_KEY',
+    'DSH_MASTER_LLM_API_KEY',
+    'DSH_MASTER_STREAM_TOKEN',
+    'DSH_MASTER_GITHUB_TOKEN',
+    'DSH_ADAPTER_TOKEN',
+  ]
+  const values = new Set<string>()
+  for (const key of NAMED) {
+    const value = env[key]
+    if (typeof value === 'string' && value.length >= 8) values.add(value)
+  }
+  for (const [key, value] of Object.entries(env)) {
+    if (typeof value !== 'string' || value.length < 8) continue
+    if (!/(_API_KEY|_APIKEY|_TOKEN|_SECRET|_PASSWORD)$/i.test(key)) continue
+    values.add(value)
+  }
+  return [...values]
+}
+
+/** 从环境变量构造 Worker 依赖；缺 Ticket/LLM 时抛可读错误。 */
+export function buildWorkerDeps(options: WorkerEnvOptions = {}): { ticket: TicketPayload; deps: WorkerDeps } {
+  const env = envOf(options)
+  const raw = env.DSH_MASTER_TICKET
+  if (!raw) throw new Error('DSH_MASTER_TICKET is required to start a SuperAgent Worker')
+  let parsed: unknown
+  try {
+    parsed = parseTicketEnv(raw)
+  } catch {
+    throw new Error('DSH_MASTER_TICKET is not valid JSON')
+  }
+  const ticket = normalizeTicket(parsed as Record<string, unknown>)
+  const workspace = String(options.workspace ?? env.WORKER_WORKSPACE ?? env.DSH_MASTER_WORKSPACE ?? process.cwd())
+  const llm = options.llm ?? createHttpLlmClient({
+    baseUrl: String(env.WORKER_LLM_BASE_URL ?? env.DSH_MASTER_LLM_BASE_URL ?? ''),
+    apiKey: env.WORKER_LLM_API_KEY ?? env.DSH_MASTER_LLM_API_KEY,
+    model: String(options.model ?? env.WORKER_LLM_MODEL ?? env.DSH_MASTER_LLM_MODEL ?? 'deepseek-chat'),
+    timeoutMs: Number(env.WORKER_LLM_TIMEOUT_MS ?? 120_000),
+  })
+  const githubToken = String(env.DSH_MASTER_GITHUB_TOKEN ?? '').trim()
+  const githubRepo = String(env.DSH_MASTER_GITHUB_REPO ?? '').trim()
+  const prClient = githubToken && githubRepo
+    ? createGithubPrClient({ token: githubToken, repo: githubRepo, apiBase: env.DSH_MASTER_GITHUB_API_BASE, baseBranch: env.DSH_MASTER_GITHUB_BASE })
+    : undefined
+  const tools = createSandboxTools({ workspace, mandate: ticket.mandate, prClient, vmIsolation: vmIsolationAttested(env) })
+  return {
+    ticket,
+    deps: {
+      llm,
+      tools,
+      workspace,
+      mandate: ticket.mandate,
+      logger: options.sink ? undefined : consoleLogger(),
+      sink: options.sink,
+      limits: options.limits,
+      model: String(options.model ?? env.WORKER_LLM_MODEL ?? '') || undefined,
+      redactValues: secretValuesOf(env),
+    },
+  }
+}
+
+function cordisSink(ctx: CordisLike): WorkerSink {
+  return {
+    log: (message: string) => {
+      try { ctx.logger?.info?.(message) } catch { /* ignore */ }
+      try { ctx.emit?.('superagent:log', { message, at: Date.now() }) } catch { /* ignore */ }
+    },
+    step: (step) => { try { ctx.emit?.('superagent:step', step) } catch { /* ignore */ } },
+    phase: (phase) => { try { ctx.emit?.('superagent:phase', { phase, at: Date.now() }) } catch { /* ignore */ } },
+    stream: (delta) => { try { ctx.emit?.('superagent:stream', delta) } catch { /* ignore */ } },
+  }
+}
+
+/** 组合 sink：Cordis 事件 + Router HTTP 实时通道（任一失败不影响另一个）。 */
+function composeSink(local: WorkerSink, remote: WorkerSink | null): WorkerSink {
+  if (!remote) return local
+  const wrap = <K extends keyof WorkerSink>(key: K) => {
+    const localFn = local[key]
+    const remoteFn = remote[key]
+    if (!localFn && !remoteFn) return undefined
+    return ((...args: Parameters<NonNullable<WorkerSink[K]>>) => {
+      try { (localFn as ((...a: unknown[]) => void) | undefined)?.(...args) } catch { /* ignore */ }
+      try { (remoteFn as ((...a: unknown[]) => void) | undefined)?.(...args) } catch { /* ignore */ }
+    }) as NonNullable<WorkerSink[K]>
+  }
+  return { log: wrap('log'), step: wrap('step'), phase: wrap('phase'), stream: wrap('stream') }
+}
+
+/** 归档真实 token 用量到 fork 内的 HarnessMM observe 服务；无该服务时不影响 Worker。 */
+export function recordWorkerCost(ctx: CordisLike, ticketId: string, result: WorkerResult): unknown {
+  try {
+    const cost = ctx.get?.('dshMasterCost') as { record?(input: Record<string, unknown>): unknown } | undefined
+    if (!cost || typeof cost.record !== 'function') return { ok: false, code: 'cost-service-unavailable' }
+    const tokens = Math.max(0, Number(result.tokenUsage ?? 0) || 0)
+    // 尚未接入 EGD/GDR 优化，优化前后相等，绝不虚报节省；只记录真实 token 与成功率。
+    return cost.record({ taskId: ticketId, baselineTokens: tokens, optimizedTokens: tokens, success: result.ok === true })
+  } catch (error) {
+    return { ok: false, code: 'cost-record-failed', error: String(error instanceof Error ? error.message : error) }
+  }
+}
+
+/** 跑一次 Worker（不依赖 Cordis；供 main.ts / 宿主/测试复用）。 */
+export async function runWorker(ticket: TicketPayload, deps: WorkerDeps): Promise<WorkerResult> {
+  const worker = new SuperAgentWorker(deps)
+  return await worker.execute(ticket)
+}
+
+/** 宿主服务查找（房主核心存在时才注册子插件；独立 fork 无核心也能跑循环）。 */
+function masterOf(ctx: CordisLike): { registerSubplugin?: (descriptor: Record<string, unknown>) => unknown } | null {
+  try {
+    const candidate = typeof (ctx as { get?: (name: string) => unknown }).get === 'function'
+      ? (ctx as { get: (name: string) => unknown }).get('dshMaster')
+      : null
+    return candidate && typeof candidate === 'object' ? candidate as never : null
+  } catch {
+    return null
+  }
+}
+
+/** bundle 行的空字符串视为未配置（否则会覆盖 env 默认值）。 */
+function optionalOf(value: unknown): string | undefined {
+  const text = String(value ?? '').trim()
+  return text ? text : undefined
+}
+
+/** 环境变量里的 Ticket JSON：剥离 BOM/空白后再解析（Windows 脚本写入常见 BOM）。 */
+export function parseTicketEnv(raw: string): unknown {
+  return JSON.parse(String(raw ?? '').replace(/^\uFEFF/, '').trim())
+}
+
+export interface Config {
+  /** bundle 行配置：`enabled: false` 时不自动执行（仍保留事件入口）。 */
+  enabled?: boolean
+  /** 是否在检测到 Ticket 后自动跑循环；默认 true（可用 DSH_MASTER_WORKER_AUTORUN=0 关闭）。 */
+  autorun?: boolean
+  /** 覆盖 LLM 模型名（默认取 env）。 */
+  model?: string
+  /** 覆盖工作区（默认取 env / cwd）。 */
+  workspace?: string
+}
+
+/**
+ * Cordis preset 入口：有 Ticket 的 fork 自动跑 Worker；没有 Ticket 时只等待事件。
+ * 返回 {ready, autoRun, reason} 便于宿主/测试检查。
+ */
+export function apply(ctx: CordisLike, config: Config = {}): { ready: boolean; autoRun: boolean; reason?: string } {
+  if (config && config.enabled === false) return { ready: false, autoRun: false, reason: 'disabled-by-config' }
+  const env = process.env
+  const raw = env.DSH_MASTER_TICKET
+  const emitError = (message: string, extra: Record<string, unknown> = {}) => {
+    try { ctx.logger?.error?.(message) } catch { /* ignore */ }
+    try { ctx.emit?.('superagent:worker:error', { error: message, ...extra }) } catch { /* ignore */ }
+  }
+
+  // 角色安全：Worker preset 只允许 fork（非元宝运行态）。与房主 ROLE_MATRIX 的
+  // master-superagent-loop 行一致，避免宿主状态把“跑过循环却显示未激活”。
+  const role = String(env.DSH_FANG_ROLE ?? '').trim()
+  const essence = String(env.DSH_FANG_ESSENCE ?? '') === '1' || String(env.DSH_FANG_TASK_ID ?? '').startsWith('rt-')
+  const effectiveRole = role === 'fork' ? (essence ? 'essence' : 'fork') : (essence ? 'essence' : (role || 'mother'))
+  if (effectiveRole !== 'fork') {
+    return { ready: false, autoRun: false, reason: `role-not-allowed:${effectiveRole}` }
+  }
+
+  // 向房主核心注册本行（核心存在时；重复注册不应打断 preset）。
+  try {
+    const master = masterOf(ctx)
+    if (master && typeof master.registerSubplugin === 'function') {
+      master.registerSubplugin({
+        id: 'superagent-loop',
+        name: 'dsh-master-superagent-loop',
+        capabilities: ['worker-agent-loop', 'llm-tool-loop', 'streaming-events', 'result-writeback'],
+        description: raw ? 'Worker Agent Loop 已接管工单（fork）' : 'Worker Agent Loop 就绪（等待工单）',
+      })
+    }
+  } catch { /* 已注册/无核心：不影响循环 */ }
+
+  if (!raw) {
+    // 普通 fork / 其他角色：只保留事件监听入口，不自动执行。
+    try {
+      const off = ctx.on?.('superagent:worker:start', (payload) => {
+        void (async () => {
+          const ticket = normalizeTicket(payload as Record<string, unknown>)
+          const { deps } = buildWorkerDeps({ sink: cordisSink(ctx) })
+          const result = await runWorker(ticket, deps)
+          try { ctx.emit?.('superagent:worker:done', { ticketId: ticket.ticketId, result }) } catch { /* ignore */ }
+        })().catch((error) => emitError(error instanceof Error ? error.message : String(error)))
+      })
+      if (typeof off === 'function') ctx.effect?.(off as () => void)
+    } catch { /* ignore */ }
+    return { ready: true, autoRun: false, reason: 'no-ticket' }
+  }
+
+  const autorun = config.autorun === false ? false : env.DSH_MASTER_WORKER_AUTORUN !== '0'
+  if (!autorun) return { ready: true, autoRun: false, reason: 'autorun-disabled' }
+
+  let ticket: TicketPayload
+  try {
+    ticket = normalizeTicket(parseTicketEnv(raw) as Record<string, unknown>)
+  } catch (error) {
+    emitError(`worker ticket invalid: ${error instanceof Error ? error.message : String(error)}`)
+    return { ready: false, autoRun: false, reason: 'ticket-invalid' }
+  }
+  if (autoStartedTicket === ticket.ticketId) return { ready: true, autoRun: false, reason: 'already-started' }
+  autoStartedTicket = ticket.ticketId
+
+  const remoteSink = (env.DSH_MASTER_STREAM_URL && env.DSH_MASTER_STREAM_TOKEN)
+    ? createHttpSink({
+        url: String(env.DSH_MASTER_STREAM_URL),
+        token: String(env.DSH_MASTER_STREAM_TOKEN),
+        ticketId: ticket.ticketId,
+        streamFlushMs: Number(optionalOf(env.DSH_MASTER_STREAM_FLUSH_MS)) || undefined,
+        log: (message) => { try { ctx.logger?.warn?.(message) } catch { /* ignore */ } },
+      })
+    : null
+  const sink = composeSink(cordisSink(ctx), remoteSink)
+
+  let deps: WorkerDeps
+  try {
+    deps = buildWorkerDeps({ sink, model: optionalOf(config.model), workspace: optionalOf(config.workspace) }).deps
+  } catch (error) {
+    autoStartedTicket = ''
+    emitError(`worker dependency failed: ${error instanceof Error ? error.message : String(error)}`, { ticketId: ticket.ticketId })
+    return { ready: false, autoRun: false, reason: 'deps-invalid' }
+  }
+
+  // v3.2.7（A 治根之二）：fork 的 Host 启动期会抢占 CPU，导致已经按 260ms 节奏到达的
+  // SSE 分片在 socket 里积压后一次性排空（前端只能看到"跳变"）。这里在进入循环前先让
+  // 宿主把插件加载/首帧渲染完成（默认 1200ms，可用 DSH_MASTER_WARMUP_MS 覆盖，0=关闭）。
+  const warmupMs = Math.max(0, Number(optionalOf(env.DSH_MASTER_WARMUP_MS) ?? 1200) || 0)
+  const warmup = warmupMs > 0 ? new Promise((resolve) => setTimeout(resolve, warmupMs)) : Promise.resolve()
+
+  void warmup
+    .then(() => runWorker(ticket, deps))
+    .then(async (result) => {
+      autoStartedTicket = ''
+      try { await remoteSink?.done(result) } catch { /* ignore */ }
+      try { await remoteSink?.close() } catch { /* ignore */ }
+      try { recordWorkerCost(ctx, ticket.ticketId, result) } catch { /* ignore */ }
+      try { ctx.emit?.('superagent:worker:done', { ticketId: ticket.ticketId, result }) } catch { /* ignore */ }
+      try {
+        ctx.logger?.info?.(`[worker] ${ticket.ticketId} ${result.ok ? 'done' : 'failed'} in ${result.elapsedMs}ms`)
+      } catch { /* ignore */ }
+    })
+    .catch((error) => {
+      autoStartedTicket = ''
+      emitError(error instanceof Error ? error.message : String(error), { ticketId: ticket.ticketId })
+    })
+  return { ready: true, autoRun: true }
+}
+
+export type { WorkerResult, WorkerDeps, TicketPayload }

package/worker/llm-http.ts

@@ -0,0 +1,359 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+
+/**
+ * OpenAI 兼容 Chat Completions 的 LLM 适配器（v3.2.2）。
+ *
+ * Worker 运行在分身 VM 内，通过环境变量拿到模型端点/凭据；本适配器不做任何
+ * 日志打印或错误回显中的 key 泄露。Provider 只负责“模型调用”，工具执行仍在
+ * Worker 本地（沙箱内）。
+ */
+
+import type { ChatMessage, LLMClient, LLMRequest, LLMResponse, LLMStreamDelta, ToolCall } from './types.ts'
+
+export interface HttpLlmOptions {
+  /** 例如 https://api.deepseek.com/v1；会拼接 /chat/completions。 */
+  baseUrl: string
+  apiKey?: string
+  model: string
+  timeoutMs?: number
+  headers?: Record<string, string>
+  fetchImpl?: typeof fetch
+}
+
+interface OpenAiToolCall {
+  id?: string
+  type?: string
+  function?: { name?: string; arguments?: string }
+}
+
+interface OpenAiMessage {
+  content?: string | null
+  tool_calls?: OpenAiToolCall[]
+}
+
+interface OpenAiResponse {
+  choices?: Array<{ message?: OpenAiMessage; finish_reason?: string }>
+  usage?: { prompt_tokens?: number; completion_tokens?: number; total_tokens?: number }
+  error?: { message?: string }
+}
+
+function endpointOf(baseUrl: string): string {
+  const trimmed = String(baseUrl ?? '').trim().replace(/\/+$/, '')
+  if (!trimmed) throw new Error('WORKER_LLM_BASE_URL is required')
+  return trimmed.endsWith('/chat/completions') ? trimmed : `${trimmed}/chat/completions`
+}
+
+function toWireMessages(messages: ChatMessage[]): unknown[] {
+  return messages.map((message) => {
+    if (message.role === 'tool') {
+      return { role: 'tool', tool_call_id: message.tool_call_id, content: message.content ?? '' }
+    }
+    if (message.role === 'assistant' && Array.isArray(message.tool_calls) && message.tool_calls.length > 0) {
+      return {
+        role: 'assistant',
+        content: message.content ?? null,
+        tool_calls: message.tool_calls.map((call) => ({
+          id: call.id,
+          type: 'function',
+          function: { name: call.function.name, arguments: call.function.arguments },
+        })),
+      }
+    }
+    return { role: message.role, content: message.content ?? '' }
+  })
+}
+
+function fromWireResponse(payload: OpenAiResponse): LLMResponse {
+  const choice = payload?.choices?.[0]
+  const message = choice?.message ?? {}
+  const calls: ToolCall[] = Array.isArray(message.tool_calls)
+    ? message.tool_calls.map((call, index) => ({
+        id: String(call?.id ?? `call_${index + 1}`),
+        type: 'function',
+        function: {
+          name: String(call?.function?.name ?? ''),
+          arguments: String(call?.function?.arguments ?? '{}'),
+        },
+      }))
+    : []
+  return {
+    message: {
+      role: 'assistant',
+      content: message.content ?? '',
+      tool_calls: calls.length > 0 ? calls : undefined,
+    },
+    usage: payload?.usage
+      ? {
+          promptTokens: Number(payload.usage.prompt_tokens ?? 0),
+          completionTokens: Number(payload.usage.completion_tokens ?? 0),
+          totalTokens: Number(payload.usage.total_tokens ?? 0),
+        }
+      : undefined,
+    finishReason: choice?.finish_reason,
+  }
+}
+
+interface StreamToolCallState {
+  id?: string
+  name?: string
+  arguments: string
+}
+
+/** 从一行 SSE 文本里取出 data 负载；返回 null 表示控制行。 */
+function sseDataOf(line: string): string | null {
+  const trimmed = line.trim()
+  if (!trimmed || trimmed.startsWith(':')) return null
+  if (!trimmed.startsWith('data:')) return null
+  return trimmed.slice(5).trim()
+}
+
+/**
+ * 解析 OpenAI 兼容的流式 chunk 并聚合为完整响应。
+ * 同时把 content 增量通过 onDelta 实时回调；tool_calls 按 index 聚合片段。
+ */
+function createStreamAccumulator(onDelta: (delta: LLMStreamDelta) => void) {
+  let content = ''
+  let finishReason: string | undefined
+  let usage: LLMResponse['usage']
+  const calls: StreamToolCallState[] = []
+  let seenToolName = ''
+
+  const applyChunk = (chunk: Record<string, unknown>): boolean => {
+    const choices = Array.isArray(chunk?.choices) ? chunk.choices as Array<Record<string, unknown>> : []
+    const choice = choices[0] ?? null
+    if (choice?.delta && typeof choice.delta === 'object') {
+      const delta = choice.delta as Record<string, unknown>
+      const piece = typeof delta.content === 'string' ? delta.content : ''
+      if (piece) {
+        content += piece
+        try { onDelta({ content: piece }) } catch { /* 回调异常不得打断流 */ }
+      }
+      const toolDeltas = Array.isArray(delta.tool_calls) ? delta.tool_calls as Array<Record<string, unknown>> : []
+      for (const item of toolDeltas) {
+        const index = Number(item?.index ?? calls.length)
+        const slot = calls[index] ?? (calls[index] = { arguments: '' })
+        const fn = (item?.function ?? {}) as Record<string, unknown>
+        if (typeof item?.id === 'string' && item.id) slot.id = item.id
+        if (typeof fn.name === 'string' && fn.name) slot.name = fn.name
+        if (typeof fn.arguments === 'string' && fn.arguments) slot.arguments += fn.arguments
+        const name = slot.name ?? ''
+        if (name && name !== seenToolName) {
+          seenToolName = name
+          try { onDelta({ toolName: name }) } catch { /* ignore */ }
+        }
+      }
+    }
+    if (typeof choice?.finish_reason === 'string') finishReason = choice.finish_reason
+    if (chunk?.usage && typeof chunk.usage === 'object') {
+      const raw = chunk.usage as Record<string, unknown>
+      usage = {
+        promptTokens: Number(raw.prompt_tokens ?? 0),
+        completionTokens: Number(raw.completion_tokens ?? 0),
+        totalTokens: Number(raw.total_tokens ?? 0),
+      }
+    }
+    return Boolean(chunk?.choices || chunk?.usage)
+  }
+
+  return {
+    applyChunk,
+    /** 返回聚合后的 LLMResponse（tool_calls 只保留有 name 的）。 */
+    result(): LLMResponse {
+      const toolCalls: ToolCall[] = calls
+        .filter((slot) => Boolean(slot && slot.name))
+        .map((slot, index) => ({
+          id: String(slot.id ?? `call_${index + 1}`),
+          type: 'function',
+          function: { name: String(slot.name ?? ''), arguments: slot.arguments || '{}' },
+        }))
+      return {
+        message: {
+          role: 'assistant',
+          content,
+          tool_calls: toolCalls.length > 0 ? toolCalls : undefined,
+        },
+        usage,
+        finishReason,
+      }
+    },
+    get sawChunk(): boolean {
+      return content.length > 0 || calls.length > 0 || finishReason !== undefined
+    },
+  }
+}
+
+/** 逐块读取响应体并喂给 SSE 解析器；返回是否识别到任何 SSE 数据。 */
+async function consumeSse(body: ReadableStream<Uint8Array> | null, accumulator: ReturnType<typeof createStreamAccumulator>): Promise<boolean> {
+  if (!body || typeof body.getReader !== 'function') return false
+  const reader = body.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ''
+  let sawData = false
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      buffer += decoder.decode(value, { stream: true })
+      // SSE 事件以空行分隔；兼容 \r\n。
+      let boundary = buffer.search(/\r?\n\r?\n/)
+      while (boundary >= 0) {
+        const rawEvent = buffer.slice(0, boundary)
+        buffer = buffer.slice(boundary + (buffer[boundary] === '\r' ? 4 : 2))
+        for (const line of rawEvent.split(/\r?\n/)) {
+          const data = sseDataOf(line)
+          if (!data) continue
+          if (data === '[DONE]') return true
+          sawData = true
+          try {
+            const chunk = JSON.parse(data)
+            accumulator.applyChunk(chunk)
+          } catch { /* 非 JSON 的 data 行忽略 */ }
+        }
+        boundary = buffer.search(/\r?\n\r?\n/)
+      }
+    }
+    // 收尾：没有空行结尾的最后一个事件。
+    const tail = buffer.trim()
+    if (tail) {
+      for (const line of tail.split(/\r?\n/)) {
+        const data = sseDataOf(line)
+        if (!data || data === '[DONE]') continue
+        sawData = true
+        try { accumulator.applyChunk(JSON.parse(data)) } catch { /* ignore */ }
+      }
+    }
+  } finally {
+    try { reader.releaseLock() } catch { /* ignore */ }
+  }
+  return sawData
+}
+
+/** 创建 HTTP LLM 客户端；调用方负责在 Worker 循环外层套超时。 */
+export function createHttpLlmClient(options: HttpLlmOptions): LLMClient {
+  const url = endpointOf(options.baseUrl)
+  const model = String(options.model ?? '').trim()
+  if (!model) throw new Error('WORKER_LLM_MODEL is required')
+  const fetchImpl = options.fetchImpl ?? fetch
+  const timeoutMs = Math.max(1, Number(options.timeoutMs ?? 120_000) || 120_000)
+  return {
+    async chat(request: LLMRequest): Promise<LLMResponse> {
+      const controller = new AbortController()
+      const timer = setTimeout(() => controller.abort(), timeoutMs)
+      const onAbort = () => controller.abort()
+      request.signal?.addEventListener('abort', onAbort, { once: true })
+      try {
+        const body: Record<string, unknown> = {
+          model: request.model ?? model,
+          messages: toWireMessages(request.messages),
+          stream: false,
+        }
+        if (Array.isArray(request.tools) && request.tools.length > 0) {
+          body.tools = request.tools.map((tool) => ({ type: 'function', function: tool }))
+          body.tool_choice = 'auto'
+        }
+        if (request.responseFormat?.type === 'json_object') body.response_format = { type: 'json_object' }
+        const headers: Record<string, string> = {
+          'content-type': 'application/json',
+          accept: 'application/json',
+          ...(options.headers ?? {}),
+        }
+        if (options.apiKey) headers.authorization = `Bearer ${options.apiKey}`
+        const response = await fetchImpl(url, {
+          method: 'POST',
+          headers,
+          body: JSON.stringify(body),
+          signal: controller.signal,
+        })
+        const text = await response.text()
+        if (!response.ok) {
+          const detail = text.slice(0, 300)
+          throw new Error(`LLM HTTP ${response.status}: ${detail}`)
+        }
+        let parsed: OpenAiResponse
+        try {
+          parsed = JSON.parse(text) as OpenAiResponse
+        } catch {
+          throw new Error('LLM response is not valid JSON')
+        }
+        if (parsed.error?.message) throw new Error(`LLM error: ${parsed.error.message}`)
+        return fromWireResponse(parsed)
+      } finally {
+        clearTimeout(timer)
+        request.signal?.removeEventListener('abort', onAbort)
+      }
+    },
+
+    /**
+     * 真实流式调用：stream=true + SSE，边收边回调。
+     * provider 若忽略 stream 并返回普通 JSON，会自动退回聚合解析（不会重复回调）。
+     */
+    async chatStream(request: LLMRequest, onDelta: (delta: LLMStreamDelta) => void): Promise<LLMResponse> {
+      const controller = new AbortController()
+      const timer = setTimeout(() => controller.abort(), timeoutMs)
+      const onAbort = () => controller.abort()
+      request.signal?.addEventListener('abort', onAbort, { once: true })
+      try {
+        const body: Record<string, unknown> = {
+          model: request.model ?? model,
+          messages: toWireMessages(request.messages),
+          stream: true,
+          stream_options: { include_usage: true },
+        }
+        if (Array.isArray(request.tools) && request.tools.length > 0) {
+          body.tools = request.tools.map((tool) => ({ type: 'function', function: tool }))
+          body.tool_choice = 'auto'
+        }
+        const headers: Record<string, string> = {
+          'content-type': 'application/json',
+          accept: 'text/event-stream',
+          ...(options.headers ?? {}),
+        }
+        if (options.apiKey) headers.authorization = `Bearer ${options.apiKey}`
+        const response = await fetchImpl(url, {
+          method: 'POST',
+          headers,
+          body: JSON.stringify(body),
+          signal: controller.signal,
+        })
+        if (!response.ok) {
+          const detail = String(await response.text()).slice(0, 300)
+          throw new Error(`LLM HTTP ${response.status}: ${detail}`)
+        }
+        const accumulator = createStreamAccumulator(onDelta)
+        const contentType = String(response.headers?.get?.('content-type') ?? '')
+        // 声明为 SSE：边收边解析（真正的增量 streaming）。
+        if (contentType.includes('text/event-stream')) {
+          const sawData = await consumeSse(response.body as ReadableStream<Uint8Array> | null, accumulator)
+          if (!sawData) throw new Error('LLM stream ended without any SSE data')
+          return accumulator.result()
+        }
+        // 未声明 SSE（provider 忽略 stream 参数）：整体读回，按 JSON 或 SSE 文本兜底。
+        const text = await response.text()
+        if (/^\s*data:/m.test(text)) {
+          for (const line of text.split(/\r?\n/)) {
+            const data = sseDataOf(line)
+            if (!data || data === '[DONE]') continue
+            try { accumulator.applyChunk(JSON.parse(data)) } catch { /* ignore */ }
+          }
+          if (accumulator.sawChunk) return accumulator.result()
+        }
+        let parsed: OpenAiResponse
+        try {
+          parsed = JSON.parse(text) as OpenAiResponse
+        } catch {
+          throw new Error('LLM response is not valid JSON')
+        }
+        if (parsed.error?.message) throw new Error(`LLM error: ${parsed.error.message}`)
+        const fallback = fromWireResponse(parsed)
+        if (fallback.message.content) {
+          try { onDelta({ content: fallback.message.content }) } catch { /* ignore */ }
+        }
+        return fallback
+      } finally {
+        clearTimeout(timer)
+        request.signal?.removeEventListener('abort', onAbort)
+      }
+    },
+  }
+}