@twinsearth/dsh-master 0.0.0-stage → 3.2.9

package/worker/agent-loop.ts

@@ -0,0 +1,524 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+
+/**
+ * SuperAgent Worker 的 Agent Loop（v3.2.2）。
+ *
+ * 状态机：
+ *   initializing → thinking → (executing_tool → thinking)* → reporting → done
+ *                                                       └→ failed（任何不可恢复错误）
+ *
+ * 为什么是 while(true)：LLM 的“该不该继续”只由模型输出（是否还有 tool_calls）决定，
+ * 循环条件本身不带业务判断；所有退出都必须经过下面的硬约束之一：
+ *   1. 模型不再返回 tool_calls → reporting/done；
+ *   2. maxSteps 用尽 → failed(max-steps)；
+ *   3. maxTokens 用尽 → failed(token-budget-exceeded)；
+ *   4. maxWallClockMs 用尽 → failed(wall-clock-exceeded)；
+ *   5. 连续相同工具调用超过阈值 → failed(dead-loop-detected)；
+ *   6. LLM/上下文/工具不可恢复错误 → failed(<code>)。
+ *
+ * 工具失败不会抛穿循环：作为 `执行报错: …` 文本回灌给模型，让模型自行纠错；
+ * 只有预算/循环/墙钟这类“停机条件”才终止整个 Worker。
+ */
+
+import type {
+  ChatMessage,
+  LLMResponse,
+  RouterTicketLike,
+  TicketPayload,
+  WorkerDeps,
+  WorkerLimits,
+  WorkerPhase,
+  WorkerResult,
+  WorkerSnapshot,
+  WorkerStep,
+} from './types.ts'
+import { DEFAULT_LIMITS } from './types.ts'
+import { WorkerError, WorkerLimitError, WorkerTicketError, toFailure } from './errors.ts'
+import { buildSystemPrompt, buildUserPrompt } from './prompt.ts'
+import { createToolRegistry } from './tools.ts'
+
+/**
+ * 周期检测（v3.2.7 审计收口）：识别「重复序列」而不是只看连续相同。
+ *
+ * 对最近窗口内**末尾**的序列做判定：若长度 p（1..maxPeriod）的块连续重复 ≥minRepeats 次，
+ * 即判定为同一循环。这样 A/B/A/B、A/B/C/A/B/C 这类交替都能在第 minRepeats 个周期就被抓住，
+ * 不依赖"连续相同"或宽松阈值。
+ *
+ * @param {string[]} signatures 最近调用签名（按时间顺序）
+ * @param {{minRepeats?:number, maxPeriod?:number}} [opts]
+ * @returns {{period:number, repeats:number, sample:string} | null}
+ */
+export function detectRepeatingCycle(
+  signatures: string[],
+  opts: { minRepeats?: number; maxPeriod?: number; maxIdenticalRepeats?: number } = {},
+): { period: number; repeats: number; sample: string } | null {
+  const maxPeriod = Math.max(1, Number(opts.maxPeriod ?? 8) || 8)
+  const list = Array.isArray(signatures) ? signatures : []
+  for (let period = 1; period <= maxPeriod; period += 1) {
+    // 周期 1（纯连续相同）必须遵守规格：> maxIdenticalToolRepeats 才算死循环；
+    // 周期 >= 2 用 3 个完整周期（minRepeats），用于抓 A/B/A/B 之类的交替。
+    const minRepeats = period === 1
+      ? Math.max(2, Number(opts.maxIdenticalRepeats ?? 3) + 1)
+      : Math.max(2, Number(opts.minRepeats ?? (Number(opts.maxIdenticalRepeats ?? 3) + 1)) || 3)
+    const need = period * minRepeats
+    if (list.length < need) continue
+    const tail = list.slice(-need)
+    const block = tail.slice(0, period)
+    let same = true
+    for (let i = period; i < need; i += 1) {
+      if (tail[i] !== block[i % period]) { same = false; break }
+    }
+    if (same) return { period, repeats: minRepeats, sample: block.join(' | ') }
+  }
+  return null
+}
+
+const ABSOLUTE_LIMIT_CEILING: WorkerLimits = {
+  maxSteps: 200,
+  maxTokens: 10_000_000,
+  maxWallClockMs: 24 * 60 * 60_000,
+  llmTimeoutMs: 10 * 60_000,
+  toolTimeoutMs: 10 * 60_000,
+  maxToolCallsPerStep: 32,
+  maxIdenticalToolRepeats: 100,
+  maxToolResultChars: 100_000,
+  maxContextChars: 5_000_000,
+}
+
+function mergeLimits(partial: Partial<WorkerLimits> | undefined): WorkerLimits {
+  const out: WorkerLimits = { ...DEFAULT_LIMITS }
+  if (partial && typeof partial === 'object') {
+    for (const key of Object.keys(DEFAULT_LIMITS) as (keyof WorkerLimits)[]) {
+      const value = partial[key]
+      if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+        out[key] = Math.min(Math.floor(value), ABSOLUTE_LIMIT_CEILING[key])
+      }
+    }
+  }
+  return out
+}
+
+/** 通用的 secret 脱敏（步骤/日志/最终报告）；具体 key 值由 redactValues 兜底。 */
+export function redactSecrets(text: string, extraValues: string[] = []): string {
+  let out = String(text ?? '')
+  for (const value of extraValues) {
+    const secret = String(value ?? '')
+    if (secret.length >= 8) out = out.split(secret).join('[REDACTED]')
+  }
+  return out
+    .replace(/\bsk-[A-Za-z0-9_-]{8,}\b/g, '[REDACTED]')
+    .replace(/\bgithub_pat_[A-Za-z0-9_]{10,}\b/g, '[REDACTED]')
+    .replace(/\bgh[pousr]_[A-Za-z0-9]{10,}\b/g, '[REDACTED]')
+    .replace(/\bAKIA[0-9A-Z]{16}\b/g, '[REDACTED]')
+    .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/gi, 'Bearer [REDACTED]')
+    .replace(/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, '[REDACTED PRIVATE KEY]')
+}
+
+/**
+ * 兼容 v3.2.1 Router Ticket 与 v3.2.2 TicketPayload。
+ * Router 的 mandate.scope 是 threadId（用于派发/授权快照），Worker 的
+ * mandate.scope 需要是 workspace 内路径；这里若发现 scope 非路径则保留
+ * Router 原 scope 并让工具层退回 workspace（见 tools.resolveMandateRoot）。
+ */
+export function normalizeTicket(input: RouterTicketLike | TicketPayload | Record<string, unknown>): TicketPayload {
+  const raw = input && typeof input === 'object' ? input as Record<string, unknown> : {}
+  const mandateRaw = raw.mandate && typeof raw.mandate === 'object' ? raw.mandate as Record<string, unknown> : {}
+  const ticketId = String(raw.ticketId ?? raw.id ?? '').trim()
+  const source = String(raw.source ?? raw.sourceId ?? '').trim()
+  const taskDescription = String(raw.taskDescription ?? raw.payload ?? '').trim()
+  const scope = String(mandateRaw.scope ?? '').trim()
+  if (!ticketId) throw new WorkerTicketError('ticketId is required')
+  if (!source) throw new WorkerTicketError('source is required')
+  if (!taskDescription) throw new WorkerTicketError('taskDescription is required')
+  if (!scope) throw new WorkerTicketError('mandate.scope is required')
+  return {
+    ticketId,
+    source,
+    taskDescription,
+    mandate: {
+      scope,
+      allowShell: mandateRaw.allowShell === true,
+      policyVersion: mandateRaw.policyVersion === undefined ? 'v1.0' : String(mandateRaw.policyVersion),
+      strength: mandateRaw.strength === 'explicit' || mandateRaw.strength === 'inferred' ? mandateRaw.strength : undefined,
+    },
+  }
+}
+
+/** 校验 LLM 返回的 tool_calls 结构；malformed 的调用仍回灌错误文本给模型。 */
+function validateToolCalls(response: LLMResponse): Array<{ id: string; name: string; args: string }> {
+  const message = response?.message ?? { role: 'assistant', content: '' }
+  const calls = Array.isArray(message.tool_calls) ? message.tool_calls : []
+  return calls.map((call, index) => {
+    const id = String(call?.id ?? `call_${index + 1}`)
+    const fn = call?.function && typeof call.function === 'object' ? call.function : undefined
+    return {
+      id,
+      name: String(fn?.name ?? ''),
+      args: String(fn?.arguments ?? '{}'),
+    }
+  })
+}
+
+export class SuperAgentWorker {
+  llm: WorkerDeps['llm']
+  tools: WorkerDeps['tools']
+  workspace: string
+  baseMandate: WorkerDeps['mandate']
+  logger: WorkerDeps['logger']
+  sink: WorkerDeps['sink']
+  limits: WorkerLimits
+  clock: () => number
+  model: string | undefined
+  redactValues: string[]
+  effectiveMandate: TicketPayload['mandate']
+
+  steps: WorkerStep[] = []
+  tokenUsage = 0
+  phase: WorkerPhase = 'initializing'
+  startedAt = 0
+  finalAnswer = ''
+  private history: ChatMessage[] = []
+  private prDelivery: WorkerResult['pr'] | undefined
+  /** 本步是否已收到 provider 的真实流式 delta（true 时不再分块模拟）。 */
+  private streamedThisStep = false
+  private registry: ReturnType<typeof createToolRegistry>
+
+  constructor(deps: WorkerDeps) {
+    if (!deps || !deps.llm || typeof deps.llm.chat !== 'function') throw new Error('SuperAgentWorker requires deps.llm.chat')
+    if (!deps.workspace) throw new Error('SuperAgentWorker requires deps.workspace')
+    this.llm = deps.llm
+    this.tools = deps.tools ?? []
+    this.workspace = deps.workspace
+    this.baseMandate = deps.mandate
+    this.effectiveMandate = deps.mandate
+    this.logger = deps.logger
+    this.sink = deps.sink
+    this.limits = mergeLimits(deps.limits)
+    this.clock = typeof deps.clock === 'function' ? deps.clock : () => Date.now()
+    this.model = deps.model
+    this.redactValues = Array.isArray(deps.redactValues) ? deps.redactValues.filter((value) => typeof value === 'string') : []
+    this.registry = createToolRegistry(this.tools)
+  }
+
+  private redact(text: string): string {
+    return redactSecrets(text, this.redactValues)
+  }
+
+  /** 主入口：永远返回 WorkerResult（不把内部异常抛给宿主/Router）。 */
+  async execute(input: RouterTicketLike | TicketPayload | Record<string, unknown>): Promise<WorkerResult> {
+    this.startedAt = this.clock()
+    this.steps = []
+    this.tokenUsage = 0
+    this.finalAnswer = ''
+    this.prDelivery = undefined
+    let ticket: TicketPayload
+    try {
+      ticket = normalizeTicket(input)
+      this.prDelivery = (input as { pr?: WorkerResult['pr'] }).pr
+      this.ticketId = ticket.ticketId
+      // v3.2.3：Ticket 的 Mandate 必须与构造 Worker 时的授权一致；不一致直接拒绝。
+      if (String(ticket.mandate.scope) !== String(this.baseMandate.scope)) {
+        throw new WorkerError('mandate-mismatch', 'ticket mandate.scope does not match the worker mandate')
+      }
+      // 权限取交集：Ticket 可以进一步收窄，但不能扩大构造时的授权。
+      this.effectiveMandate = {
+        ...ticket.mandate,
+        allowShell: this.baseMandate.allowShell === true && ticket.mandate.allowShell === true,
+      }
+    } catch (error) {
+      const failure = toFailure(error)
+      this.setPhase('failed')
+      this.record({ type: 'error', content: `${failure.code}: ${failure.message}` })
+      return this.result(ticketIdOf(input), false, failure)
+    }
+
+    this.history = [
+      { role: 'system', content: buildSystemPrompt(ticket) },
+      { role: 'user', content: buildUserPrompt(ticket) },
+    ]
+
+    try {
+      this.setPhase('initializing')
+      this.record({ type: 'phase', content: 'initializing' })
+      let stepIndex = 0
+      // 规格判定：连续相同工具调用 > maxIdenticalToolRepeats → dead-loop。
+      let lastSignature = ''
+      let signatureRepeats = 0
+      // 补充判定（P2 审计）：滑动窗口内的同签名次数，用于抓 A/B/A/B 交替；
+      // 阈值取 max(6, 2×连续阈值)，比规格更宽松，避免误杀“合法重复几次再换”的行为。
+      const signatureWindow: string[] = []
+      const WINDOW_SIZE = 40
+      const WINDOW_THRESHOLD = Math.max(6, Number(this.limits.maxIdenticalToolRepeats) * 2)
+      let totalToolCalls = 0
+      const maxTotalToolCalls = Math.min(
+        this.limits.maxSteps * this.limits.maxToolCallsPerStep,
+        1000,
+      )
+
+      // eslint-disable-next-line no-constant-condition
+      while (true) {
+        this.assertWallClock()
+        if (stepIndex >= this.limits.maxSteps) {
+          throw new WorkerLimitError('max-steps', `Worker 超出最大循环次数 (${this.limits.maxSteps})，判定为死循环，强制终止。`)
+        }
+        stepIndex += 1
+        this.setPhase('thinking')
+        this.log(`[Worker] === 循环 Step ${stepIndex}/${this.limits.maxSteps} ===`)
+        this.assertContextBudget()
+
+        const response = await this.callLLM()
+        const rawContent = String(response.message?.content ?? '')
+        if (rawContent.length > this.limits.maxContextChars) {
+          throw new WorkerLimitError('context-limit-exceeded', `单条模型响应长度 ${rawContent.length} 超过上限 ${this.limits.maxContextChars}`)
+        }
+        const usage = response.usage
+        let used = Number(usage?.totalTokens ?? ((usage?.promptTokens ?? 0) + (usage?.completionTokens ?? 0))) || 0
+        if (used <= 0) {
+          // provider 不返回 usage 时的兜底估算，防止 Token 预算被绕过。
+          used = Math.ceil((JSON.stringify(this.history).length + rawContent.length) / 4)
+        }
+        this.tokenUsage += used
+        if (this.tokenUsage > this.limits.maxTokens) {
+          throw new WorkerLimitError('token-budget-exceeded', `超出最大 Token 预算 (${this.limits.maxTokens})，强制终止。`)
+        }
+
+        const assistantMessage: ChatMessage = {
+          role: 'assistant',
+          content: this.redact(rawContent),
+          tool_calls: Array.isArray(response.message?.tool_calls) ? response.message.tool_calls : undefined,
+        }
+        this.history.push(assistantMessage)
+
+        if (assistantMessage.content) {
+          this.stream(assistantMessage.content)
+          this.record({ type: 'thought', content: assistantMessage.content })
+        }
+
+        const toolCalls = validateToolCalls(response)
+        if (toolCalls.length === 0) {
+          this.finalAnswer = String(assistantMessage.content ?? '').trim() || '任务执行完成，无返回内容。'
+          this.setPhase('reporting')
+          this.record({ type: 'final_answer', content: this.finalAnswer })
+          this.setPhase('done')
+          return this.result(ticket.ticketId, true)
+        }
+        if (toolCalls.length > this.limits.maxToolCallsPerStep) {
+          throw new WorkerLimitError('too-many-tool-calls', `单轮工具调用数 ${toolCalls.length} 超过上限 ${this.limits.maxToolCallsPerStep}`)
+        }
+
+        for (const call of toolCalls) {
+          const signature = `${call.name}:${call.args}`
+          totalToolCalls += 1
+          if (totalToolCalls > maxTotalToolCalls) {
+            throw new WorkerLimitError('tool-call-budget-exceeded', `工具调用总数 ${totalToolCalls} 超过上限 ${maxTotalToolCalls}，判定为失控循环。`)
+          }
+          // ① 规格判定：连续相同工具调用（同名+同参）超过阈值
+          if (signature === lastSignature) {
+            signatureRepeats += 1
+          } else {
+            lastSignature = signature
+            signatureRepeats = 1
+          }
+          if (signatureRepeats > this.limits.maxIdenticalToolRepeats) {
+            throw new WorkerLimitError('dead-loop-detected', `连续重复调用同一工具 ${signatureRepeats} 次（${call.name}），判定为死循环。`)
+          }
+          // ② 补充判定：滑动窗口内同签名次数（不要求连续，A/B/A/B 交替也会累计）
+          signatureWindow.push(signature)
+          if (signatureWindow.length > WINDOW_SIZE) signatureWindow.shift()
+          const sameInWindow = signatureWindow.filter((item) => item === signature).length
+          if (sameInWindow > WINDOW_THRESHOLD) {
+            throw new WorkerLimitError('dead-loop-detected', `最近 ${signatureWindow.length} 次调用中同一工具/参数出现 ${sameInWindow} 次（${call.name}），判定为死循环。`)
+          }
+          // ③ 周期判定（cycle-dead-loop）：A/B/A/B、A/B/C/A/B/C 交替在第 3 个周期即判死循环
+          const cycle = detectRepeatingCycle(signatureWindow, { maxPeriod: 8, maxIdenticalRepeats: this.limits.maxIdenticalToolRepeats })
+          if (cycle) {
+            throw new WorkerLimitError('dead-loop-detected', `检测到周期为 ${cycle.period} 的重复调用序列（重复 ${cycle.repeats} 次：[${cycle.sample}]），判定为死循环（cycle-dead-loop）。`)
+          }
+
+          this.record({ type: 'tool_call', content: call.args, toolName: call.name, toolArgs: safeParseArgs(call.args) })
+          this.setPhase('executing_tool')
+          this.stream(undefined, call.name)
+          const result = await this.executeTool(call)
+          const safeResult = this.redact(result)
+          const truncated = safeResult.length > this.limits.maxToolResultChars
+            ? safeResult.slice(0, this.limits.maxToolResultChars) + `\n…[工具结果截断，原长 ${safeResult.length} 字符]`
+            : safeResult
+          this.record({ type: 'tool_result', content: truncated, toolName: call.name })
+          this.history.push({
+            role: 'tool',
+            tool_call_id: call.id,
+            name: call.name,
+            content: truncated,
+          })
+          this.setPhase('thinking')
+        }
+        // 循环继续：带着 tool 结果再次询问模型。
+      }
+    } catch (error) {
+      const failure = toFailure(error)
+      this.setPhase('failed')
+      this.log(`[Worker] 循环终止: ${failure.code} ${failure.message}`)
+      this.record({ type: 'error', content: `${failure.code}: ${failure.message}` })
+      return this.result(ticket.ticketId, false, failure)
+    }
+  }
+
+  /** 最近一步（供宿主轮询推送）。 */
+  getLatestStep(): WorkerStep | null {
+    return this.steps.length > 0 ? this.steps[this.steps.length - 1] : null
+  }
+
+  /** 崩溃恢复现场：把已走步骤/预算一起交给 Router/会话仓。 */
+  snapshot(): WorkerSnapshot {
+    return {
+      ticketId: this.ticketId,
+      phase: this.phase,
+      steps: this.steps.map((step) => ({ ...step })),
+      tokenUsage: this.tokenUsage,
+      elapsedMs: Math.max(0, this.clock() - this.startedAt),
+      finalAnswer: this.finalAnswer,
+    }
+  }
+
+  private ticketId = ''
+
+  private result(ticketId: string, ok: boolean, error?: { code: string; message: string; fatal: boolean }): WorkerResult {
+    return {
+      ok,
+      ticketId,
+      phase: this.phase,
+      finalAnswer: this.finalAnswer,
+      steps: this.steps.map((step) => ({ ...step })),
+      tokenUsage: this.tokenUsage,
+      elapsedMs: Math.max(0, this.clock() - this.startedAt),
+      ...(this.prDelivery ? { pr: this.prDelivery } : {}),
+      error,
+    }
+  }
+
+  private assertWallClock(): void {
+    const elapsed = this.clock() - this.startedAt
+    if (elapsed > this.limits.maxWallClockMs) {
+      throw new WorkerLimitError('wall-clock-exceeded', `Worker 超出最大墙钟时间 (${this.limits.maxWallClockMs}ms)`)
+    }
+  }
+
+  private assertContextBudget(): void {
+    const chars = JSON.stringify(this.history).length
+    if (chars > this.limits.maxContextChars) {
+      throw new WorkerLimitError('context-limit-exceeded', `上下文长度 ${chars} 超过上限 ${this.limits.maxContextChars}，停止以避免 OOM/超长请求。`)
+    }
+  }
+
+  private async callLLM(): Promise<LLMResponse> {
+    const controller = new AbortController()
+    let timer: ReturnType<typeof setTimeout> | undefined
+    this.streamedThisStep = false
+    const timeout = new Promise<never>((_, reject) => {
+      timer = setTimeout(() => {
+        controller.abort()
+        reject(new WorkerError('llm-timeout', `LLM 调用超时（>${this.limits.llmTimeoutMs}ms）`))
+      }, this.limits.llmTimeoutMs)
+    })
+    const request = {
+      model: this.model,
+      messages: this.history,
+      tools: this.registry.schemas(),
+      signal: controller.signal,
+    }
+    try {
+      // 真实 streaming：provider 支持时逐 token 回调宿主；否则退回一次性调用。
+      const pending = typeof this.llm.chatStream === 'function'
+        ? this.llm.chatStream(request, (delta) => {
+            if (delta?.content) this.streamedThisStep = true
+            try { this.sink?.stream?.(delta) } catch { /* sink 不得打断流 */ }
+          })
+        : this.llm.chat(request)
+      const response = await Promise.race([pending, timeout])
+      if (!response || typeof response !== 'object' || !response.message) {
+        throw new WorkerError('llm-invalid-response', 'LLM 返回空响应或缺少 message')
+      }
+      return response
+    } catch (error) {
+      if (error instanceof WorkerError) throw error
+      throw new WorkerError('llm-call-failed', error instanceof Error ? error.message : String(error))
+    } finally {
+      if (timer) clearTimeout(timer)
+    }
+  }
+
+  private async executeTool(call: { id: string; name: string; args: string }): Promise<string> {
+    const controller = new AbortController()
+    try {
+      return await this.registry.execute(
+        { name: call.name, arguments: call.args },
+        {
+          workspace: this.workspace,
+          signal: controller.signal,
+          timeoutMs: this.limits.toolTimeoutMs,
+          mandate: this.effectiveMandate,
+        },
+      )
+    } catch (error) {
+      // 理论上 registry 已把工具异常转成文本；这里兜底确保不打断循环。
+      return `执行报错: ${error instanceof Error ? error.message : String(error)}`
+    }
+  }
+
+  private setPhase(phase: WorkerPhase): void {
+    if (this.phase === phase) return
+    this.phase = phase
+    try { this.sink?.phase?.(phase) } catch { /* sink 不得影响循环 */ }
+    try { this.logger?.info?.(`[Worker] phase=${phase}`) } catch { /* ignore */ }
+  }
+
+  private record(step: Omit<WorkerStep, 'stepIndex' | 'timestamp' | 'tokenUsage'> & { stepIndex?: number }): void {
+    const full: WorkerStep = {
+      stepIndex: step.stepIndex ?? this.steps.length + 1,
+      type: step.type,
+      // v3.2.5 P1-3：所有步骤内容统一脱敏（含 error/thought/final_answer），
+      // 避免异常消息里的密钥绕过 tool_result 处的单点脱敏。
+      content: this.redact(String(step.content ?? '')),
+      toolName: step.toolName,
+      toolArgs: step.toolArgs,
+      timestamp: this.clock(),
+      tokenUsage: this.tokenUsage,
+    }
+    this.steps.push(full)
+    try { this.sink?.step?.(full) } catch { /* ignore */ }
+  }
+
+  private stream(content?: string, toolName?: string): void {
+    try {
+      if (content) {
+        // 本步由 provider 真实流式输出过 → 不重复模拟；否则按块模拟兜底。
+        if (this.streamedThisStep) return
+        for (let index = 0; index < content.length; index += 240) {
+          this.sink?.stream?.({ content: content.slice(index, index + 240) })
+        }
+      } else if (toolName) {
+        this.sink?.stream?.({ toolName })
+      }
+    } catch { /* ignore */ }
+  }
+
+  private log(message: string): void {
+    try { this.sink?.log?.(message) } catch { /* ignore */ }
+    try { this.logger?.info?.(message) } catch { /* ignore */ }
+  }
+}
+
+function ticketIdOf(input: RouterTicketLike | TicketPayload | Record<string, unknown>): string {
+  const raw = input && typeof input === 'object' ? input as Record<string, unknown> : {}
+  return String(raw.ticketId ?? raw.id ?? '')
+}
+
+function safeParseArgs(args: string): Record<string, unknown> | undefined {
+  try {
+    const parsed = JSON.parse(String(args ?? '{}'))
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed as Record<string, unknown> : undefined
+  } catch {
+    return undefined
+  }
+}

