@mdsohail99/opencode-agent-teams 0.0.0-stage → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (100) hide show
  1. package/AGENTS.md +123 -0
  2. package/CHANGELOG.md +137 -0
  3. package/LICENSE +21 -0
  4. package/README.md +350 -2
  5. package/agents/orchestrators/agent-teams.md +198 -0
  6. package/agents/orchestrators/ai-data.md +91 -0
  7. package/agents/orchestrators/backend.md +109 -0
  8. package/agents/orchestrators/devops.md +89 -0
  9. package/agents/orchestrators/frontend.md +117 -0
  10. package/agents/orchestrators/qa.md +89 -0
  11. package/agents/orchestrators/security.md +98 -0
  12. package/agents/orchestrators-fork/orchestrator-agent-teams.md +203 -0
  13. package/agents/specialists/accessibility-auditor.md +322 -0
  14. package/agents/specialists/ai-engineer.md +152 -0
  15. package/agents/specialists/ai-generated-code-security-auditor.md +213 -0
  16. package/agents/specialists/api-platform-engineer.md +169 -0
  17. package/agents/specialists/api-tester.md +311 -0
  18. package/agents/specialists/application-security-engineer.md +497 -0
  19. package/agents/specialists/backend-architect.md +242 -0
  20. package/agents/specialists/brand-guardian.md +327 -0
  21. package/agents/specialists/cloud-security-architect.md +526 -0
  22. package/agents/specialists/code-reviewer.md +83 -0
  23. package/agents/specialists/codebase-archaeologist.md +347 -0
  24. package/agents/specialists/codebase-onboarding-engineer.md +180 -0
  25. package/agents/specialists/compliance-auditor.md +165 -0
  26. package/agents/specialists/data-engineer.md +312 -0
  27. package/agents/specialists/data-visualization-engineer.md +158 -0
  28. package/agents/specialists/database-optimizer.md +183 -0
  29. package/agents/specialists/database-reliability-engineer.md +169 -0
  30. package/agents/specialists/desktop-app-engineer.md +211 -0
  31. package/agents/specialists/developer-tooling-engineer.md +160 -0
  32. package/agents/specialists/devops-automator.md +380 -0
  33. package/agents/specialists/finops-engineer.md +160 -0
  34. package/agents/specialists/frontend-developer.md +230 -0
  35. package/agents/specialists/git-workflow-master.md +91 -0
  36. package/agents/specialists/image-prompt-engineer.md +242 -0
  37. package/agents/specialists/incident-responder.md +443 -0
  38. package/agents/specialists/incident-response-commander.md +448 -0
  39. package/agents/specialists/inclusive-visuals-specialist.md +78 -0
  40. package/agents/specialists/internationalization-engineer.md +191 -0
  41. package/agents/specialists/iot-fleet-engineer.md +155 -0
  42. package/agents/specialists/llm-post-training-engineer.md +172 -0
  43. package/agents/specialists/mcp-builder.md +254 -0
  44. package/agents/specialists/minimal-change-engineer.md +213 -0
  45. package/agents/specialists/mobile-app-builder.md +498 -0
  46. package/agents/specialists/multi-agent-systems-architect.md +593 -0
  47. package/agents/specialists/payments-billing-engineer.md +201 -0
  48. package/agents/specialists/penetration-tester.md +405 -0
  49. package/agents/specialists/performance-benchmarker.md +273 -0
  50. package/agents/specialists/persona-walkthrough-specialist.md +275 -0
  51. package/agents/specialists/privacy-engineer.md +159 -0
  52. package/agents/specialists/prompt-engineer.md +208 -0
  53. package/agents/specialists/rag-pipeline-engineer.md +435 -0
  54. package/agents/specialists/rapid-prototyper.md +467 -0
  55. package/agents/specialists/reality-checker.md +240 -0
  56. package/agents/specialists/realtime-collaboration-engineer.md +194 -0
  57. package/agents/specialists/rust-refactoring-specialist.md +320 -0
  58. package/agents/specialists/search-relevance-engineer.md +244 -0
  59. package/agents/specialists/secrets-credential-hygiene-engineer.md +182 -0
  60. package/agents/specialists/section-508-accessibility-specialist.md +338 -0
  61. package/agents/specialists/security-architect.md +310 -0
  62. package/agents/specialists/software-architect.md +119 -0
  63. package/agents/specialists/sre-site-reliability-engineer.md +97 -0
  64. package/agents/specialists/technical-writer.md +398 -0
  65. package/agents/specialists/test-automation-engineer.md +186 -0
  66. package/agents/specialists/test-results-analyzer.md +310 -0
  67. package/agents/specialists/threat-detection-engineer.md +540 -0
  68. package/agents/specialists/ui-designer.md +388 -0
  69. package/agents/specialists/ui-finish-gate-reviewer.md +220 -0
  70. package/agents/specialists/uswds-developer.md +339 -0
  71. package/agents/specialists/ux-architect.md +474 -0
  72. package/agents/specialists/ux-researcher.md +334 -0
  73. package/agents/specialists/video-streaming-engineer.md +157 -0
  74. package/agents/specialists/visual-storyteller.md +155 -0
  75. package/agents/specialists/web-gis-developer.md +115 -0
  76. package/agents/specialists/webassembly-engineer.md +163 -0
  77. package/agents/specialists/wechat-mini-program-developer.md +356 -0
  78. package/agents/specialists/whimsy-injector.md +444 -0
  79. package/agents/specialists/workflow-architect.md +590 -0
  80. package/bin/cli.js +351 -0
  81. package/bin/install.mjs +418 -0
  82. package/bin/lib/config-root.mjs +51 -0
  83. package/bin/lib/merge-commands.mjs +138 -0
  84. package/bin/lib/merge-env-flags.mjs +92 -0
  85. package/bin/lib/merge-schema.mjs +77 -0
  86. package/bin/lib/merge-subagent-depth.mjs +133 -0
  87. package/bin/lib/plugin-park.mjs +48 -0
  88. package/bin/lib/relay-process.mjs +116 -0
  89. package/bin/lib/runtime-state.mjs +118 -0
  90. package/bin/menu.mjs +582 -0
  91. package/bin/uninstall.mjs +360 -0
  92. package/package.json +50 -4
  93. package/src/index.ts +115 -0
  94. package/src/state/tracker.ts +102 -0
  95. package/src/tools/broadcast.ts +58 -0
  96. package/src/tools/delegate.ts +154 -0
  97. package/src/tools/status.ts +25 -0
  98. package/src/tools/terminate.ts +70 -0
  99. package/src/tui.ts +9 -0
  100. package/src/worktree/manager.ts +142 -0
