@twinsearth/dsh-master 0.0.0-stage → 3.2.8

package/worker/types.ts

@@ -0,0 +1,247 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+
+/**
+ * dsh-superagent-worker preset 的类型定义（v3.2.2）。
+ *
+ * 运行在分身 VM 内；Router 通过 `DSH_MASTER_TICKET` 环境变量传入 Ticket。
+ * 本文件只用可擦除类型语法（无 enum / namespace / parameter properties），
+ * 因此 Node 22.6+ 的类型擦除与 tsc 都能直接消费。
+ */
+
+export type WorkerPhase =
+  | 'initializing'
+  | 'thinking'
+  | 'executing_tool'
+  | 'reporting'
+  | 'done'
+  | 'failed'
+
+export type WorkerStepType =
+  | 'thought'
+  | 'tool_call'
+  | 'tool_result'
+  | 'final_answer'
+  | 'error'
+  | 'phase'
+
+export type MandateStrength = 'explicit' | 'inferred'
+
+/** 授权范围（不可变 Ticket 的一部分）。 */
+export interface TicketMandate {
+  /** 允许修改的文件范围（通常为 workspace 内路径）；Worker 工具据此做路径 jail。 */
+  scope: string
+  /** 是否允许执行 Shell（默认 false，最小权限）。 */
+  allowShell: boolean
+  policyVersion?: string
+  strength?: MandateStrength
+}
+
+/** Worker 实际消费的工单负载。 */
+export interface TicketPayload {
+  ticketId: string
+  source: string
+  taskDescription: string
+  mandate: TicketMandate
+}
+
+/** 兼容 v3.2.1 Router 的 Ticket 形状（id/sourceId/payload）。 */
+export interface RouterTicketLike {
+  id?: string
+  sourceId?: string
+  requester?: string
+  payload?: string
+  eventType?: string
+  mandate?: {
+    scope?: string
+    allowShell?: boolean
+    policyVersion?: string
+    strength?: MandateStrength
+  }
+}
+
+export interface ToolCall {
+  id: string
+  type?: 'function'
+  function: {
+    name: string
+    /** JSON 字符串（模型返回的原始参数）。 */
+    arguments: string
+  }
+}
+
+export interface ToolSchema {
+  name: string
+  description: string
+  parameters: Record<string, unknown>
+}
+
+export interface ChatMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool'
+  content?: string | null
+  tool_calls?: ToolCall[]
+  tool_call_id?: string
+  name?: string
+}
+
+export interface LLMUsage {
+  promptTokens?: number
+  completionTokens?: number
+  totalTokens?: number
+}
+
+export interface LLMResponse {
+  message: ChatMessage
+  usage?: LLMUsage
+  finishReason?: string
+}
+
+export interface LLMRequest {
+  model?: string
+  messages: ChatMessage[]
+  tools?: ToolSchema[]
+  signal?: AbortSignal
+  /** OpenAI 兼容的可选 JSON 模式；Worker 默认不强制，避免破坏 tool_calls。 */
+  responseFormat?: { type: 'json_object' } | { type: 'text' }
+}
+
+/** 流式片段：content 是增量 token 文本，toolName 表示进入某个工具调用。 */
+export interface LLMStreamDelta {
+  content?: string
+  toolName?: string
+}
+
+/** LLM 适配器接口：由 HTTP/宿主服务/测试脚本提供。 */
+export interface LLMClient {
+  chat(request: LLMRequest): Promise<LLMResponse>
+  /**
+   * 真实流式调用（provider 支持 SSE delta 时实现）。
+   * 返回聚合后的完整响应；delta 在生成过程中实时回调，宿主可直接转发给 UI。
+   * 未实现时 Agent Loop 自动退回 chat() + 分块模拟。
+   */
+  chatStream?(request: LLMRequest, onDelta: (delta: LLMStreamDelta) => void): Promise<LLMResponse>
+}
+
+export interface ToolExecutionContext {
+  workspace: string
+  signal: AbortSignal
+  timeoutMs: number
+  mandate: TicketMandate
+}
+
+export interface WorkerTool {
+  name: string
+  description: string
+  parameters: Record<string, unknown>
+  execute(args: Record<string, unknown>, context: ToolExecutionContext): Promise<string>
+}
+
+export interface WorkerStep {
+  stepIndex: number
+  type: WorkerStepType
+  content: string
+  toolName?: string
+  toolArgs?: Record<string, unknown>
+  timestamp: number
+  tokenUsage?: number
+}
+
+export interface WorkerLimits {
+  /** 硬上限：LLM 轮次。超过即 max-steps。 */
+  maxSteps: number
+  /** 硬上限：累计 token（来自 usage；provider 不返回时按 0 计，另受 context 字符限制）。 */
+  maxTokens: number
+  /** 硬上限：墙钟时间。 */
+  maxWallClockMs: number
+  /** 单次 LLM 调用超时。 */
+  llmTimeoutMs: number
+  /** 单个工具执行超时。 */
+  toolTimeoutMs: number
+  /** 单轮最多并行/顺序工具调用数。 */
+  maxToolCallsPerStep: number
+  /** 连续相同工具调用（同名+同参）允许次数；超过判定死循环。 */
+  maxIdenticalToolRepeats: number
+  /** 工具结果回灌模型的截断长度。 */
+  maxToolResultChars: number
+  /** 上下文（messages 序列化）最大字符数，防 OOM / 超长请求。 */
+  maxContextChars: number
+}
+
+export interface WorkerSink {
+  /** 人类可读日志（可转发到宿主/日志文件）。 */
+  log?(message: string): void
+  /** 每一步的结构化审计记录（崩溃后可恢复现场）。 */
+  step?(step: WorkerStep): void
+  /** 状态机迁移。 */
+  phase?(phase: WorkerPhase): void
+  /** 流式片段（无真实 streaming 时按块模拟；宿主可转发到 UI）。 */
+  stream?(delta: { content?: string; toolName?: string }): void
+}
+
+export interface WorkerDeps {
+  llm: LLMClient
+  tools: WorkerTool[]
+  workspace: string
+  mandate: TicketMandate
+  logger?: {
+    info?(message: string): void
+    warn?(message: string): void
+    error?(message: string): void
+  }
+  sink?: WorkerSink
+  limits?: Partial<WorkerLimits>
+  /** 可注入时钟，便于测试；默认 Date.now。 */
+  clock?: () => number
+  /** 测试用：LLM 请求的 model 覆盖。 */
+  model?: string
+  /** 需要从日志/步骤中抹掉的具体 secret 值（如 LLM key）；正则脱敏之外的兜底。 */
+  redactValues?: string[]
+}
+
+export interface WorkerFailure {
+  code: string
+  message: string
+  fatal: boolean
+}
+
+export interface WorkerResult {
+  ok: boolean
+  ticketId: string
+  phase: WorkerPhase
+  finalAnswer: string
+  steps: WorkerStep[]
+  tokenUsage: number
+  elapsedMs: number
+  error?: WorkerFailure
+  /** 可选的 PR 交付元数据；分支/文件由 Worker 准备，凭据与开 PR 仅在 Router 宿主侧。 */
+  pr?: {
+    branch: string
+    title?: string
+    body?: string
+    base?: string
+    draft?: boolean
+    files?: Array<{ path: string; content: string }>
+  }
+}
+
+export interface WorkerSnapshot {
+  ticketId: string
+  phase: WorkerPhase
+  steps: WorkerStep[]
+  tokenUsage: number
+  elapsedMs: number
+  finalAnswer: string
+}
+
+/** 默认限制（可被 config/构造参数覆盖，但不可关闭硬上限）。 */
+export const DEFAULT_LIMITS: WorkerLimits = {
+  maxSteps: 15,
+  maxTokens: 50_000,
+  maxWallClockMs: 15 * 60_000,
+  llmTimeoutMs: 120_000,
+  toolTimeoutMs: 120_000,
+  maxToolCallsPerStep: 4,
+  maxIdenticalToolRepeats: 3,
+  maxToolResultChars: 8_000,
+  maxContextChars: 400_000,
+}