package/worker/errors.ts

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+
+/** Worker 可分类错误：Router/宿主据此决定是否重试或报警。 */
+export class WorkerError extends Error {
+  code: string
+  fatal: boolean
+
+  constructor(code: string, message: string, fatal = true) {
+    super(message)
+    this.name = 'WorkerError'
+    this.code = code
+    this.fatal = fatal
+  }
+}
+
+export class WorkerLimitError extends WorkerError {
+  constructor(code: string, message: string) {
+    super(code, message, true)
+    this.name = 'WorkerLimitError'
+  }
+}
+
+export class WorkerTicketError extends WorkerError {
+  constructor(message: string) {
+    super('ticket-invalid', message, true)
+    this.name = 'WorkerTicketError'
+  }
+}
+
+export class MandateViolationError extends WorkerError {
+  constructor(message: string) {
+    super('mandate-violation', message, false)
+    this.name = 'MandateViolationError'
+  }
+}
+
+/** 把 unknown 转成可序列化的失败对象。 */
+export function toFailure(error: unknown): { code: string; message: string; fatal: boolean } {
+  if (error instanceof WorkerError) {
+    return { code: error.code, message: error.message, fatal: error.fatal }
+  }
+  if (error instanceof Error) {
+    return { code: 'worker-failed', message: error.message, fatal: true }
+  }
+  return { code: 'worker-failed', message: String(error), fatal: true }
+}

