From 882a362643d57aae2af77baa34f35d55a5331df3 Mon Sep 17 00:00:00 2001 From: Cleo0415 Date: Tue, 17 Nov 2026 11:19:34 +0000 Subject: [PATCH] feat(osm): dispatch worker sessions via HAPI MCP when running in HAPI Add hapi-mcp.md and route /osm:research, /osm:plan, /osm:impl, and /osm:review through mcp__hapi__spawn_peer and mcp__hapi__ping_peer when available so workers run as linked HAPI sessions, falling back to codeagent-wrapper outside HAPI or with --no-hapi-mcp. --- AGENTS.md | 2 +- README.md | 1 + README.zh-CN.md | 1 + src/utils/__tests__/hapi-mcp-dispatch.test.ts | 40 +++++++++++++++++++ templates/commands/impl.md | 4 ++ templates/commands/plan.md | 2 + templates/commands/research.md | 2 + templates/commands/review.md | 2 + templates/prompts/claude/hapi-mcp.md | 25 ++++++++++++ 9 files changed, 78 insertions(+), 1 deletion(-) create mode 100644 src/utils/__tests__/hapi-mcp-dispatch.test.ts create mode 100644 templates/prompts/claude/hapi-mcp.md diff --git a/AGENTS.md b/AGENTS.md index de79b5b..1c715b6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,7 +7,7 @@ Install OpenSlime to provide minimal Claude-led multi-agent collaboration on Ope What the installation writes: - `~/.claude/commands/osm/` (slash commands) - `~/.claude/skills/ccg/` (on-demand skills) -- `~/.claude/.ccg/{config.toml,prompts/}` +- `~/.claude/.ccg/{config.toml,prompts/}` (includes Claude dispatch helpers `osm-report.md`, `osm-ledger.md`, and `hapi-mcp.md`) - `~/.claude/rules/ccg-codegraph.md` - `~/.claude/bin/codeagent-wrapper` - `~/.claude/bin/osm` (decision-ledger launcher; runs this checkout's `bin/ccg.mjs` with the installing Node) diff --git a/README.md b/README.md index df2737c..8bbebc1 100644 --- a/README.md +++ b/README.md @@ -87,6 +87,7 @@ Manual steps: [AGENTS.md](AGENTS.md). - **Scoped writers.** In `/osm:impl`, `codex` writes backend, logic and tests, and `antigravity` writes UI. Each task lists the files its writer may touch. - **Claude supervises.** It fixes behaviour-preserving slips of ≤5 lines itself and re-runs `VERIFY`. Anything bigger goes back to the writer via `resume`; after two failed tries it asks you before taking over. - **Always cross-checked.** Research, plan and review run codex and antigravity in separate fresh sessions, and Claude compares where they agree and where they don't. +- **HAPI peer dispatch.** Inside a HAPI session with `mcp__hapi__spawn_peer`, `/osm:*` automatically dispatches workers via HAPI MCP (`waitForReply: true`, mapping `antigravity` to `agy`) so subagent chats appear as linked child sessions; `--no-hapi-mcp` or running outside HAPI falls back to `codeagent-wrapper`. - **Stage report.** Every run ends with a report in `${TMPDIR:-/tmp}/osm-reports/` that includes a confidence estimate (High/Medium/Low, %). ## Ledger reference diff --git a/README.zh-CN.md b/README.zh-CN.md index 25432c3..521136e 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -90,6 +90,7 @@ Install OpenSlime from https://github.com/Overbaker/OpenSlime. Follow AGENTS.md - 更大的改动通过 `resume` 退回给执行者。 - 同一执行者失败两次后,先问你再决定是否接管。 - **始终交叉校验。** research、plan、review 都让 codex 和 antigravity 各自在新会话里独立完成,由 Claude 对比两者一致和分歧的地方。 +- **HAPI 会话联动。** 在可用 `mcp__hapi__spawn_peer` 的 HAPI 会话内,`/osm:*` 会自动通过 HAPI MCP 派发并等待回传(`antigravity` 映射为 `agy`),让子代理成为可直达的父子关联会话;传入 `--no-hapi-mcp` 或处于 HAPI 外部时回退到 `codeagent-wrapper`。 - **阶段报告。** 每次运行结束都在 `${TMPDIR:-/tmp}/osm-reports/` 生成一份报告,附带置信度(高/中/低,百分比)。 ## 账本细节 diff --git a/src/utils/__tests__/hapi-mcp-dispatch.test.ts b/src/utils/__tests__/hapi-mcp-dispatch.test.ts new file mode 100644 index 0000000..41e8cf5 --- /dev/null +++ b/src/utils/__tests__/hapi-mcp-dispatch.test.ts @@ -0,0 +1,40 @@ +import { readFileSync } from 'node:fs' +import { tmpdir } from 'node:os' +import fs from 'fs-extra' +import { join } from 'pathe' +import { describe, expect, it } from 'vitest' +import { getAllCommandIds, installWorkflows } from '../installer' +import { PACKAGE_ROOT } from '../installer-template' + +const readTemplate = (rel: string) => readFileSync(join(PACKAGE_ROOT, 'templates', rel), 'utf8') + +describe('HAPI MCP dispatch integration', () => { + it('installs hapi-mcp.md next to osm-ledger.md with ~/.claude rewritten', async () => { + const installDir = join(tmpdir(), `osm-hapi-mcp-${Date.now()}`, '.claude') + await fs.ensureDir(join(installDir, 'bin')) + await fs.writeFile( + join(installDir, 'bin', 'codeagent-wrapper'), + '#!/usr/bin/env node\nconsole.log("codeagent-wrapper version 5.16.0")\n', + { mode: 0o755 }, + ) + + await installWorkflows(getAllCommandIds(), installDir, true, { mcpProvider: 'skip' }) + + const installedGuide = readFileSync(join(installDir, '.ccg', 'prompts', 'claude', 'hapi-mcp.md'), 'utf8') + expect(installedGuide).toContain('mcp__hapi__spawn_peer') + expect(installedGuide).toContain(`${installDir}/.ccg/prompts/`) + + for (const cmd of ['research', 'plan', 'impl', 'review']) { + const commandDoc = readFileSync(join(installDir, 'commands', 'osm', `${cmd}.md`), 'utf8') + expect(commandDoc).toContain(`${installDir}/.ccg/prompts/claude/hapi-mcp.md`) + } + }, 60_000) + + it('keeps hapi-mcp guidance outside wrapper heredocs', () => { + for (const cmd of ['research', 'plan', 'impl', 'review']) { + const raw = readTemplate(`commands/${cmd}.md`) + expect(raw).toContain('hapi-mcp.md') + expect(raw).toContain('--no-hapi-mcp') + } + }) +}) diff --git a/templates/commands/impl.md b/templates/commands/impl.md index 0eff786..89b6a38 100644 --- a/templates/commands/impl.md +++ b/templates/commands/impl.md @@ -50,6 +50,8 @@ description: 'codex/antigravity 按任务写代码,Claude 监控审查 + 归 **工作目录**:`{{WORKDIR}}` **必须通过 Bash 执行 `pwd`(Unix)或 `cd`(Windows CMD)获取当前工作目录的绝对路径**,禁止从 `$HOME` 或环境变量推断。如果用户通过 `/add-dir` 添加了多个工作区,先确定任务相关的工作区。 + - **HAPI session dispatch**: When `mcp__hapi__spawn_peer` is in your tool list (and `$ARGUMENTS` lacks `--no-hapi-mcp`), read `~/.claude/.ccg/prompts/claude/hapi-mcp.md` once and dispatch/resume writers via `mcp__hapi__spawn_peer` / `mcp__hapi__ping_peer` (`waitForReply: true`) instead of `codeagent-wrapper` so workers run as linked HAPI sessions. + For each task (independent tasks with disjoint files may go in one `--parallel` batch; use `dependencies:` for ordering): ``` ~/.claude/bin/codeagent-wrapper --progress --backend <{{BACKEND_PRIMARY}}|{{FRONTEND_PRIMARY}}> {{GEMINI_MODEL_FLAG}}{{GROK_MODEL_FLAG}}{{KIMI_MODEL_FLAG}}{{OPENCODE_MODEL_FLAG}}- "{{WORKDIR}}" <<'EOF' @@ -80,6 +82,8 @@ description: 'codex/antigravity 按任务写代码,Claude 监控审查 + 归 - **Lesson probe** (see osm-ledger.md): do not use the two prompts below. Use the neutral A/B prompts in osm-ledger.md step 5: no workdir, and none of the words main or comparison. Hold Step 5 fixes until the probe is scored. On a tie the main side lands. - With `--compare explore`, wait for both writers, then substitute the recorded absolute comparison worktree path and base commit into BOTH reviewer prompts below. Both reviewers must inspect both candidates before selection; without comparison, omit the comparison candidate instructions. + - **HAPI session dispatch**: When `mcp__hapi__spawn_peer` is in your tool list (and `$ARGUMENTS` lacks `--no-hapi-mcp`), use `mcp__hapi__spawn_peer` (`waitForReply: true`, see `~/.claude/.ccg/prompts/claude/hapi-mcp.md`) instead of `codeagent-wrapper`. + **Step 6.1**: Launch the calls below in ONE message: **FIRST Bash call ({{BACKEND_PRIMARY}})**: diff --git a/templates/commands/plan.md b/templates/commands/plan.md index 460a731..e2dfd56 100644 --- a/templates/commands/plan.md +++ b/templates/commands/plan.md @@ -27,6 +27,8 @@ description: 'codex + antigravity 交叉分析 → 消除歧义 → 零决策可 - Always run both {{BACKEND_PRIMARY}} and {{FRONTEND_PRIMARY}}, launched in ONE message with `run_in_background: true`. They answer independently; Claude cross-checks where they agree and disagree. - **工作目录**:`{{WORKDIR}}` **必须通过 Bash 执行 `pwd`(Unix)或 `cd`(Windows CMD)获取当前工作目录的绝对路径**,禁止从 `$HOME` 或环境变量推断。如果用户通过 `/add-dir` 添加了多个工作区,先确定任务相关的工作区。 + - **HAPI session dispatch**: When `mcp__hapi__spawn_peer` is in your tool list (and `$ARGUMENTS` lacks `--no-hapi-mcp`), read `~/.claude/.ccg/prompts/claude/hapi-mcp.md` once and dispatch both models via `mcp__hapi__spawn_peer` (`waitForReply: true`) instead of `codeagent-wrapper` so workers run as linked HAPI sessions. + **Step 2.1**: Launch the calls below in ONE message: **FIRST Bash call ({{BACKEND_PRIMARY}})**: diff --git a/templates/commands/research.md b/templates/commands/research.md index a66df04..7128d55 100644 --- a/templates/commands/research.md +++ b/templates/commands/research.md @@ -52,6 +52,8 @@ description: '需求 → 约束集(codex + antigravity 交叉探索 + OpenSpec } ``` + - **HAPI session dispatch**: When `mcp__hapi__spawn_peer` is in your tool list (and `$ARGUMENTS` lacks `--no-hapi-mcp`), read `~/.claude/.ccg/prompts/claude/hapi-mcp.md` once and dispatch both models via `mcp__hapi__spawn_peer` (`waitForReply: true`) instead of `codeagent-wrapper` so workers run as linked HAPI sessions. + **Step 4.1**: Launch the calls below in ONE message: **FIRST Bash call ({{BACKEND_PRIMARY}} — backend boundaries)**: diff --git a/templates/commands/review.md b/templates/commands/review.md index 004ca32..8501a19 100644 --- a/templates/commands/review.md +++ b/templates/commands/review.md @@ -29,6 +29,8 @@ description: 'codex + antigravity 独立会话交叉审查 → Critical 必须 - Always run both {{BACKEND_PRIMARY}} and {{FRONTEND_PRIMARY}}, launched in ONE message with `run_in_background: true`. They answer independently; Claude cross-checks where they agree and disagree. - **工作目录**:`{{WORKDIR}}` **必须通过 Bash 执行 `pwd`(Unix)或 `cd`(Windows CMD)获取当前工作目录的绝对路径**,禁止从 `$HOME` 或环境变量推断。如果用户通过 `/add-dir` 添加了多个工作区,先确定任务相关的工作区。 + - **HAPI session dispatch**: When `mcp__hapi__spawn_peer` is in your tool list (and `$ARGUMENTS` lacks `--no-hapi-mcp`), read `~/.claude/.ccg/prompts/claude/hapi-mcp.md` once and dispatch both fresh reviewers via `mcp__hapi__spawn_peer` (`waitForReply: true`) instead of `codeagent-wrapper` so review sessions link to the parent session. + **Step 3.1**: Launch the calls below in ONE message: **FIRST Bash call ({{BACKEND_PRIMARY}})**: diff --git a/templates/prompts/claude/hapi-mcp.md b/templates/prompts/claude/hapi-mcp.md new file mode 100644 index 0000000..76c86f9 --- /dev/null +++ b/templates/prompts/claude/hapi-mcp.md @@ -0,0 +1,25 @@ +# HAPI MCP peer dispatch (Claude) + +Read this once per stage when `mcp__hapi__spawn_peer` (or `spawn_peer`) is present in your tool list and `$ARGUMENTS` does not include `--no-hapi-mcp`. + +Running inside HAPI gives external models first-class, inspectable HAPI sessions linked under this session. Outside HAPI (or if peer tools are disabled/unavailable, or the opt-out flag is set), fall back to `codeagent-wrapper`. + +## Backend flavor map +- `antigravity` -> `agy` +- `codex`, `claude`, `grok`, `kimi`, `opencode`, `pi` -> unchanged +- `gemini` -> retired from HAPI creatable flavors; keep on `codeagent-wrapper` + +## Fresh calls (`research`, `plan`, `review`, initial `impl` task) +1. Keep the exact brief and any `ROLE_FILE`: if a step references `~/.claude/.ccg/prompts//.md`, read that file first and prepend its instructions to the peer remit. +2. Call `mcp__hapi__spawn_peer` with: + - `directory`: resolved `` + - `agent`: mapped HAPI flavor + - `name`: concise stage label such as `osm::` + - `message`: the full role instructions and stage brief + - `waitForReply`: `true` +3. For parallel stages (`codex` + `antigravity`), emit both `spawn_peer` calls in ONE message, then end your turn and wait for HAPI to deliver both replies automatically (do not poll). +4. Save each returned `sessionId` instead of a wrapper `SESSION_ID`. + +## Follow-up fixes (`resume` in `/osm:impl`) +- Call `mcp__hapi__ping_peer` with `sessionIdPrefix` set to the saved child `sessionId`, `message` carrying `file:line`, problem, and expected result, `wake: true`, and `waitForReply: true`. End your turn to receive the reply. +- If a writer fails or peer tools are disabled mid-run, retry once or fall back to `codeagent-wrapper` with the exact same brief.