multi-agent-pi

Imported from zhufangzhou/multi-agent-pi (AGENTS.md). Install upstream with npx skills add zhufangzhou/multi-agent-pi. Copyright stays with the author.

Repository Guidelines

Project Overview

multi-agent-pi is an oh-my-pi extension (/ma-pi slash command) that dispatches tasks to a multi-agent team from a full-page TUI dashboard. The team runtime is built directly on the omp SDK (@oh-my-pi/pi-coding-agent):

• every team member is an omp AgentSession with subagent semantics (taskDepth: 1, parentTaskPrefix: "ma-pi"), tools whitelisted to read/bash/hub, and IRC enabled
• inter-agent messaging rides omp's process-global IrcBus via the built-in hub tool (P2P by id, to:"all" broadcast, auto-wake of idle recipients) — the old self-built MessageBus is gone
• teams are designed on demand: an orchestrator session (one structured LLM call, enforced via the SDK's outputSchema + yield tool) picks the roles for each task; DEFAULT_TEAM in src/team.ts is only the fallback
• a fixed reporter agent summarizes the team's final outcome once every worker settles

The runtime runs in a daemon subprocess (bun src/daemon.ts) spawned by the omp host, isolated from the host's own agent loop and session files; DaemonClient proxies it over stdio JSON-RPC. Sessions persist per working directory under ~/.omp/ma-pi/sessions/<cwd-slug>/<runId>/ and are resumable.

Architecture & Data Flow

┌─ omp host ────────────────────────────────────────────────┐
│ extension.ts  /ma-pi → ctx.ui.custom(MaPiPage, overlay)   │
│   resolveModelOptions: ctx.model + ctx.modelRegistry      │
│ page.ts       MaPiPage — pi-tui Component, 5-zone layout  │
│ client.ts     DaemonClient — stdio JSON-RPC proxy         │
└──────┬────────────────────────────────────────────────────┘
       │ Bun.spawn (MA_PI_MODEL_OPTS, MA_PI_RESUME)
┌──────▼────────────────────────────────────────────────────┐
│ daemon.ts     JSON-lines command loop + throttled snapshots│
│ controller.ts DomainController (orchestrator + team)       │
│   └─ @oh-my-pi/pi-coding-agent: createAgentSession,        │
│      ModelRegistry, SessionManager, IrcBus (hub tool)      │
│ persist.ts    state.json + <agent>.jsonl under ~/.omp/…    │
└────────────────────────────────────────────────────────────┘

Data flow:

1. /ma-pi resolves the current omp session's model (ctx.model, ctx.modelRegistry.getApiKey) → ModelOptions passed to the daemon via MA_PI_MODEL_OPTS (env fallback: OPENAI_API_KEY/OPENAI_MODEL/ OPENAI_BASE_URL)
2. DaemonClient spawns src/daemon.ts (same cwd as the user's project) and sends init; the daemon answers {type:"ready"} then pushes throttled (200 ms) {type:"snapshot"} events
3. DomainController.dispatch(task) has the orchestrator design a team (structured yield result; manual JSON parse only as fallback), spawns one AgentSession per member, and runs them in parallel
4. #attachSession subscribes to session events (message_start, message_update, tool_execution_*, irc_message, message_end, agent_end) and mirrors them into DomainSnapshot for the TUI
5. A 400 ms polling loop (startPolling) tracks session.isStreaming, marks auto-woken agents idle, and fires the reporter once all workers settle
6. Every state change schedules a debounced (400 ms) atomic state.json write; agent transcripts are JSONL session files owned by the SDK's SessionManager (resume = SessionManager.open)

Key Files

Development Commands

npx tsc --noEmit            # typecheck (only static check)
source .env && bun src/smoke.ts          # E2E dispatch (needs OPENAI_API_KEY etc.)
source .env && bun src/smoke-resume.ts   # E2E resume of the newest saved run

Both smoke scripts are the regression gate after upgrading the SDK or changing the controller: upgrade the pinned @oh-my-pi/* versions, run typecheck, then both smokes (they use a real provider, minutes each).

Code Conventions

• Naming: camelCase functions/variables, PascalCase classes/types, kebab-case filenames; event type discriminants snake_case (message_start, tool_execution_end, irc_message)
• Structured output: the orchestrator's design call uses the SDK's outputSchema (requireYieldTool) with a JTD schema (TEAM_DESIGN_SCHEMA, incl. the team goal + success criteria and per-role scope/deliverable/dependsOn); validated payloads arrive on tool_execution_end for yield (result.details.data). parseJsonObject
  • normalizeSpec remain as fallback/defense-in-depth
• Team design: designPrompt grades tasks by difficulty — simple → 2 agents single path, linear → pipeline, open-ended/hard → 2-4 agents in the SAME stage exploring mutually exclusive approaches (diversity is the point), plus a later synthesizer/comparator that depends on ALL of them. dependsOn lists each agent's upstreams (same or earlier stage only); normalizeStages repairs violations by pushing a consumer past its latest upstream (bubble until stable) and tags every roster entry [stage N]
• Convergence: MESSAGING_GUIDANCE bans acknowledgement/thanks-only replies and has agents stop once their deliverable is out; the designed goal/done criteria are injected into every dispatch prompt and the reporter ends its summary with a COMPLETION: verdict line
• Session lifecycle: team sessions are spawned per run and disposed on abort/switch; the orchestrator session lives for the controller's lifetime. dispose() flushes JSONL — the daemon exit path must await it
• Persistence: state.json (atomic tmp+rename) + <agentId>.jsonl; deliberately NOT ~/.omp/agent/sessions/… and always suppressBreadcrumb: true, so ma-pi never hijacks omp's own /resume picker or --continue breadcrumb. /export zips the whole run (sessions/*.jsonl, state.json, communication.json|md, manifest.json, handoffs/*.md) into <cwd>/ma-pi-export-<runId>.zip
• Cross-stage handoff: after each turn the controller writes the agent's latest deliverable to <cwd>/.ma-pi/handoffs/<runId>/<agentId>.md; later-stage prompts inject the file list (path + one-line preview) and the agents read the files with the read tool, so rework updates are always current. Dispatch prompts annotate the roster with [stage N] tags and forbid messaging later-stage teammates (not yet joined — sends would fail); IRC is reserved for same-stage collaboration and rework loops: an earlier-stage agent stays live and can be asked to fix its handoff, and a later-stage finding triggers a rework round via IRC
• Isolation: daemon sessions use disableExtensionDiscovery: true (no user omp extensions in the team), but the SDK still auto-discovers the project's context files (AGENTS.md), skills, and rules from cwd
• Error handling: runAgent-style retry is not used; the controller relies on SDK auto-retry/fallback. Esc-abort disposes sessions and treats the resulting rejections as expected (#abortRequested)

Dependency Surface (@oh-my-pi/*, pinned exact, currently 17.2.9)

Deep imports (…/modes/theme/mermaid-cache, …/tools/render-utils, …/extensibility/slash-commands) are internal paths — re-verify with typecheck + smokes on every SDK upgrade. page.ts mirrors a few omp internals (streaming-reveal constants, getMarkdownTheme recipe) — replace with the public API if omp ever exports them.

Testing & QA

• No test framework — the two smoke scripts are the tests
• monitor-test/messaging-test/implicit-test from the old multi-agent-pi library are gone (no multi-agent-pi dependency anymore)
• Smoke tests require real LLM API keys from .env (OPENAI_API_KEY, OPENAI_MODEL, OPENAI_BASE_URL)