@twinsearth/dsh-master 0.0.0-stage → 3.2.8

package/worker/tools.ts

@@ -0,0 +1,531 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+
+/**
+ * Worker 的安全工具集（v3.2.3）。
+ *
+ * v3.2.2 安全审计后的加固：
+ *   * Shell 使用白名单环境变量（剥离 KEY/TOKEN/SECRET/DSH_*），防密钥回灌模型；
+ *   * Shell 超时/中止时 kill 整个进程树（Windows taskkill /T /F；POSIX 进程组），
+ *     不再出现“工具已返回但后台进程继续跑”；
+ *   * fs_write_file 的 Mandate 来自每次调用的 context.mandate（而非构造闭包），
+ *     并默认拒绝 .git/.dsh/.env 等敏感路径；
+ *   * 路径 jail + realpath 防 symlink 逃逸保持不变。
+ *
+ * 仍然坚持：Shell 的高危语义无法用黑名单彻底解决，**VM/容器隔离是主防线**；
+ * allowShell 应与“已证明隔离的 VM”绑定（见 docs/SECURITY.md）。
+ */
+
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { spawn } from 'node:child_process'
+
+import type {
+  TicketMandate,
+  ToolExecutionContext,
+  ToolSchema,
+  WorkerTool,
+} from './types.ts'
+
+export const LONG_SYNC_COMMAND_THRESHOLD_MS = 5000
+const MAX_READ_BYTES = 256 * 1024
+const MAX_WRITE_BYTES = 1024 * 1024
+const MAX_SHELL_OUTPUT_CHARS = 16_000
+const SHELL_ENV_ALLOWLIST = new Set([
+  'PATH', 'Path', 'PATHEXT', 'SYSTEMROOT', 'SystemRoot', 'WINDIR', 'COMSPEC', 'ComSpec',
+  'TEMP', 'TMP', 'HOME', 'USERPROFILE', 'HOMEDRIVE', 'HOMEPATH', 'LANG', 'LC_ALL', 'TZ', 'SHELL',
+])
+
+/** 默认拒绝写入的敏感路径（相对 workspace；可在 config 覆盖）。 */
+export const DEFAULT_DENY_WRITE_PATHS = ['.git', '.dsh', '.env', '.env.local', '.ssh', 'node_modules/.cache']
+
+/**
+ * 命令级禁锢（v3.2.5 P0-2 纵深防御）：
+ *
+ * 黑名单**不是**安全边界—— type ../x / echo > ../x / sh -c ... / powershell -Command ...
+ * 都能绕过字面黑名单。这里在命令串层面硬拒绝能逃出 jail 的构造：
+ *   * 重定向与管道（> >> < | && || ;）：可把输出写到任意路径、可串联任意解释器；
+ *   * 目录切换（cd / chdir / pushd / popd）：一旦 cd 出 jail，后续相对路径全部逃离；
+ *   * 父目录穿越（..）：相对逃逸的主要形式；
+ *   * 绝对路径（盘符 / 前导斜杠 / ~）：jail 外的绝对路径；
+ *   * 环境变量展开（%VAR% / $VAR / ${VAR}）：可拼出密钥名或路径；
+ *   * 解释器（sh/bash/cmd/powershell/node/python/...）：等价任意代码执行。
+ *
+ * 真正的边界仍是 VM/容器（见 docs/SECURITY.md）：本函数只保证「未证明隔离时不可用」。
+ */
+const SHELL_INTERPRETERS = new Set([
+  'sh', 'bash', 'zsh', 'dash', 'ksh', 'fish',
+  'cmd', 'cmd.exe', 'powershell', 'powershell.exe', 'pwsh', 'pwsh.exe',
+  'node', 'nodejs', 'python', 'python3', 'perl', 'ruby', 'php', 'deno', 'bun',
+  'wscript', 'cscript', 'mshta', 'rundll32', 'regsvr32', 'certutil', 'bitsadmin',
+])
+
+/** 返回拒绝原因；null 表示通过命令级禁锢检查。 */
+export function shellConfinementViolation(command: string): string | null {
+  const raw = String(command ?? '')
+  if (!raw.trim()) return 'empty-command'
+  // 1) 重定向 / 管道 / 串联 / 命令替换
+  if (/[<>|&;`]/.test(raw)) return 'shell-redirection-or-chaining'
+  if (/\$\(/.test(raw)) return 'shell-substitution'
+  // 2) 目录切换
+  if (/\b(cd|chdir|pushd|popd)\b/i.test(raw)) return 'shell-cd'
+  // 3) 父目录穿越（路径段形式，避免误伤 a..b 文件名）
+  if (/(^|[\s"'])\.\.([\\/]|$)/.test(raw)) return 'shell-parent-traversal'
+  // 4) 绝对路径（盘符 / 前导斜杠 / UNC / ~）
+  if (/[A-Za-z]:[\\/]/.test(raw)) return 'shell-absolute-path'
+  if (/(^|[\s"'])[\\/]{1,2}[^\s"']/.test(raw)) return 'shell-absolute-path'
+  if (/(^|[\s"'])~[\\/]/.test(raw)) return 'shell-home-path'
+  // 5) 环境变量展开（可能拼出密钥名或 jail 外路径）
+  if (/%[A-Za-z_][A-Za-z0-9_]*%/.test(raw)) return 'shell-env-expansion'
+  if (/\$\{?[A-Za-z_][A-Za-z0-9_]*\}?/.test(raw)) return 'shell-env-expansion'
+  // 6) 解释器作为命令词（任意代码执行）
+  const firstWord = raw.trim().split(/\s+/)[0].replace(/^["']|["']$/g, '').toLowerCase()
+  const base = firstWord.split(/[\\/]/).pop() ?? firstWord
+  if (SHELL_INTERPRETERS.has(base)) return 'shell-interpreter:' + base
+  // 7) git 危险子命令（含 -C / --git-dir / -c 变体）
+  if (/\bgit\b[^;&|]*\b(push|remote|config|credential|submodule)\b/i.test(raw)) return 'shell-git-write'
+  return null
+}
+
+/** 危险 Shell 模式（最小黑名单；VM 网络/资源隔离仍是主防线）。 */
+export const DEFAULT_DENY_PATTERNS: RegExp[] = [
+  /\bsudo\b/i,
+  /\bmkfs\b/i,
+  /\bdd\s+if=/i,
+  /\bshutdown\b/i,
+  /\breboot\b/i,
+  /\b(curl|wget)\b/i,
+  /\b(ssh|scp|nc|ncat|telnet)\b/i,
+  /\bchmod\s+777\b/i,
+  /\brm\s+-[a-z]*r[a-z]*f[a-z]*\s+\/(\s|$)/i,
+  /\bgit\s+push\b/i,
+  /\bgh\s+(auth|token)\b/i,
+  /\bpowershell(\.exe)?\b.*\s-(enc|e)\b/i,
+  /\b(base64\s+-d|frombase64string)\b.*\|\s*(sh|bash|powershell)/i,
+  // 解释器 -e/-c 任意代码执行：黑名单挡不住，直接拒绝（VM 内也应尽量少用）。
+  /\b(node|python|python3|perl|ruby|php)\b.*\s-(e|c)\b/i,
+]
+
+/** 只保留安全环境变量；任何 KEY/TOKEN/SECRET/PASSWORD/AUTH/DSH_* 一律剔除。 */
+export function sanitizeShellEnv(env: Record<string, string | undefined> = process.env): Record<string, string> {
+  const safe: Record<string, string> = {}
+  for (const [key, value] of Object.entries(env)) {
+    if (value === undefined) continue
+    if (!SHELL_ENV_ALLOWLIST.has(key)) continue
+    safe[key] = value
+  }
+  // 最小可运行集：没有 PATH 时用系统默认（exec 会在 shell 内置 PATH，但显式更稳）。
+  if (!safe.PATH && !safe.Path) safe.PATH = process.platform === 'win32' ? 'C:\\Windows\\System32;C:\\Windows' : '/usr/local/bin:/usr/bin:/bin'
+  return safe
+}
+
+/** 杀掉整棵进程树（Windows 用 taskkill /T；POSIX 用负 pid 信号）。 */
+export function killProcessTree(child: { pid?: number } | null | undefined, platform = process.platform): Promise<void> {
+  const pid = Number(child?.pid)
+  if (!Number.isInteger(pid) || pid <= 0) return Promise.resolve()
+  return new Promise((resolve) => {
+    try {
+      if (platform === 'win32') {
+        const killer = spawn('taskkill', ['/pid', String(pid), '/T', '/F'], { windowsHide: true })
+        killer.on('close', () => resolve())
+        killer.on('error', () => resolve())
+      } else {
+        try { process.kill(-pid, 'SIGKILL') } catch { /* already gone */ }
+        try { process.kill(pid, 'SIGKILL') } catch { /* already gone */ }
+        resolve()
+      }
+    } catch {
+      resolve()
+    }
+  })
+}
+
+export interface ShellResult {
+  stdout: string
+  stderr: string
+  code: number | null
+  timedOut: boolean
+  aborted: boolean
+}
+
+/**
+ * 在 workspace 内执行 Shell；超时/中止时杀死进程树并等待退出。
+ * 输出上限 2MB（超出 kill），返回值再截断到 16k 字符。
+ */
+export function runShell(command: string, options: {
+  cwd: string
+  timeoutMs: number
+  signal: AbortSignal
+  env?: Record<string, string | undefined>
+}): Promise<ShellResult> {
+  return new Promise((resolve) => {
+    const child = spawn(command, {
+      cwd: options.cwd,
+      env: sanitizeShellEnv(options.env ?? process.env),
+      shell: true,
+      windowsHide: true,
+      detached: process.platform !== 'win32',
+    })
+    let stdout = ''
+    let stderr = ''
+    let settled = false
+    let timedOut = false
+    let aborted = false
+    let size = 0
+    let killTimer: ReturnType<typeof setTimeout> | undefined
+    const finish = (code: number | null) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      if (killTimer) clearTimeout(killTimer)
+      options.signal.removeEventListener('abort', onAbort)
+      // close 表示 stdio 已关闭；只有超时/中止/输出爆量时才需补杀进程树。
+      // 不再对每次成功命令都调用 taskkill，也不等待一个可能永远不来的第二次 close。
+      resolve({ stdout, stderr, code, timedOut, aborted })
+    }
+    const killAndSettle = () => {
+      void killProcessTree(child)
+      // 某些孙进程持有管道时 close 可能迟到；给正常关闭一个短窗口后硬结算。
+      if (killTimer) clearTimeout(killTimer)
+      killTimer = setTimeout(() => finish(null), 500)
+      killTimer.unref?.()
+    }
+    const timer = setTimeout(() => {
+      timedOut = true
+      killAndSettle()
+    }, Math.max(1, options.timeoutMs))
+    const onAbort = () => {
+      aborted = true
+      killAndSettle()
+    }
+    options.signal.addEventListener('abort', onAbort, { once: true })
+    child.stdout?.on('data', (chunk: Buffer) => {
+      size += chunk.length
+      if (size > 2 * 1024 * 1024) { killAndSettle(); return }
+      if (stdout.length < MAX_SHELL_OUTPUT_CHARS * 2) stdout += chunk.toString('utf8')
+    })
+    child.stderr?.on('data', (chunk: Buffer) => {
+      size += chunk.length
+      if (size > 2 * 1024 * 1024) { killAndSettle(); return }
+      if (stderr.length < MAX_SHELL_OUTPUT_CHARS * 2) stderr += chunk.toString('utf8')
+    })
+    child.on('error', (error) => { stderr += `\n${error.message}`; void finish(null) })
+    child.on('close', (code) => { void finish(code) })
+  })
+}
+
+export interface PullRequestInput {
+  title: string
+  body: string
+  branch?: string
+  base?: string
+}
+
+export interface PullRequestClient {
+  createPullRequest(input: PullRequestInput): Promise<string>
+}
+
+export interface SandboxOptions {
+  workspace: string
+  mandate: TicketMandate
+  /**
+   * VM/容器隔离是否已被证明（v3.2.5 P0-2 fail-closed）：
+   * 未证明时 exec_shell_in_vm 一律拒绝——黑名单/路径字符串检查都不是安全边界。
+   */
+  vmIsolation?: boolean
+  prClient?: PullRequestClient
+  denyPatterns?: RegExp[]
+  /** 额外拒绝写入的相对路径。 */
+  denyWritePaths?: string[]
+  /** Shell 超过该时长后转为后台作业（默认 5000ms；测试可缩小）。 */
+  backgroundAfterMs?: number
+}
+
+/** 解析 Mandate.scope 为写 jail 根；scope 是 threadId/非路径时退回 workspace。 */
+export function resolveMandateRoot(workspace: string, scope: string): string {
+  const root = path.resolve(workspace)
+  const raw = String(scope ?? '').trim()
+  if (!raw) return root
+  // scope 首先是一张 Ticket 的逻辑边界（GitHub issue/飞书 thread），不是路径。
+  // 仅当配置明确给出已存在的仓库子目录时才收窄写 jail，绝不把飞书 ID 当成路径。
+  if (raw.includes('#') || raw.includes(':')) return root
+  const candidate = path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(root, raw)
+  const rel = path.relative(root, candidate)
+  if (rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))) return candidate
+  return root
+}
+
+function isInside(root: string, candidate: string): boolean {
+  const rel = path.relative(root, candidate)
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))
+}
+
+async function realpathNearest(target: string): Promise<string> {
+  let current = target
+  for (let i = 0; i < 32; i += 1) {
+    try {
+      return await fs.realpath(current)
+    } catch {
+      const parent = path.dirname(current)
+      if (parent === current) return current
+      current = parent
+    }
+  }
+  return target
+}
+
+export async function resolveInside(root: string, target: unknown): Promise<string> {
+  const text = String(target ?? '').trim()
+  if (!text || text.includes('\u0000')) throw new Error('invalid-path')
+  const base = path.resolve(root)
+  const resolved = path.isAbsolute(text) ? path.resolve(text) : path.resolve(base, text)
+  if (!isInside(base, resolved)) throw new Error('path-outside-workspace')
+  const realBase = await realpathNearest(base)
+  const realTarget = await realpathNearest(resolved)
+  if (!isInside(realBase, realTarget)) throw new Error('path-outside-workspace')
+  return resolved
+}
+
+function requireString(args: Record<string, unknown>, key: string): string {
+  const value = args[key]
+  if (typeof value !== 'string') throw new Error(`argument ${key} must be a string`)
+  return value
+}
+
+function truncateOutput(text: string): string {
+  if (text.length <= MAX_SHELL_OUTPUT_CHARS) return text
+  return text.slice(0, MAX_SHELL_OUTPUT_CHARS) + `\n…[输出截断，共 ${text.length} 字符]`
+}
+
+function commandDenied(command: string, patterns: RegExp[]): string | null {
+  for (const pattern of patterns) if (pattern.test(command)) return String(pattern)
+  return null
+}
+
+/** 写入前检查敏感相对路径；在 workspace 与 mandateRoot 之间都检查。 */
+function deniedWritePath(workspace: string, target: string, denyPaths: string[]): string | null {
+  const rel = path.relative(workspace, target).split(path.sep).join('/')
+  for (const denied of denyPaths) {
+    const normalized = denied.replace(/\\/g, '/').replace(/^\/+/, '')
+    if (normalized && (rel === normalized || rel.startsWith(normalized + '/'))) return normalized
+  }
+  // v3.2.5 P2：.env 的所有变体（.env、.env.local、.env.production、.env.example…）一律拒绝写入，
+  // 避免仅靠枚举漏掉 .env.production 之类。
+  const baseName = rel.split('/').pop() ?? ''
+  if (/^\.env(\.|$)/i.test(baseName)) return '.env*'
+  return null
+}
+
+function createPrTool(client?: PullRequestClient): WorkerTool {
+  return {
+    name: 'create_pr',
+    description: '在允许的仓库创建一个 Pull Request（需要宿主注入 PR 客户端；默认不可用）',
+    parameters: {
+      type: 'object',
+      properties: {
+        title: { type: 'string' }, body: { type: 'string' },
+        branch: { type: 'string' }, base: { type: 'string' },
+      },
+      required: ['title', 'body'],
+    },
+    async execute(args) {
+      if (!client) return '【系统拒绝】PR 后端未配置；请输出最终报告，由 Router/宿主完成回写。'
+      // v3.2.5 P2：分支/base 白名单校验——Worker 不得直接对默认分支开 PR，也不得使用非法分支名。
+      const PROTECTED_BASES = ['main', 'master', 'trunk', 'release', 'production', 'stable']
+      const branch = typeof args.branch === 'string' ? args.branch.trim() : ''
+      const base = typeof args.base === 'string' && args.base.trim() ? args.base.trim() : undefined
+      if (!branch) return '【系统拒绝】create_pr 必须显式提供 branch（分支需由宿主/分身先推送）。'
+      if (!/^[A-Za-z0-9._/-]{1,120}$/.test(branch)) return '【系统拒绝】branch 含非法字符。'
+      if (branch.startsWith('-') || branch.includes('..') || branch.includes('//')) return '【系统拒绝】branch 不合法。'
+      if (PROTECTED_BASES.includes(branch.toLowerCase())) return '【系统拒绝】不能直接向受保护分支开 PR（branch=' + branch + '）。'
+      if (base && PROTECTED_BASES.includes(base.toLowerCase()) === false) return '【系统拒绝】base 必须是受保护主干分支，当前 base=' + base + '。'
+      if (base && branch.toLowerCase() === base.toLowerCase()) return '【系统拒绝】branch 与 base 相同。'
+      try {
+        const url = await client.createPullRequest({
+          title: requireString(args, 'title'),
+          body: requireString(args, 'body'),
+          branch,
+          base,
+        })
+        return `PR created: ${url}`
+      } catch (error) {
+        return `创建 PR 失败: ${error instanceof Error ? error.message : String(error)}`
+      }
+    },
+  }
+}
+
+export function createSandboxTools(options: SandboxOptions): WorkerTool[] {
+  const workspace = path.resolve(options.workspace)
+  const denyPatterns = [...DEFAULT_DENY_PATTERNS, ...(options.denyPatterns ?? [])]
+  const denyWritePaths = [...DEFAULT_DENY_WRITE_PATHS, ...(options.denyWritePaths ?? [])]
+  const backgroundAfterMs = Math.max(20, Number(options.backgroundAfterMs ?? LONG_SYNC_COMMAND_THRESHOLD_MS) || LONG_SYNC_COMMAND_THRESHOLD_MS)
+  interface ShellJob { id: string; status: 'running' | 'done'; result?: ShellResult; startedAt: number; timeoutMs: number; cleanup?: ReturnType<typeof setTimeout> }
+  const shellJobs = new Map<string, ShellJob>()
+  let shellJobSeq = 0
+  const formatShellResult = (result: ShellResult, timeoutMs: number): string => {
+    const stdout = truncateOutput(result.stdout)
+    const stderr = truncateOutput(result.stderr)
+    if (result.timedOut || result.aborted) return `执行报错: 超时（>${timeoutMs}ms）或已中止；进程树已终止\nSTDOUT:\n${stdout}\nSTDERR:\n${stderr}`
+    return `STDOUT:\n${stdout}\nSTDERR:\n${stderr}`
+  }
+  const startShellJob = (command: string, context: ToolExecutionContext): ShellJob => {
+    if (shellJobs.size >= 50) {
+      const oldestDone = [...shellJobs.values()].find((job) => job.status === 'done')
+      if (oldestDone) { if (oldestDone.cleanup) clearTimeout(oldestDone.cleanup); shellJobs.delete(oldestDone.id) }
+      else throw new Error('too-many-background-shell-jobs')
+    }
+    const id = `vm-job-${Date.now().toString(36)}-${(++shellJobSeq).toString(36)}`
+    const job: ShellJob = { id, status: 'running', startedAt: Date.now(), timeoutMs: Math.max(1, context.timeoutMs) }
+    shellJobs.set(id, job)
+    void runShell(command, { cwd: workspace, timeoutMs: Math.max(1, context.timeoutMs), signal: context.signal })
+      .then((result) => {
+        job.result = result
+        job.status = 'done'
+        job.cleanup = setTimeout(() => shellJobs.delete(id), 10 * 60_000)
+        job.cleanup.unref?.()
+      })
+      .catch((error) => {
+        job.result = { stdout: '', stderr: String(error instanceof Error ? error.message : error), code: null, timedOut: false, aborted: false }
+        job.status = 'done'
+      })
+    return job
+  }
+  return [
+    {
+      name: 'fs_read_file',
+      description: '读取 workspace 内文件的 UTF-8 内容（最大 256KB）',
+      parameters: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
+      async execute(args) {
+        const file = await resolveInside(workspace, requireString(args, 'path'))
+        const stat = await fs.stat(file)
+        if (!stat.isFile()) throw new Error('not-a-file')
+        if (stat.size > MAX_READ_BYTES) throw new Error('file-too-large')
+        return await fs.readFile(file, 'utf8')
+      },
+    },
+    {
+      name: 'fs_list_dir',
+      description: '列出 workspace 内目录条目（最多 200 项）',
+      parameters: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
+      async execute(args) {
+        const dir = await resolveInside(workspace, args.path === undefined ? '.' : requireString(args, 'path'))
+        const entries = await fs.readdir(dir, { withFileTypes: true })
+        return entries.slice(0, 200).map((entry) => `${entry.isDirectory() ? 'dir ' : 'file'} ${entry.name}`).join('\n') || '(empty)'
+      },
+    },
+    {
+      name: 'fs_write_file',
+      description: '写入文件（workspace 内且位于 Mandate.scope；拒绝 .git/.env 等敏感路径）',
+      parameters: { type: 'object', properties: { path: { type: 'string' }, content: { type: 'string' } }, required: ['path', 'content'] },
+      async execute(args, context) {
+        // v3.2.3：Mandate 每次从 context 取，避免构造闭包与本次 Ticket 不一致。
+        const mandateRoot = resolveMandateRoot(workspace, context.mandate.scope)
+        const target = await resolveInside(workspace, requireString(args, 'path'))
+        if (!isInside(mandateRoot, target)) throw new Error('path-outside-mandate')
+        const denied = deniedWritePath(workspace, target, denyWritePaths)
+        if (denied) throw new Error(`sensitive-path-denied:${denied}`)
+        const content = requireString(args, 'content')
+        if (Buffer.byteLength(content, 'utf8') > MAX_WRITE_BYTES) throw new Error('content-too-large')
+        await fs.mkdir(path.dirname(target), { recursive: true })
+        const realParent = await realpathNearest(path.dirname(target))
+        if (!isInside(await realpathNearest(mandateRoot), realParent)) throw new Error('path-outside-mandate')
+        await fs.writeFile(target, content, 'utf8')
+        return `written ${Buffer.byteLength(content, 'utf8')} bytes to ${path.relative(workspace, target)}`
+      },
+    },
+    {
+      name: 'exec_shell_in_vm',
+      description: '在分身 workspace 内执行 Shell（需 Mandate.allowShell；脱敏环境、黑名单、进程树超时）',
+      parameters: { type: 'object', properties: { command: { type: 'string' } }, required: ['command'] },
+      async execute(args, context) {
+        // P0-2 fail-closed：没有隔离证明就不允许 Shell（黑名单不是安全边界）。
+        if (options.vmIsolation !== true) {
+          return '【系统拒绝】Shell 仅在已证明隔离的 VM/容器内可用；当前运行态未提供隔离证明（DSH_MASTER_VM_ISOLATION=attested）。'
+        }
+        if (context.mandate.allowShell !== true) return '【系统拒绝】当前工单未授权执行 Shell 命令。'
+        const command = requireString(args, 'command').trim()
+        if (!command) throw new Error('command-required')
+        const denied = commandDenied(command, denyPatterns)
+        if (denied) return `【系统拒绝】命令命中安全黑名单（${denied}）。`
+        // P0-2：命令级禁锢（重定向/管道/cd/../绝对路径/env 展开/解释器/git 写操作）。
+        const escaped = shellConfinementViolation(command)
+        if (escaped) return `【系统拒绝】命令试图逃出 workspace/Mandate jail（${escaped}）。`
+        const job = startShellJob(command, context)
+        let timer: ReturnType<typeof setTimeout> | undefined
+        try {
+          return await Promise.race([
+            (async () => {
+              while (job.status === 'running') await new Promise((resolve) => setTimeout(resolve, 10))
+              return formatShellResult(job.result!, context.timeoutMs)
+            })(),
+            new Promise<string>((resolve) => {
+              timer = setTimeout(() => resolve(`后台任务 ${job.id} 已启动（超过 ${backgroundAfterMs}ms）；请调用 vm_job_result 查询，参数 {"jobId":"${job.id}"}。`), backgroundAfterMs)
+              timer.unref?.()
+            }),
+          ])
+        } finally { if (timer) clearTimeout(timer) }
+      },
+    },
+    {
+      name: 'vm_job_result',
+      description: '查询 exec_shell_in_vm 后台作业的终态与输出；参数 jobId',
+      parameters: { type: 'object', properties: { jobId: { type: 'string' } }, required: ['jobId'] },
+      async execute(args) {
+        const id = requireString(args, 'jobId')
+        const job = shellJobs.get(id)
+        if (!job) return `【系统拒绝】未知或已过期的后台任务: ${id}`
+        if (job.status === 'running') return `{"jobId":"${id}","status":"running"}`
+        return formatShellResult(job.result!, job.timeoutMs)
+      },
+    },
+    createPrTool(options.prClient),
+  ]
+}
+
+export interface ToolRegistry {
+  schemas(): ToolSchema[]
+  execute(call: { name: string; arguments: string }, context: ToolExecutionContext): Promise<string>
+}
+
+export function createToolRegistry(tools: WorkerTool[]): ToolRegistry {
+  const byName = new Map(tools.map((tool) => [tool.name, tool]))
+  return {
+    schemas() {
+      return tools.map((tool) => ({ name: tool.name, description: tool.description, parameters: tool.parameters }))
+    },
+    async execute(call, context) {
+      const tool = byName.get(String(call?.name ?? ''))
+      if (!tool) return `【系统拒绝】未知工具: ${String(call?.name ?? '')}`
+      let args: Record<string, unknown> = {}
+      try {
+        const parsed = JSON.parse(String(call?.arguments ?? '{}'))
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) args = parsed as Record<string, unknown>
+        else return '执行报错: 工具参数必须是 JSON object'
+      } catch (error) {
+        return `执行报错: 参数 JSON 解析失败: ${error instanceof Error ? error.message : String(error)}`
+      }
+      const controller = new AbortController()
+      const timer = setTimeout(() => controller.abort(), Math.max(1, context.timeoutMs))
+      const onAbort = () => controller.abort()
+      context.signal.addEventListener('abort', onAbort, { once: true })
+      try {
+        return await Promise.race([
+          tool.execute(args, { ...context, signal: controller.signal }),
+          new Promise<string>((resolve) => {
+            controller.signal.addEventListener('abort', () => resolve(`执行报错: 工具超时或被中止（>${context.timeoutMs}ms）`), { once: true })
+          }),
+        ])
+      } catch (error) {
+        return `执行报错: ${error instanceof Error ? error.message : String(error)}`
+      } finally {
+        clearTimeout(timer)
+        context.signal.removeEventListener('abort', onAbort)
+      }
+    },
+  }
+}
+
+export function isPathInside(root: string, target: string): boolean {
+  return isInside(path.resolve(root), path.resolve(target))
+}