package/worker/github-pr.ts

@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+
+/**
+ * Worker 的 GitHub PR 客户端（v3.2.5）。
+ *
+ * 仅做“创建 PR”的 API 调用：分支必须已由 Worker/宿主推送到 GitHub；
+ * token 来自宿主注入的 DSH_MASTER_GITHUB_TOKEN，不写日志、不进状态。
+ * create_pr 工具默认没有 client（fail-closed），只有配置完整时才可用。
+ */
+
+export interface GithubPrOptions {
+  token: string
+  repo: string
+  apiBase?: string
+  baseBranch?: string
+  fetchImpl?: typeof fetch
+}
+
+export interface PullRequestInput {
+  title: string
+  body: string
+  branch?: string
+  base?: string
+}
+
+export interface PullRequestClient {
+  createPullRequest(input: PullRequestInput): Promise<string>
+}
+
+export function createGithubPrClient(options: GithubPrOptions): PullRequestClient {
+  const token = String(options.token ?? '').trim()
+  const repo = String(options.repo ?? '').trim()
+  if (!token) throw new Error('github pr client requires token')
+  if (!/^[^/\s]+\/[^/\s]+$/.test(repo)) throw new Error('github pr client requires repo owner/name')
+  const apiBase = String(options.apiBase ?? 'https://api.github.com').replace(/\/+$/, '')
+  const defaultBase = String(options.baseBranch ?? 'main')
+  const fetchImpl = options.fetchImpl ?? fetch
+  return {
+    async createPullRequest(input: PullRequestInput): Promise<string> {
+      const branch = String(input?.branch ?? '').trim()
+      if (!branch) throw new Error('create_pr requires a branch (push it first)')
+      const response = await fetchImpl(`${apiBase}/repos/${repo}/pulls`, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          accept: 'application/vnd.github+json',
+          authorization: `Bearer ${token}`,
+          'user-agent': 'dsh-master-worker',
+        },
+        body: JSON.stringify({
+          title: String(input?.title ?? '').slice(0, 200),
+          body: String(input?.body ?? '').slice(0, 20_000),
+          head: branch,
+          base: String(input?.base ?? defaultBase),
+        }),
+      })
+      const text = await response.text()
+      if (!response.ok) throw new Error(`github pr create failed: HTTP ${response.status} ${text.slice(0, 200)}`)
+      let parsed: { html_url?: string; number?: number } = {}
+      try { parsed = JSON.parse(text) } catch { /* ignore */ }
+      return String(parsed.html_url ?? `PR #${parsed.number ?? '?'}`)
+    },
+  }
+}