@luchenglong/cli-bridge 0.2.8 → 0.2.10

package/mcp/providers/codex.mjs

@@ -0,0 +1,239 @@
+// mcp/providers/codex.mjs — codex MCP 工具面（契约 §4）。
+// framing/生命周期归 keystone 统一服务器 mcp/cli-bridge-mcp.mjs。
+//
+// 与 opencode/agy 面结构同构：直接 spawn codex（CODEX_BIN 覆盖；.js/.mjs 目标经
+// process.execPath 包装，供测试夹具使用）。无 ctx.emit：状态走快照文件
+// {homeDir}/cli-bridge-mcp-codex.json（bridge-kit buildMcpBridgePayload + 原子写 tmp→rename）。
+//
+// codex 面的两处特有事实（实测 codex-cli 0.98.0）：
+//   • 续聊走 `codex exec resume <thread_id> <prompt>`，且 resume **不接受 -C/-s/-o/-add-dir**；
+//     所以 cwd 只由 spawn 的 cwd 决定，argv 里的沙箱经 -c sandbox_mode 落地。
+//   • 模型清单没有 CLI 子命令，只能走 HTTP /models（descriptor 的 codex_models 负责），
+//     这里只做工具面转接，不复制解析逻辑。
+import { spawn as nodeSpawn } from 'node:child_process'
+import { resolve as resolvePath } from 'node:path'
+import { readFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+import defineProvider, { codexResolveExePrefix, codexExeCandidates } from '../../providers/codex.mjs'
+import { codexShimRejectReason } from '../../providers/codex-cli.mjs'
+import { createStatusEngine, createLineStream, buildMcpBridgePayload, isLimited, renderStatus } from '../../core/bridge-kit.mjs'
+import { packageVersion } from '../version.mjs'
+
+export const meta = { id: 'codex', label: 'CODEX', version: packageVersion() }
+
+// ── 统一设置文件分区读（MCP 子进程无 ctx.get，只读 env/文件）───────────────────
+// 与 opencode/mimo 面同规则：注入 descriptor 的 readSettings，使面板里指定的
+// binPath/defaultModel/sandboxMode 在 MCP 形态同样生效（三形态行为一致）。
+const SETTINGS_FILE_NAME = 'cli-bridge-settings.json'
+
+function resolveSettingsFile(env) {
+  try {
+    if (env.CLI_BRIDGE_SETTINGS_FILE) return env.CLI_BRIDGE_SETTINGS_FILE
+    if (env.DSH_HOME) return resolvePath(env.DSH_HOME, SETTINGS_FILE_NAME)
+    if (process.platform === 'win32' && env.APPDATA) return resolvePath(env.APPDATA, 'DSH Desktop', 'dsh-home', SETTINGS_FILE_NAME)
+    if (env.HOME) return resolvePath(env.HOME, '.dsh', SETTINGS_FILE_NAME)
+  } catch (e) { /* 无 env 能力 */ }
+  return null
+}
+
+function readPartition(env) {
+  const p = resolveSettingsFile(env)
+  if (!p) return { partition: null, path: null, home: null }
+  try {
+    const all = JSON.parse(readFileSync(p, 'utf8'))
+    return { partition: (all && typeof all === 'object' && all.codex) ? all.codex : null, path: p, home: dirname(p) }
+  } catch (e) {
+    return { partition: null, path: p, home: dirname(p) }
+  }
+}
+
+const provider = defineProvider({
+  env: process.env,
+  process,
+  nodeChild: { spawn: nodeSpawn },
+  readSettings: () => readPartition(process.env)
+})
+
+let lastIo = null
+function publishSnapshot(snapshot) {
+  const io = lastIo
+  if (!io) return
+  try {
+    const target = io.path.join(io.homeDir, 'cli-bridge-mcp-codex.json')
+    const payload = buildMcpBridgePayload(snapshot, process.pid, Date.now())
+    const tmp = target + '.' + process.pid + '.tmp'
+    try { io.fs.mkdirSync(io.path.dirname(target), { recursive: true }) } catch (e) { /* 目录已存在 */ }
+    io.fs.writeFileSync(tmp, JSON.stringify(payload), 'utf8')
+    io.fs.renameSync(tmp, target)
+  } catch (e) { /* 灯数据尽力而为，绝不影响工具调用 */ }
+}
+
+// provider.engine 在 attach 后才存在；MCP 形态不 attach，用本模块的 engine。
+const engine = createStatusEngine({ provider, publish: publishSnapshot })
+provider.engine = engine
+
+// ── exe / cwd 解析 ────────────────────────────────────────────────────────────
+function exePrefix() {
+  return codexResolveExePrefix(process.env, '')
+}
+
+function resolveCwd(a) {
+  if (a && a.cwd) return resolvePath(String(a.cwd))
+  return process.env.CODEX_BRIDGE_CWD || process.cwd()
+}
+
+function baseResult(over) {
+  return Object.assign({
+    ok: false, status: 'ERROR', response: '', sessionId: null, durationSeconds: null,
+    numTurns: null, totalTokens: null, exitCode: null, mode: 'auto', backend: null, stderr: ''
+  }, over)
+}
+
+// ── spawn（实时折叠走 bridge-kit 行流）────────────────────────────────────────
+function runCodex(args) {
+  return new Promise((resolve) => {
+    const a = args || {}
+    const built = provider.buildArgv(exePrefix(), a, { planActive: false, defaultMode: 'auto' })
+    const cwd = resolveCwd(a)
+    // .cmd/.bat shim：无 shell 的 spawn 解析不了它，走 shell 会二次解释 prompt。
+    const shim = codexShimRejectReason(built.argv[0]) || codexShimRejectReason(built.argv[1])
+    if (shim) {
+      const res = baseResult({ status: 'CODEX_UNAVAILABLE', mode: built.mode, stderr: shim })
+      engine.begin(cwd); engine.end(res, cwd)
+      resolve(res)
+      return
+    }
+    let child
+    try {
+      child = nodeSpawn(built.argv[0], built.argv.slice(1), { cwd, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true })
+    } catch (e) {
+      resolve(baseResult({ status: 'SPAWN_ERROR', mode: built.mode, stderr: String(e && e.message || e) }))
+      return
+    }
+    engine.begin(cwd)
+    let out = ''
+    let err = ''
+    let killed = false
+    const timer = setTimeout(() => { killed = true; try { child.kill() } catch (e) { /* 已退出 */ } }, (built.timeoutSec + 60) * 1000)
+    const stream = createLineStream((ln) => {
+      const t = ln.trim()
+      if (t.charAt(0) !== '{') return
+      try { engine.foldEvent(JSON.parse(t), cwd) } catch (e) { /* 坏行跳过 */ }
+    })
+    child.stdout.on('data', (d) => {
+      out += d
+      if (out.length > 4000000) out = out.slice(-2000000)
+      stream.pushChunk(String(d))
+    })
+    child.stderr.on('data', (d) => { err += d; if (err.length > 1000000) err = err.slice(-500000) })
+    child.on('error', (e) => {
+      clearTimeout(timer)
+      stream.flush()
+      const res = baseResult({ status: 'CODEX_UNAVAILABLE', mode: built.mode, stderr: 'codex spawn failed: ' + String(e && e.message || e) })
+      engine.end(res, cwd)
+      resolve(res)
+    })
+    child.on('close', (code) => {
+      clearTimeout(timer)
+      stream.flush()
+      const outcome = { exitCode: killed ? 124 : code }
+      let res = provider.buildResult(provider.parseJson(out), outcome, built.mode, err, out, null)
+      if (killed && !res.ok) {
+        res.status = 'HUNG_TIMEOUT'
+        res.stderr = (res.stderr ? res.stderr + ' ' : '') + '[killed by DSH timeout guard after ' + built.timeoutSec + 's; if this was a long-running script (build/test) raise timeoutSec]'
+      }
+      engine.end(res, cwd)
+      resolve(res)
+    })
+  })
+}
+
+function textResult(res) {
+  if (res.fallback) {
+    return 'codex unavailable (' + res.reason + '). Use native tools / the local model for this task; do not retry codex.'
+  }
+  const limited = !res.ok && isLimited(res)
+  const head = 'codex ' + (res.ok ? 'OK' : 'FAILED') + ' [status=' + res.status +
+    (res.sessionId ? ' session=' + res.sessionId : '') +
+    (res.totalTokens != null ? ' tokens=' + res.totalTokens : '') + ']'
+  const hint = typeof provider.failureHint === 'function' ? provider.failureHint(res) : ''
+  let note = ''
+  if (limited) note = '\n\n[Note: this looks like a rate-limit / network failure. Do NOT retry codex in a loop; finish the task with your own tools, or ask the user.]'
+  const body = res.response || (res.stderr ? '[stderr] ' + res.stderr : (res.rawStdout ? '[raw] ' + res.rawStdout : ''))
+  return head + (body ? '\n\n' + body : '') + (hint ? '\n\n' + hint : '') + note
+}
+
+// ── 工具面（与描述符同源：名字/schema 一律从 descriptor 取，禁止第二份定义）──────
+function toolList(env) {
+  const d = provider.tools
+  const extra = provider.extraTools || []
+  return [d.run, d.continue, d.status].concat(extra.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })))
+    .map((t) => Object.assign({}, t))
+}
+
+export function tools(env) {
+  return toolList(env)
+}
+
+export async function call(name, args, io) {
+  if (io) lastIo = io
+  if (!lastIo) return 'codex error: MCP io not initialized'
+  const a = args || {}
+  const d = provider.tools
+  if (name === d.status.name) {
+    const snap = provider.statusToolLogic(a)
+    if (a.cwd) {
+      // statusToolLogic 已经按 cwd 过滤并升格顶层字段，这里直接渲染。
+    }
+    return renderStatus(snap, provider)[0].text
+  }
+  if (name === (provider.extraTools[0] && provider.extraTools[0].name)) {
+    const res = await provider.extraTools[0].logic(a)
+    const rendered = provider.extraTools[0].render(a, res)
+    return rendered[0].text
+  }
+  if (!a.prompt || !String(a.prompt).trim()) return 'codex error: prompt is required'
+  const mapped = Object.assign({}, a)
+  if (name === d.continue.name) {
+    // continue 的会话语义：sessionId 优先，否则 latest → exec resume --last。
+    if (!mapped.sessionId && mapped.latest) mapped.continueLatest = true
+  }
+  const res = await runCodex(mapped)
+  return textResult(res)
+}
+
+export function check(env) {
+  const ts = tools(env)
+  const names = ts.map((t) => t.name)
+  for (const t of ts) {
+    if (!t.name || !t.description || !t.inputSchema || t.inputSchema.type !== 'object') throw new Error('codex mcp: bad tool def ' + JSON.stringify(t && t.name))
+  }
+  // MCP 面必须覆盖 descriptor 三件套（名字一致，提示词连续性红线）。
+  for (const k of ['run', 'continue', 'status']) {
+    if (!names.includes(provider.tools[k].name)) throw new Error('codex mcp: tools surface missing descriptor name ' + provider.tools[k].name)
+  }
+  // argv 契约漂移锁（实测 codex-cli 0.98.0 的旗集）。
+  const b = provider.buildArgv(['codex'], { prompt: 'x' }, { planActive: false })
+  for (const f of ['exec', '--json', '--skip-git-repo-check']) {
+    if (b.argv.indexOf(f) < 0) throw new Error('codex mcp: argv contract drift: ' + f)
+  }
+  // ⚠️ codex exec 没有 -a；出现即参数错误（实测 clap: unexpected argument '-a'）。
+  if (b.argv.indexOf('-a') >= 0 || b.argv.indexOf('--ask-for-approval') >= 0) throw new Error('codex mcp: codex exec rejects -a/--ask-for-approval; use -c approval_policy')
+  // resume 子命令不接受 -C/-s/-L：argv 必须改成 -c sandbox_mode。
+  const r = provider.buildArgv(['codex'], { prompt: 'x', sessionId: 'sid-1' }, { planActive: false })
+  for (const f of ['resume', 'sid-1', '--json']) {
+    if (r.argv.indexOf(f) < 0) throw new Error('codex mcp: resume argv contract drift: ' + f)
+  }
+  for (const f of ['-C', '-s', '--add-dir']) {
+    if (r.argv.indexOf(f) >= 0) throw new Error('codex mcp: resume must not emit ' + f + ' (codex exec resume rejects it)')
+  }
+  if (r.argv.indexOf('-c') < 0 || String(r.argv[r.argv.indexOf('-c') + 1] || '').indexOf('sandbox_mode=') < 0) {
+    throw new Error('codex mcp: resume must set the sandbox through -c sandbox_mode')
+  }
+  // 模型清单在 MCP 面必须点名真实端点而非本地目录（红线：不把本地目录冒充实时）。
+  const mt = ts.find((t) => /_models$/.test(t.name))
+  if (!mt) throw new Error('codex mcp: missing codex_models tool')
+  if (!/live/.test(String(mt.description))) throw new Error('codex mcp: codex_models must document the live source')
+  return true
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@luchenglong/cli-bridge",
-  "version": "0.2.8",
-  "description": "CLI Bridge for DeepSeek Harness (DSH): one package bridging four local coding-CLI agents — agy (Google Antigravity CLI), Tencent CodeBuddy Code, Xiaomi MiMo (MiMoCode / MiMo Desktop), and OpenCode. Each provider keeps its own agent preset (cordis-agy / codebuddy-first / cordis-mimo / opencode-first), tools (agy_run / codebuddy_run / mimo_run / opencode_run + continue + status), rate-limit/network fallback dialog, and zero-dependency MCP server, unified under a single home-level status light, one settings file, and one bundle patch. Merges agy-first-bridge, codebuddy-first-bridge and mimo-first-bridge.",
+  "version": "0.2.10",
+  "description": "CLI Bridge for DeepSeek Harness (DSH): one package bridging six local coding-CLI agents — agy (Google Antigravity CLI), Tencent CodeBuddy Code, Xiaomi MiMo (MiMoCode), OpenCode, Claude Code, and OpenAI Codex CLI. Each provider keeps its own agent preset (cordis-agy / codebuddy-first / cordis-mimo / opencode-first / claude-first / codex-first), tools (<id>_run / <id>_continue / <id>_status, plus per-provider model listing), rate-limit/network fallback dialog, and zero-dependency MCP server, unified under a single home-level status light, one settings file, and one bundle patch. Merges agy-first-bridge, codebuddy-first-bridge and mimo-first-bridge.",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -20,10 +20,14 @@
     "./providers/codebuddy": "./providers/codebuddy.mjs",
     "./providers/mimo": "./providers/mimo.mjs",
     "./providers/opencode": "./providers/opencode.mjs",
+    "./providers/claude": "./providers/claude.mjs",
+    "./providers/codex": "./providers/codex.mjs",
     "./preset-agy": "./preset/agy-first/cli-bridge.mjs",
     "./preset-codebuddy": "./preset/codebuddy-first/cli-bridge.mjs",
     "./preset-mimo": "./preset/mimo-first/cli-bridge.mjs",
     "./preset-opencode": "./preset/opencode-first/cli-bridge.mjs",
+    "./preset-claude": "./preset/claude-first/cli-bridge.mjs",
+    "./preset-codex": "./preset/codex-first/cli-bridge.mjs",
     "./package.json": "./package.json"
   },
   "dsh": {

package/preset/claude-first/agent.cordis.yml

@@ -0,0 +1,136 @@
+# 生成物 — 由 node scripts/build.mjs 从 preset/claude-first/plugin-list.mjs 生成，勿手改。
+# legacy 目录形态（$DSH_HOME/.agent-presets/claude-first/）；新 DSH 走声明制
+# （home-plugin/cli-bridge-indicator/lib/preset-declarations.mjs 直接 import 同一源）。
+- id: persona
+  name: '@deepseek-ai/dsh-persona'
+  config:
+    prefix: 'You are a coding agent powered by the {{model}} model.'
+- id: agent-instructions
+  name: '@deepseek-ai/dsh-agent-instructions'
+  config:
+    maxBytes: 65536
+- id: tool-bash
+  name: '@deepseek-ai/dsh-tool-bash'
+  disabled: !!js 'process.platform === ''win32'''
+- id: tool-pwsh
+  name: '@deepseek-ai/dsh-tool-pwsh'
+  disabled: !!js 'process.platform !== ''win32'''
+- id: tool-fs
+  name: '@deepseek-ai/dsh-tool-fs'
+- id: tool-fs-search
+  name: '@deepseek-ai/dsh-tool-fs-search'
+  config:
+    sampleOverCapGlobResults: false
+- id: tool-jobs
+  name: '@deepseek-ai/dsh-tool-jobs'
+- id: skill-filesystem
+  name: '@deepseek-ai/dsh-skill-filesystem'
+- id: tool-skill
+  name: '@deepseek-ai/dsh-tool-skill'
+- id: command-goal
+  name: '@deepseek-ai/dsh-command-goal'
+- id: tool-goal
+  name: '@deepseek-ai/dsh-tool-goal'
+- id: planning
+  name: 'cordis:group'
+  group: true
+  isolate:
+    planMode: true
+  config:
+    - id: plan-mode
+      name: '@deepseek-ai/dsh-plan-mode'
+      config:
+        section: |
+          You are in plan mode. Stay in plan mode until exit_plan_mode succeeds or the user switches the session mode. Imperative language to implement changes means plan the implementation, not execute it. A user's conversational agreement — including an answer confirming something you asked — approves nothing and does not end plan mode; fold the confirmed decision into the plan and submit it through exit_plan_mode.
+
+          Explore first. Use non-mutating reads, searches, static analysis, and checks to ground the plan in the actual repository. Do not edit or write files, change configuration, run formatters or code generation that rewrites tracked files, commit, or otherwise carry out the plan. Prefer existing functions and patterns over new machinery.
+
+          The tool catalog stays the same across modes for request-cache stability. These plan-mode rules override any later tool description or guidance that suggests using mutation tools; those tools remain listed to keep the tool catalog unchanged. Do not use todo_write to track this planning phase: it tracks implementation after an approved plan, while the plan itself belongs in exit_plan_mode.
+
+          Resolve discoverable facts by inspection. Use ask_user_question only for user-owned choices or material ambiguity that inspection cannot answer. Do not ask the user where code lives or how current behavior works when you can find out.
+
+          Make the plan decision-complete: state the goal and success criteria; group implementation changes by subsystem; identify public API, schema, and data-flow changes; cover edge cases, failure modes, tests, acceptance criteria, and explicit assumptions. Keep it concise enough to review but detailed enough that another engineer can implement it without making design decisions.
+
+          When ready, call exit_plan_mode with the complete plan markdown, starting with a # title. Make exit_plan_mode the only and final tool call in that assistant response: it presents the plan for approval, and implementation begins only in a later step after approval. Do not paste the final plan as a plain reply or ask "should I proceed?" through prose or ask_user_question. If review rejects it, incorporate the feedback and present again. If the review channel is unavailable or aborted, stay in plan mode and ask the user to switch modes manually; do not proceed with implementation.
+- id: compaction
+  name: 'cordis:group'
+  group: true
+  isolate:
+    compaction: true
+    toolResultPruner: true
+  config:
+    - id: compaction-basic
+      name: '@deepseek-ai/dsh-compaction-basic'
+    - id: command-compact
+      name: '@deepseek-ai/dsh-command-compact'
+    - id: tool-result-pruner
+      name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
+      config:
+        thresholdChars: 8192
+        headChars: 4096
+        tailChars: 1024
+- id: delegation
+  name: 'cordis:group'
+  group: true
+  isolate:
+    workflowEngine: true
+  config:
+    - id: tool-subagent-control
+      name: '@deepseek-ai/dsh-tool-subagent-control'
+    - id: tool-subagent-list-agents
+      name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
+    - id: tool-subagent
+      name: '@deepseek-ai/dsh-tool-subagent'
+      config:
+        provider: spawn
+        toolName: subagent
+        modelSelectionSettings: true
+    - id: tool-subagent-fork
+      name: '@deepseek-ai/dsh-tool-subagent'
+      config:
+        provider: fork
+        toolName: subagent_fork
+    - id: tool-subagent-codex
+      name: '@deepseek-ai/dsh-tool-subagent'
+      disabled: true
+      config:
+        provider: codex
+        toolName: subagent_codex
+        maxDepth: provider-managed
+    - id: tool-subagent-claude-code
+      name: '@deepseek-ai/dsh-tool-subagent'
+      disabled: true
+      config:
+        provider: claude-code
+        toolName: subagent_claude_code
+        maxDepth: provider-managed
+    - id: workflow-ptc
+      name: '@deepseek-ai/dsh-workflow-ptc'
+      config:
+        provider: spawn
+    - id: tool-workflow
+      name: '@deepseek-ai/dsh-tool-workflow'
+    - id: tool-ralph
+      name: '@deepseek-ai/dsh-tool-ralph'
+      disabled: true
+      config:
+        subagentProvider: spawn
+        maxRounds: 64
+- id: tool-ask-user
+  name: '@deepseek-ai/dsh-tool-ask-user'
+- id: tool-todo
+  name: '@deepseek-ai/dsh-tool-todo'
+  config:
+    allowParallelInProgress: true
+- id: tool-web
+  name: '@deepseek-ai/dsh-tool-web'
+  config:
+    fetch: true
+    searchTimeoutMs: 60000
+- id: present
+  name: '@deepseek-ai/dsh-tool-present'
+- id: tool-plugin-manager
+  name: '@deepseek-ai/dsh-plugin-manager/tools'
+  disabled: true
+- id: cli-bridge-claude
+  name: '@luchenglong/cli-bridge/preset-claude'

package/preset/claude-first/cli-bridge.mjs

@@ -0,0 +1,131 @@
+// preset/claude-first/cli-bridge.mjs — claude-first preset 的桥接插件（preset 宿主形态）。
+//
+// PROVIDER-CONTRACT.md §5：本模块只做「宿主接线」——构造描述符、attach、注册三工具 +
+// claude_models、心跳/事件发布、claude:policy 提示词段。全部执行/状态语义在
+// providers/claude.mjs + core/bridge-kit.mjs。
+//
+// preset id 'claude-first' 由 plugin-list.mjs 单源声明（本文件不含 id 字面量清单）。
+//
+// 本模块是宿主进程内真 ESM：可 import node: 内建与包内相对路径；禁止 import
+// @deepseek-ai/*（解析根够不到 harness 包，历史论证 —— 契约 §8）。
+import { existsSync } from 'node:fs'
+
+import defineProvider, { claudeExeCandidates } from '../../providers/claude.mjs'
+import { POLICY_TEXT } from '../../providers/claude-policy.mjs'
+import { renderResult, renderStatus } from '../../core/bridge-kit.mjs'
+import { isBridgeEnabled } from '../../core/scheduling.mjs'
+import { PROVIDER_IDS } from '../../providers/registry.mjs'
+
+export const name = 'cli-bridge-claude'
+export const inject = ['tools', 'subprocess', 'systemPrompt', 'timer']
+
+const OUTPUT_SCHEMA = { type: 'object', additionalProperties: true }
+
+export function apply(ctx) {
+  // 调度门禁：用户在设置面板关掉 claude → 本形态不注册任何工具/政策段/心跳。
+  // 每次会话装配时现读文件（改设置下次会话即生效，无需重启宿主）；fail-open。
+  if (!isBridgeEnabled('claude', PROVIDER_IDS)) return
+  const subprocess = ctx.subprocess
+  const sandboxPolicy = ctx.get('sandboxPolicy')
+
+  const provider = defineProvider({ process, env: process.env })
+
+  // 状态快照 → 家级灯（keystone 听 'claude/status'，事件是 app 级广播）。
+  function publish(snapshot) {
+    try { ctx.emit('claude/status', { snapshot }) } catch (e) { /* ignore */ }
+  }
+
+  // cwd 兜底：显式 cwd 参数 > env CLAUDE_MCP_CWD > 沙箱 workspaceRoot > process.cwd()。
+  function getCwdFallback() {
+    if (process.env.CLAUDE_MCP_CWD) return String(process.env.CLAUDE_MCP_CWD)
+    if (sandboxPolicy && typeof sandboxPolicy.workspaceRoot === 'string' && sandboxPolicy.workspaceRoot) return sandboxPolicy.workspaceRoot
+    return process.cwd()
+  }
+
+  // 设置面板分区（每次 getSettings 现读 ctx.get，面板改默认模型后下一次调用即生效）。
+  function panelSettings() {
+    try {
+      const s = ctx.get && ctx.get('cliBridgeSettings')
+      return (s && s.claude) || null
+    } catch (e) { return null }
+  }
+
+  // exe 解析优先级（与描述符 claudeExeCandidates 同一套）：
+  //   面板 binPath > env CLAUDE_BIN/CLAUDE_CLI/CLAUDE_CODE_BIN > 已知本地安装 > PATH 名 claude。
+  // .js/.mjs 目标经 process.execPath 包装（返回数组前缀，buildArgv 接受）。
+  // ⚠️ npm 全局安装会在 Windows 给 claude.cmd —— 本形态经 DSH subprocess 启动，.cmd 能否
+  // 执行取决于宿主；探测不到原生 exe 时如实落到 resolveExecutable，失败会明确报
+  // CLAUDE_UNAVAILABLE/SPAWN_ERROR（绝不静默改走别的后端）。
+  const binPathSetting = (() => {
+    const s = panelSettings()
+    const v = s ? s.binPath : ''
+    return typeof v === 'string' ? v : ''
+  })()
+  const exeCandidates = claudeExeCandidates(process.env, binPathSetting)
+
+  async function resolveExe(backend, signal) {
+    for (const c of exeCandidates) {
+      if (!c) continue
+      if (/\.(mjs|cjs|js)$/i.test(c)) return [process.execPath, c]
+      try { if (existsSync(c)) return c } catch (e) { }
+    }
+    return await subprocess.resolveExecutable('claude', undefined, signal)
+  }
+
+  provider.attach({
+    ctx, subprocess, resolveExe, getCwdFallback, publish,
+    getSettings: () => {
+      const s = panelSettings()
+      return s && typeof s === 'object' ? s : {}
+    }
+  })
+
+  // 宣告 claude 优先模式：家级灯据此决定常驻显示（presetActive）。挂载即宣告 +
+  // 每 30s 心跳续租（TTL 75s，契约 §2）。
+  function announceMode() {
+    try {
+      const sid = (ctx.session && ctx.session.id) || ctx.sessionId || null
+      ctx.emit('claude/mode', sid ? { active: true, sessionId: sid } : { active: true })
+    } catch (e) { /* ignore */ }
+  }
+  announceMode()
+  try { const t = ctx.setInterval ? ctx.setInterval(announceMode, 30000) : null; if (t && ctx.effect) ctx.effect(() => () => { try { t() } catch (e) {} }) } catch (e) {}
+
+  // ── 工具注册（执行进描述符三逻辑 + extraTools）──────────────────────────────
+  ctx.effect(() => ctx.tools.register({
+    name: provider.tools.run.name,
+    description: provider.tools.run.description,
+    parameters: provider.tools.run.inputSchema,
+    output: { schema: OUTPUT_SCHEMA, render: (args, value) => renderResult(value, provider) },
+    execute: (args, exec) => provider.runToolLogic(args, exec)
+  }))
+  ctx.effect(() => ctx.tools.register({
+    name: provider.tools.continue.name,
+    description: provider.tools.continue.description,
+    parameters: provider.tools.continue.inputSchema,
+    output: { schema: OUTPUT_SCHEMA, render: (args, value) => renderResult(value, provider) },
+    execute: (args, exec) => provider.continueToolLogic(args, exec)
+  }))
+  ctx.effect(() => ctx.tools.register({
+    name: provider.tools.status.name,
+    description: provider.tools.status.description,
+    parameters: provider.tools.status.inputSchema,
+    output: { schema: OUTPUT_SCHEMA, render: (args, value) => renderStatus(value, provider) },
+    execute: (args) => provider.statusToolLogic(args)
+  }))
+  for (const et of provider.extraTools || []) {
+    ctx.effect(() => ctx.tools.register({
+      name: et.name,
+      description: et.description,
+      parameters: et.inputSchema,
+      output: { schema: OUTPUT_SCHEMA, render: et.render || ((args, value) => renderResult(value, provider)) },
+      execute: (args, exec) => et.logic(args, exec)
+    }))
+  }
+
+  ctx.effect(() => ctx.systemPrompt.section({
+    name: 'claude:policy',
+    order: (typeof ctx.systemPrompt.getSectionOrder === 'function' ? ctx.systemPrompt.getSectionOrder('TOOL_SUBAGENT') : 2800) + 10,
+    text: POLICY_TEXT
+  }))
+}

package/preset/claude-first/plugin-list.mjs

@@ -0,0 +1,28 @@
+// preset/claude-first/plugin-list.mjs — claude-first 预设的单源插件清单（PROVIDER-CONTRACT §5）。
+//
+// = 官方 standard 基线（standard-base.mjs）+ claude 桥接行 + persona 差异。
+// preset id 'claude-first'：本包新增 provider，无旧包兼容包袱，id 直接用 provider id + '-first'
+// （与 opencode-first 同构；cordis-agy / cordis-mimo 的 cordis-* 前缀是旧包历史遗留，不可套用）。
+import { standardPluginRows, bridgeRow } from '../standard-base.mjs'
+
+export const meta = {
+  id: 'claude-first',
+  name: 'Claude Code 执行代理',
+  description: '完整编码 Agent（standard 全部能力），额外提供 claude_run/claude_continue 工具并注入"claude 优先"策略：各种模式下先把实现、编辑、调试、构建、跨文件排查派给本机 Claude Code CLI（DSH 完全控制、claude 无提示改文件、默认后台执行），原生工具仅用于只读查询与最终验证。模型清单以服务端权威探测为准（claude_models）。',
+  order: 50
+}
+
+export function buildPlugins(deps) {
+  const rows = standardPluginRows()
+  // persona 段：prefix 必填；**不设 suffix** —— DSH 只注册 provider/model 两个提示词变量，
+  // 写 {{cwd}} 会在组装期抛 unknown prompt variable，使整个预设不可用（工作目录由
+  // working-directory 服务以不插值的用户上下文提供）。
+  const persona = rows.find((r) => r.id === 'persona')
+  if (persona && persona.config) {
+    persona.config.prefix = 'You are a coding agent powered by the {{model}} model.'
+    delete persona.config.suffix
+  }
+  // 桥接行：第二参数由 build（scripts/build.mjs）注入裸包说明符，绝不在这里写死路径。
+  rows.push(bridgeRow('claude', deps && deps.bridgeName))
+  return rows
+}

package/preset/claude-first/preset.yml

@@ -0,0 +1,3 @@
+name: Claude Code 执行代理
+description: '完整编码 Agent（standard 全部能力），额外提供 claude_run/claude_continue 工具并注入"claude 优先"策略：各种模式下先把实现、编辑、调试、构建、跨文件排查派给本机 Claude Code CLI（DSH 完全控制、claude 无提示改文件、默认后台执行），原生工具仅用于只读查询与最终验证。模型清单以服务端权威探测为准（claude_models）。'
+order: 50