package/AGENTS.md ADDED
@@ -0,0 +1,123 @@
1
+ <!-- agent-teams-orchestration:start -->
2
+ # Department Team-Lead Orchestration (Agent-Teams pattern)
3
+
4
+ The agent system is organized as departments, each led by an orchestrator (team lead):
5
+ Frontend, Backend, Security, DevOps, AI & Data, QA. Each lead fans out to its own
6
+ sub-agent team via the Task tool. Leads are `mode: all` (Tab-switchable + Task-launchable).
7
+
8
+ TWO MODES:
9
+ - **Normal mode (any agent except Agent-Teams):** the ACTIVE agent is the main agent
10
+ of its session. If you are a department lead, your "main agent" is whoever spawned
11
+ you (Agent-Teams or the active Tab agent) — escalate to THAT, not to a global "supervisor".
12
+ - **Agent-Teams mode:** Agent-Teams IS the main agent/router of the session. It
13
+ receives escalations from its teams and routes to fixers itself (it can launch any
14
+ agent). It reports the final result to the user.
15
+
16
+ ## OpenCode 1.18.34+ Native Hierarchical Depth (`subagent_depth = 2`)
17
+ OpenCode 1.18.34+ natively supports nested subagents up to `subagent_depth = 2` (configured in `config.json` via `"subagent_depth": 2`):
18
+ - **Depth 0 (Root Orchestrator):** `Agent-Teams` (or active Tab session) orchestrates high-level departmental workflows.
19
+ - **Depth 1 (Department Leads):** Department Leads (`Frontend`, `Backend`, `Security`, `DevOps`, `AI & Data`, `QA`) receive departmental goals and launch their specialists via nested `Task` tool calls.
20
+ - **Depth 2 (Department Specialists):** Domain specialists (e.g. `Frontend Developer`, `Database Optimizer`, `API Tester`) execute focused implementation, testing, or auditing tasks.
21
+ - **Stock Agent Compatibility:** The built-in `build` agent remains untouched as the standard single-task primary agent; multi-agent hierarchical fan-out applies when the user selects `Agent-Teams`.
22
+
23
+ ## Core rule: hub-and-spoke — NO lead launches another lead
24
+ - Each orchestrator's `permission.task` allowlist contains ONLY its own team members.
25
+ Leads cannot launch other leads (this is mechanically enforced).
26
+ - If a lead needs another department, it returns a structured escalation in this format:
27
+ `ESCALATE: <department> | WHAT: <need> | WHERE: <file/module> | CONTEXT: <what it did + what the other team must know>`
28
+ - ESCALATE EARLY: return the escalation as soon as the blocker is detected, not after
29
+ finishing all work — the receiving main agent starts the fixer while you continue
30
+ unblocked work.
31
+
32
+ ## You are the MAIN AGENT (Agent-Teams or Build) — how to handle escalations
33
+ 1. When any sub-agent's result contains `ESCALATE: <dept> | ...`, parse it.
34
+ 2. Decide the owner:
35
+ - Is that department's lead ALREADY running (an active/prior task_id in this session)?
36
+ → Route the escalation to THAT existing lead (resume its task_id with the context).
37
+ - Not running → spawn that lead via the Task tool with the escalation as its prompt.
38
+ 3. NEVER spawn a second instance of a department lead that's already running —
39
+ reusing the running lead prevents two writers editing the same module (conflict).
40
+ 4. Hand the resolution back to the originating team so it can continue.
41
+ 5. Keep a running mental registry of which leads are active in this session.
42
+
43
+ ## Visible Parallel Batch `Task` Fan-Out (Recommended Visible Mode)
44
+ On Stock OpenCode, the premier execution mode for `Agent-Teams` (and whenever visual transparency is preferred) is **Visible Parallel Batch Task Fan-Out**:
45
+ - **Batch Concurrent Emission**: When independent departmental workstreams exist (e.g. Frontend UI, Backend API, QA verification), `Agent-Teams` emits all `Task` tool calls **concurrently in the same assistant turn** (omitting `background: true`). Parameters: `Task(subagent_type="<Lead>", description="<Short description>", prompt="<Detailed prompt>")`.
46
+ - **Interactive TUI UX**: OpenCode renders live interactive `│ Task` widgets with animated spinners, live toolcall indicators (`↳ Edit src/...`, `↳ Run pytest`), and one-click inspection directly in the main TUI timeline.
47
+ - **Nested Visibility (`subagent_depth = 2`)**: Department Leads (Depth 1) also dispatch their Specialists (Depth 2) via nested `Task` tool calls, maintaining live visibility down through the subagent tree.
48
+
49
+ ## Fan-out is ESCALATION-DRIVEN by default — main agent may parallelize when it fits
50
+ The DEFAULT for single-agent sessions (or when departments have sequential dependencies) is one lead at a time: spawn a lead, and only spawn another department when a running lead escalates and explicitly requests it. This is correct whenever the cross-department dependency is only discovered DURING the work (e.g. QA finds a backend bug mid-testing). Concurrency is produced by the RESUME pattern, not by pre-spawning teams.
51
+
52
+ ### When the main agent MAY parallelize (spawn leads in the same message)
53
+ Parallel spawn is allowed when the main agent can already see, from the user's
54
+ request, that two departments have INDEPENDENT work that can run at the same time
55
+ with no write conflict — e.g. frontend UI + backend API are both clearly needed AND
56
+ touch different modules. Use judgment: if the tracks are coupled or one waits on the
57
+ other, do NOT parallelize — use the default one-lead + escalation flow instead.
58
+
59
+ ### The default flow — single-lead with on-demand escalation
60
+ 1. Main agent spawns the ONE lead whose task is the user's request (e.g. QA).
61
+ 2. The lead does all its independent work, then returns `ESCALATE: <dept> | ...`
62
+ only if it actually hit a blocker requiring another department.
63
+ 3. ONLY THEN does the main agent spawn (or resume) the requested department lead.
64
+ 4. When the fix returns, the main agent resumes the requesting lead to finish.
65
+
66
+ ### Yield-and-resume (how concurrency happens without pre-spawning)
67
+ When a lead escalates mid-task:
68
+ 1. Lead does all work that does NOT depend on the other department (e.g. QA runs
69
+ all tests except test X), then returns early with
70
+ `ESCALATE: <dept> | ... | CONTEXT: I've done A,B,C; only X is blocked`.
71
+ It does NOT block or wait — its session ends cleanly (main agent keeps task_id).
72
+ 2. Main agent, in ONE parallel batch, BOTH:
73
+ - resumes the requesting lead's task_id ("keep going on anything else you can; X pending"), AND
74
+ - spawns the needed lead ("fix X for the QA team").
75
+ If the requesting lead has no more independent work, skip the resume and only spawn.
76
+ 3. When the fixing lead returns, main agent resumes the requesting lead's task_id
77
+ with the fix → it finishes the blocked item.
78
+ 4. Never keep a lead idle: if a lead can do more work while another department fixes
79
+ its blocker, RESUME it to keep working rather than leaving it paused.
80
+ 5. When the escalation is a mid-task discovery (like our QA → Backend test case),
81
+ do NOT start both leads together — the dependent lead starts first, escalates,
82
+ and only then is the second lead spawned. Parallel spawn is reserved for work
83
+ the main agent can see is independent from the start.
84
+
85
+ ### Resumption discipline & Deterministic Error Recovery
86
+ - Resuming a lead by `task_id` preserves its session context — it knows what it already did.
87
+ - **Deterministic Error Resumption Format**: When a subagent fails, encounters a timeout, or throws an unhandled error, OpenCode returns:
88
+ ```
89
+ Subagent failed (task_id: <id>): <error>
90
+ ```
91
+ The orchestrator extracts `<id>` and calls `Task(task_id="<id>", prompt="<instruction explaining the failure, fix, or recovery path>")`. This continues the **exact same subagent session**, preserving all previously executed tool calls, code diffs, conversation history, and working memory.
92
+ - Multiple Task calls in one message run concurrently (proven: 20 subagents in parallel).
93
+ - Escalation is non-destructive: the lead's independent output is kept; only the blocked
94
+ item waits.
95
+
96
+ ### Async fan-out plugin (agent-teams, relay-backed)
97
+ For true async fan-out (react to the FIRST finisher while others still run), use the
98
+ `agent-teams` plugin tools. The plugin is a thin HTTP proxy to a per-instance relay
99
+ server (an external opencode SDK client):
100
+ - `running_agents` — launch N sub-agent sessions in the background in parallel (non-blocking, UNLIMITED
101
+ count). Returns session IDs immediately. Results return to the caller (chain preserved).
102
+ - `next_agent` — block until ONE running session finishes; return its result.
103
+ Other sessions keep running. Call repeatedly to drain results as each finishes.
104
+ - `agents_status` — non-blocking snapshot of all running sessions' status/output. Use periodically to check execution progress across team members.
105
+
106
+ **Multi-instance safety:** one relay per opencode server instance. Each opencode
107
+ TUI/session has a unique serverUrl; the relay port is derived from that URL, so
108
+ every terminal/project/session gets its own isolated relay. Multiple opencode
109
+ sessions can run simultaneously and each spawns its own sub-agent teams.
110
+ The main agent keeps working independently while its team sub-agents run.
111
+
112
+ Used by leads to fan out their team, and by the main agent when it manages multiple
113
+ in-flight leads and needs to react to the first finisher. Sub-agents never report to
114
+ the main agent directly — always follow the chain: sub-agent -> lead -> main agent.
115
+
116
+ ## One-writer-per-module discipline
117
+ When a lead delegates a file/module to another department (via escalation), that
118
+ module's ownership transfers. The originating lead must NOT edit the same module
119
+ until the other department returns it. Apply this in all dispatch prompts.
120
+
121
+ ## If true parallel teams are needed
122
+ Use separate git worktrees (one per department), not parallel writers on the same files.
123
+ <!-- agent-teams-orchestration:end -->
package/CHANGELOG.md ADDED
@@ -0,0 +1,137 @@
1
+ # Changelog
2
+
3
+ All notable changes to **`opencode-agent-teams-relay`** will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v1.0.0.html).
7
+
8
+ ---
9
+
10
+ ## [1.0.8] - 2026-10-10
11
+
12
+ ### Added
13
+ - **OpenCode 1.18.34+ Stock Native Hierarchical Depth (`subagent_depth = 2`):** Configured natively at root in `opencode.json` across both `full` and `agents` install modes, enabling Depth 0 (Root Orchestrator) → Depth 1 (Department Leads) → Depth 2 (Specialists) out of the box on upstream stock OpenCode.
14
+ - **Visible Parallel Batch Task Mode:** Optimized orchestrators to emit concurrent `Task` calls in the same assistant turn. OpenCode natively renders live interactive `│ Task` widgets with animated spinners and toolcall indicators (`↳ Edit src/...`).
15
+ - **Swarm Slash Command Palette:** Injected `/tree`, `/report`, `/ask`, `/resume`, `/stop`, and `/errors` commands into `opencode.json` for live ASCII org-chart tracking, mid-flight worker steering, and emergency stopping.
16
+ - **Fast-Path Capability Probing:** Modernized `probeInlineSupport()` in `plugins/agent-teams.ts` to query `/experimental/capabilities` directly instead of creating throwaway `__agent_teams_subtask_probe__` sessions, eliminating the 5-second startup lag and ghost session leaks on SQLite.
17
+ - **Native Git Worktree Sandboxing:** Integrated `relay/agent-teams-relay.mjs` with OpenCode 1.18.34+ native worktree endpoints (`POST /experimental/worktree/create` and `remove`), allocating isolated git sandboxes per mutating task to prevent write collisions.
18
+ - **Deterministic Error Resumption:** Standardized `Task(task_id="<id>", prompt="...")` for recovering failed tasks (`Subagent failed (task_id: <id>): <error>`), preserving all accumulated context, tools, and code diffs.
19
+ - **Total Sandbox & XDG Isolation:** Set `$env:XDG_CONFIG_HOME` in sandbox and test launcher scripts to guarantee 100% clean isolation from machine-global user profile configs.
20
+
21
+ ### Fixed
22
+ - **Subagent Completion Stall Resolution:** Added a synthetic tool-action summary fallback in `readSessionOutput()` (`relay/agent-teams-relay.mjs`) when turns conclude with tool executions (`edit`, `write`, `bash`) rather than conversational text. Unblocks the `session.idle` handler and routes the session to `done` immediately.
23
+ - **Resilient 404 Notification Queue Handling:** Implemented a 3-attempt retry loop with 4-second backoff in `drainParentNotifications()` (`relay/agent-teams-relay.mjs`). Prevents transient 404 responses during parent status checks or `promptAsync` delivery from permanently deleting the orchestrator's notification queue.
24
+ - **Cross-Session Target Scoping in Resume & Restart:** Passed `parentID: context.sessionID` in `resume_agent` and `manage_agents restart` (`plugins/agent-teams.ts`) and configured default resume prompts (`"Resume and continue from where you left off."`). Resolves targets strictly to the current active session, preventing accidental resumption of stale historical ghost agents.
25
+ - **Session Preservation on Operator Kill:** Replaced `deleteServerSession` with `abortServerSession` across `manage_agents kill` and `kill_all` (`relay/agent-teams-relay.mjs`). Aborts in-flight execution upstream while preserving SQLite session records and WAL history intact for subsequent resumption.
26
+ - **Enriched Out-of-Band `/ask` Snapshots:** Formatted tool calls, arguments, outputs, and thinking snippets into the ephemeral transcript snapshot in `agent-teams-relay.mjs`, ensuring operator inquiries reflect active background work and tool execution rather than appearing idle.
27
+
28
+ ## [1.0.6] - 2026-09-04
29
+
30
+ ### Added
31
+ - **Reactive Orchestrator Protocol (`orchestrator-agent-teams.md`):** Mandated non-blocking fanout where the Main Orchestrator dispatches department leads asynchronously via `Task(background=true)` and immediately yields the turn to the user (permanently preserving terminal interactivity). Forbids calling `next_agent` in foreground turns.
32
+ - **File Touch Scope Protocol:** Adds explicit decision rules for worktree isolation: `worktree: true` when subagents touch shared files (`package.json`, shared schemas); `worktree: false` for disjoint directories or read-only tasks to eliminate disk I/O and temporary git branch overhead.
33
+ - **Swarm Management & Side Query Directives:** Equipped the Orchestrator with `agents_status` (hierarchical tree snapshots and stall detection), `manage_agents` (`kill`, `kill_all`, `inspect`, `restart`), and `ask_agent` for out-of-band side queries.
34
+ - **Autonomous Department Leads (Level 1 Depth):** Upgraded all 6 Department Leads (`Backend`, `Frontend`, `DevOps`, `QA`, `AI & Data`, `Security`) to autonomous middle managers that supervise specialists in background worktrees, run compile/typecheck/test verification gates inside department sandboxes, and report consolidated outcomes upward.
35
+
36
+ ### Fixed
37
+ - **Root `subagent_depth` Schema Alignment:** Configured `subagent_depth = 2` directly at the root level of `opencode.json` in `bin/lib/merge-subagent-depth.mjs` and `install.ps1` to align with the official OpenCode V2 schema (`https://opencode.ai/config.json`) and SDK types. Eliminates editor schema validation warnings (`Property subagent_depth is not allowed`) while auto-migrating any misplaced `experimental.subagent_depth` back to root and pruning empty `experimental` blocks.
38
+
39
+ ## [1.0.5] - 2026-09-03
40
+
41
+ ### Fixed
42
+ - **OpenCode V2 Subagent Depth Alignment:** Updated installer logic (`bin/lib/merge-subagent-depth.mjs` and `install.ps1`) to configure `experimental.subagent_depth = 2` matching the official OpenCode V2 (`v1.18.x+`) schema (`https://opencode.ai/config.json`).
43
+ - **Legacy Config Auto-Migration:** Automatically detects legacy root `subagent_depth` in existing user configs, migrates it into `experimental.subagent_depth`, and removes the root key to eliminate schema validation errors while preserving custom user values and existing experimental keys.
44
+
45
+ ## [1.0.4] - 2026-08-20
46
+
47
+ ### Added
48
+ - **Durable WAL + checkpoint state store.** The relay persists its entire picture of the world (`nodes`, `teams`, plus an append-only `events` diary) to `<state-dir>/agent-teams-relay.wal` (append-only write-ahead log) with periodic atomic checkpoints to `<state-dir>/agent-teams-relay-state.json` — every state transition is mirrored transactionally, and a relay that is killed and restarted replays its full state, including completed results, drained flags, and retry budgets. The in-memory Maps remain the runtime source of truth for logic; the store survives restarts. (`relay/agent-teams-relay.mjs`)
49
+ - **Full-instance visibility (`/reconcile`).** A new plugin-side **supervisor loop** (started at plugin load, not on tool calls) checks relay health every 10s, respawns a dead relay, and pushes the opencode server's *entire* live session list to the relay's new `/reconcile` endpoint — so the relay tracks every session on the instance (including human-started ones), not just children it spawned itself, and corrects drifted statuses. (`plugins/agent-teams.ts`, `relay/agent-teams-relay.mjs`)
50
+ - **Confirmed-deletion cascade.** Deletion is now triggered **only** by a confirmed parent deletion — either the SSE `session.deleted` event or a parent missing from two consecutive reconciliation passes *and* an explicit `session.get` returning 404. Unreachability is never treated as deletion. Pending `/await-any` waiters are resolved with `disposed` status; child sessions are deleted with an audit trail in the `events` diary.
51
+ - **30-day confirmed-orphan sweep.** A low-frequency safety net (`ORPHAN_SWEEP_INTERVAL_MS`, default 24h cadence) revisits stale nodes but only cascades them through the same confirmed-deletion gate — never on age alone.
52
+ - **Event-diary retention.** The append-only `events` table is pruned on boot and on the maintenance tick (default 24h): rows older than 90 days are removed (`EVENT_RETENTION_DAYS` to override, e.g. for tests).
53
+ - **`/resume` + `resume_agent` tool.** Any existing, still-alive session can receive a follow-up instruction and continue with its accumulated context; status/drained/result reset and a fresh completion promise is registered so `next_agent`/`agents_status` pick it back up. Network failure to the upstream server returns `502 upstream_unreachable` (never treated as "not found").
54
+ - **Per-agent failure isolation.** Retry budgets are now **per-node** (`retry_count`, capped at 3): one agent exhausting its budget goes `error` with a `needs_attention` event while every sibling keeps working. The global circuit breaker is reserved solely for SSE-transport failures; `/reset-circuit {sessionID}` revives a single node's budget. (`relay/agent-teams-relay.mjs`)
55
+ - **Test suite growth:** 28 automated tests (relay lifecycle, reconcile, cascade, orphan sweep, resume, failure isolation, installer scenarios 1–6) via `node --test`.
56
+
57
+ ### Changed
58
+ - **Architectural Upgrade: Replaced HTTP Heartbeat Polling with OS Kernel Process Supervision.** Relays no longer issue `GET /global/health` probes over local HTTP connections to check parent liveness. Instead, the plugin passes `PARENT_PID` to the relay, which monitors the parent OpenCode Process ID directly via OS Kernel liveness checks (`process.kill(parentPid, 0)`). Zero false-positive relay exits during CPU or AI spikes. As long as the parent OpenCode process exists in the OS process table, the relay stays 100% alive indefinitely (even if idle for days). The moment the user closes the parent OpenCode application or terminal, the kernel monitor detects process termination (`ESRCH`) and shuts down the relay immediately. (`relay/agent-teams-relay.mjs`, `plugins/agent-teams.ts`)
59
+ - **Single config root + disabled-plugin parking.** Both install modes now target `~/.config/opencode` — one config world, no more separate `.config/ocd` for agents-only. In `agents` (native-fork) mode the plugin is **parked** into `plugins-disabled/agent-teams.ts`, outside the core's `{plugin,plugins}/*.{ts,js}` autodiscovery, so the fork's compiled-in `Task`/`next_agent`/`agents_status` run collision-free (no tool collision between the plugin and the native fork). `full` mode restores it into `plugins/`, removes any parked copy, and strips stale `subagent_depth`. Legacy `.config/ocd` installs are still auto-detected for reinstall/uninstall. (`bin/install.mjs`, `bin/menu.mjs`, `bin/uninstall.mjs`, `install.ps1`, `bin/lib/config-root.mjs`, new `bin/lib/plugin-park.mjs`)
60
+ - **Runtime floor raised to `node >= 20.19`** (for the WAL + checkpoint durable store). (`package.json`)
61
+ - **State & Runtime Cleanup Alignment:** Synchronized runtime state allowlists across `bin/lib/runtime-state.mjs` and `install.ps1` to cover the WAL + checkpoint state files (`agent-teams-relay.wal`, `agent-teams-relay-state.json` and transient `.tmp` variants) and temporary tokens (`token.tmp`).
62
+ - `scripts/test-relay-cascade.mjs` replaces the obsolete `test-relay-dispose.mjs` integration script.
63
+
64
+ ### Removed
65
+ - `/dispose` endpoint and `evictStale()` (the 30-minute TTL eviction) — both replaced by the confirmed-deletion cascade above. Nothing is ever deleted automatically without a confirmed parent deletion.
66
+
67
+ ### Fixed
68
+ - **Auxiliary-server split-brain on startup.** When the real opencode server wasn't answering yet at plugin load (boot race), the plugin immediately spawned a second `opencode serve` and pointed the relay at it — the relay silently watched the wrong server while `/reconcile` pushes to the real one failed. The upstream probe now retries (~5s window) before any auxiliary fallback, the fallback is logged when it does happen, and the supervisor **self-heals**: once pushes reach the real server again, an aux-backed relay is killed and respawned on the real URL (lossless — the WAL + checkpoint store replays state). (`plugins/agent-teams.ts`)
69
+ - **Relay heartbeat exit threshold raised from 12 → 36 (3 minutes) and made env-tunable.** Previously, aux-backed relays (spawned when the real opencode upstream was down) exited after only 12 × 5 s = 60 seconds of upstream unreachability. Under heavy parallel AI workloads, the aux `opencode serve` process becomes transiently unreachable for longer than 60 s, causing the relay to self-terminate. The plugin then re-ran `ensureRelay`, found the upstream still down, and spawned a *new* aux server on a new random port — triggering a new relay on a new port. Every cycle broke `next_agent`'s long-poll connection. 8+ relay/aux pairs were created in a single session. Default is now 36 failures (3 minutes). `HEARTBEAT_MAX_FAILURES` env var allows custom tuning without code changes. (`relay/agent-teams-relay.mjs`)
70
+ - **`next_agent` now retries `/await-any` up to 5 times across relay restarts.** When the relay is respawned mid-poll the HTTP connection drops. The execute handler now retries with a 2 s pause + `ensureRelay` health re-check between attempts, so a relay that restarted and recovered its persisted state is found on the next attempt. (`plugins/agent-teams.ts`)
71
+ - **`reconcileMissedCompletions` called immediately at relay boot.** Previously this ran only after the SSE event stream connected (which can take several seconds). An `/await-any` call arriving in that window could block to timeout even if sub-agents already finished while the relay was down. Now the recovery runs right after `openDatabase()` / `loadDurableState()` so persisted completions are resolved before the first tool call is served. (`relay/agent-teams-relay.mjs`)
72
+ - **Relay health check no longer gates on `eventsReady`.** `/health` now always returns `ok: true` when the relay process is alive (i.e. it responded). `eventsReady` remains in the payload as an informational field about the SSE stream. Previously, any transient SSE reconnect caused the plugin's `health()` check to return `false`, which deleted the relay cache entry and tried to respawn a relay that was already running — a duplicate that then immediately exited on `EADDRINUSE`. (`relay/agent-teams-relay.mjs`, `plugins/agent-teams.ts`)
73
+ - **Ghost `__agent_teams_subtask_probe__` sessions no longer appear in the session list.** `probeVersionFastPath()` now conservatively returns `tooOld: true` whenever the core version cannot be determined (endpoint unhealthy, no `version` field, unparseable string, or network error). On stock opencode 1.2.27 the version is not published on `/global/health`, so the fast-path now short-circuits before creating any throwaway session — the probe session creation is skipped entirely. (`plugins/agent-teams.ts`)
74
+ - **Probe session DELETE is delayed 5 s.** When the full probe path does run (native fork ≥ 1.18.x), the `finally` cleanup now waits 5 seconds before issuing the DELETE. An immediate DELETE on a session that just received `prompt_async` fails silently on some cores, leaving a ghost session in the list. The delay gives the session time to reach idle. (`plugins/agent-teams.ts`)
75
+ - **Relay reconcile skips probe sessions.** `handleReconcileSessions()` now filters out any session whose title is `__agent_teams_subtask_probe__` before folding it into the node tree. Previously these sessions accumulated in the relay's durable store across restarts and triggered unnecessary status-API polling on every reconcile pass. (`relay/agent-teams-relay.mjs`)
76
+ - **Fixed `serverUrl` undefined hashing to port 25821 on startup.** Added `isValidServerUrl()` validation to prevent attempting relay startup or spawning auxiliary servers on undefined server URLs. (`plugins/agent-teams.ts`)
77
+
78
+ ---
79
+
80
+ ## [1.0.3] - 2026-08-09
81
+
82
+ ### Changed
83
+ - **Mode-aware config directory:** the installer now targets `.config/ocd` in `agents` mode (native fork) and `.config/opencode` in `full` mode (stock opencode), so both modes can coexist on the same machine without clobbering each other's state. (`bin/install.mjs`, `install.ps1`)
84
+ - `install.ps1` uses `$PSScriptRoot` for the package root and `$USERPROFILE` first for the home dir (more robust under non-standard shells).
85
+
86
+ ### Fixed
87
+ - **Mode-aware `subagent_depth` merge in `install.ps1`:** `full` mode now strips a stale `subagent_depth` key instead of writing it (the stock core rejects the unrecognized key and refuses to start); `agents` mode creates `opencode.json` with `subagent_depth=2` when missing.
88
+ - **Hidden console on Windows:** the relay process now spawns a hidden console at startup (`hide_console.ps1`), so the background relay no longer pops a terminal window.
89
+
90
+ ---
91
+
92
+ ## [1.0.2] - 2026-08-07
93
+
94
+ ### Added
95
+ - README: **"Performance & Measured Impact"** section — real measured numbers from an in-repo orchestration run (18 concurrent sessions, ~15 min wall-clock to synthesis, 8 concurrent escalations), with explicit **measured vs modeled** labeling and the honest tokens-for-throughput trade-off.
96
+
97
+ ---
98
+
99
+ ## [1.0.1] - 2026-08-07
100
+
101
+ ### Fixed
102
+ - `subagent_depth` merge is now **mode-aware**: the key is only applied in `agents` mode (native fork core, which understands it). `full` mode (stock opencode core) no longer writes it — the stable core rejects `subagent_depth` as an unrecognized key and refuses to start. Full-mode installs/reverts also **strip** a stale `subagent_depth` to self-heal configs broken by an earlier agents-mode install.
103
+
104
+ ---
105
+
106
+ ## [1.0.0] - 2026-08-07
107
+
108
+ Initial public release — async department-lead orchestration and parallel sub-agent relay for OpenCode.
109
+
110
+ ### Added
111
+ - 🚀 **Async Parallel Fan-Out:** `running_agents` tool launches unlimited child sessions in parallel without freezing the OpenCode TUI; results collected with `next_agent` (drain) / `agents_status` (snapshot).
112
+ - 📡 **Detached SDK Relay Engine:** External Node.js background process (relay/agent-teams-relay.mjs) connecting via `@opencode-ai/sdk`, tracking `session.idle` / `session.error` events via SSE.
113
+ - 🏢 **7 Department Leads & 67 Specialists:** Pre-configured orchestrators (`Agent-Teams`, `Frontend`, `Backend`, `Security`, `DevOps`, `AI & Data`, `QA`) routing tasks to specialized domain agents.
114
+ - ⚡ **Management by Exception:** Unblocked work digests silently; blockers trigger immediate escalations so fixer leads dispatch in parallel.
115
+ - 🛡️ **Relay Resilience & Self-Healing:**
116
+ - Heartbeat tolerates transient upstream blips (5 consecutive failures before exit) instead of dying on a single one.
117
+ - Stale-team eviction never deletes teams with running/undrained children.
118
+ - Plugin re-probes relay health on every tool call and respawns a dead relay.
119
+ - Token persisted atomically (tmp+rename+fsync, `0o600`) after a successful listen; capped exponential reconnect backoff; missed completions reconciled on resubscribe.
120
+ - 🔄 **Auto-Continue on Transient Provider Errors:** `reasoning_content ... must be passed back` (DeepSeek thinking mode), `AI_JSONParseError` / `JSON parsing failed`, and `[503] request queue is full` are automatically resumed with a minimal "continue" prompt instead of failing the task (bounded retries, genuine failures still surface).
121
+ - 🧵 **Inline Sub-Agent Mode:** `running_agents({ inline: true })` renders a child as a native `│ Task` widget with automatic fallback to the relay path on cores that don't support subtask parts.
122
+ - ⚙️ **Two-Mode Installer:** `full` (agents + AGENTS.md + plugin + relay + npm dep) and `agents` / `--agents-only` (agents + AGENTS.md only, for native-fork users). Writes a `.installed-mode` marker.
123
+ - 🗑️ **Mode-Aware Uninstall:** removes only the artifacts the installed mode manages; preserves other user plugins, `opencode.json`, `package.json`, and `node_modules`. `status` reports the installed mode.
124
+ - 📦 **Safe Installer:** non-destructive with full timestamped backups, rollback, and marked-block `AGENTS.md` merging; keeps the last 5 backups.
125
+ - 🔒 **Shared-Secret Security:** 32-byte token authentication; unique hash-derived relay ports per server URL (20000–50000) for multi-session isolation.
126
+
127
+ ### Changed
128
+ - `install.ps1` is mode-aware (`-AgentsOnly`).
129
+ - README documents installation modes; `MANIFEST.txt` lists both.
130
+
131
+ ### Removed
132
+ - (n/a — initial release)
133
+
134
+ ### Fixed
135
+ - Relay no longer exits on a single transient upstream heartbeat failure.
136
+ - Token file no longer world-readable, and is written only after the relay is listening (no clobber on port collisions).
137
+ - Sub-agent sessions hitting transient provider errors resume automatically instead of dying.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to sunshine conditions below:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.