opencode-swarm-plugin 0.43.0 → 0.44.1

package/docs/planning/ADR-009-oh-my-opencode-patterns.md

@@ -1,353 +0,0 @@
-# ADR-009: Patterns from oh-my-opencode
-
-## Status
-
-Proposed
-
-## Context
-
-[oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode) by **code-yeongyu** is the most feature-rich OpenCode plugin in the wild (2961★). After deep analysis of its architecture, we identified several patterns that would significantly strengthen our swarm coordination.
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                                                                 │
-│   "Standing on the shoulders of giants"                        │
-│                                                                 │
-│   oh-my-opencode innovations we're adopting:                   │
-│   • 7-Section Delegation Protocol                              │
-│   • Compaction Context Injection                               │
-│   • Preemptive Compaction (80% threshold)                      │
-│   • Event + Polling Hybrid for completion detection            │
-│   • Parallel Execution Minimums                                │
-│   • Context-Safe Tool Limits                                   │
-│                                                                 │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### What oh-my-opencode Does Well
-
-1. **Agent System** - Factory-based registry with model-specific configs, BackgroundManager for async execution, structured delegation prompts
-2. **21 Lifecycle Hooks** - Compaction handling, session recovery, think-mode auto-switching, external hook protocol
-3. **Background Agents** - Event + polling hybrid, todo-aware completion, fire-and-forget abort
-4. **LSP/AST Tools** - Zero-config LSP integration, 11 code intelligence tools, context-safe limits
-5. **Claude Code Compatibility** - Dual-path config loading, 4 independent loaders, auto-migration
-6. **Plugin Architecture** - Hook mapping pattern, session-scoped state, graceful degradation
-
-### What We Already Have
-
-- Swarm Mail for inter-agent messaging
-- File reservations for conflict prevention
-- UBS scan on completion
-- Hive for work item tracking
-- Worktree isolation (ADR-007)
-- Structured review (ADR-007)
-
-### Gaps This ADR Addresses
-
-1. **Coordinator prompts lack structure** - Workers sometimes go rogue
-2. **Context compaction loses critical info** - Decomposition strategy, dependency graph forgotten
-3. **No preemptive compaction** - Sessions die at 100% instead of gracefully compacting at 80%
-4. **Polling-only completion detection** - Slower than event-driven
-5. **No parallel execution enforcement** - Researchers call tools sequentially
-6. **Tool outputs can explode context** - No hard limits on results
-
-## Decision
-
-### 1. 7-Section Delegation Protocol
-
-Adopt oh-my-opencode's structured delegation format for coordinator → worker handoffs:
-
-```markdown
-## TASK
-[Specific task description]
-
-## EXPECTED OUTCOME
-[What success looks like]
-
-## REQUIRED SKILLS
-[Domain knowledge needed]
-
-## REQUIRED TOOLS
-[Tools the worker should use]
-
-## MUST DO
-- [Non-negotiable requirements]
-- [Quality gates]
-
-## MUST NOT DO
-- [Forbidden approaches]
-- [Anti-patterns to avoid]
-
-## CONTEXT
-[Shared context from coordinator]
-[Dependency information]
-[What other workers are doing]
-```
-
-**Implementation:** Update `swarm_subtask_prompt` to generate this format.
-
-**Why:** Reduces rogue behavior. Workers have clear boundaries and success criteria.
-
-### 2. Compaction Context Injection
-
-Preserve critical information through context compaction by injecting a structured prompt BEFORE the summarization API call:
-
-```markdown
-## 1. User Requests (As-Is)
-[Exact wording of original requests - preserved verbatim]
-
-## 2. Final Goal
-[End result expected from this session]
-
-## 3. Work Completed
-[Files modified, features implemented, problems solved]
-
-## 4. Remaining Tasks
-[Pending items, follow-ups, blocked work]
-
-## 5. MUST NOT Do
-[Forbidden approaches, failed attempts, anti-patterns discovered]
-
-## 6. Swarm State (if applicable)
-[Epic ID, completed subtasks, in-progress workers, dependency graph]
-```
-
-**Implementation:** Add `experimental.session.compacting` hook that injects this prompt.
-
-**Why:** Currently compaction loses decomposition strategy, dependency graph, and failed approaches. Workers repeat mistakes.
-
-### 3. Preemptive Compaction
-
-Monitor token usage and trigger compaction at 80% threshold instead of waiting for overflow:
-
-```typescript
-// In chat.message or message.updated hook
-const usageRatio = totalTokens / contextLimit;
-if (usageRatio >= 0.8 && !compactionInProgress.has(sessionID)) {
-  compactionInProgress.add(sessionID);
-  await ctx.client.session.summarize({ ... });
-  
-  // Auto-resume after compaction
-  setTimeout(() => {
-    ctx.client.session.promptAsync({ parts: [{ text: "Continue" }] });
-  }, 500);
-}
-```
-
-**Configuration:**
-```json
-{
-  "preemptive_compaction": {
-    "enabled": true,
-    "threshold": 0.8,
-    "cooldown_seconds": 300
-  }
-}
-```
-
-**Why:** Prevents context overflow mid-work. Coordinators and workers survive long-running epics.
-
-### 4. Event + Polling Hybrid for Completion Detection
-
-Currently we only poll for worker completion. Add event-driven detection as primary path:
-
-```typescript
-// Primary: Event-driven (fast)
-event: async ({ event }) => {
-  if (event.type === "session.idle") {
-    const todos = await client.session.todo();
-    if (todos.length === 0) {
-      markWorkerComplete(event.properties?.info?.id);
-    }
-  }
-}
-
-// Fallback: Polling (reliable)
-setInterval(() => {
-  for (const worker of runningWorkers) {
-    const status = await client.session.status(worker.sessionID);
-    if (status.type === "idle") {
-      // Same completion logic
-    }
-  }
-}, 2000);
-```
-
-**Why:** Events are faster. Polling catches missed events. Hybrid = reliable + fast.
-
-### 5. Parallel Execution Minimums
-
-Enforce minimum parallel tool calls for researcher agents:
-
-```markdown
-## PARALLEL EXECUTION REQUIREMENTS
-
-You MUST launch multiple tools simultaneously in your first action.
-Never call tools sequentially unless output depends on prior result.
-
-Minimum parallel calls by request type:
-- TYPE A (conceptual): 3+ tools (context7 + pdf-brain + websearch)
-- TYPE B (implementation): 4+ tools (repo-autopsy + grep + ast-grep + read)
-- TYPE C (comprehensive): 6+ tools (all of the above)
-
-WRONG:
-1. Search for X
-2. Wait for result
-3. Search for Y
-
-RIGHT:
-[Search X | Search Y | Search Z] → single response
-```
-
-**Implementation:** Add to `swarm-researcher` agent prompt. Enforce via output validation.
-
-**Why:** Sequential tool calls waste round-trips and burn context. Parallel = faster + cheaper.
-
-### 6. Context-Safe Tool Limits
-
-Add hard limits and truncation reporting to tools that can explode context:
-
-| Tool | Limit | Truncation Message |
-|------|-------|-------------------|
-| `repo-autopsy_search` | 100 results | `Found 347 results (showing first 100):` |
-| `cass_search` | 50 results | `Found 89 sessions (showing first 50):` |
-| `find-exports` | 50 results | `Found 72 exports (showing first 50):` |
-| `semantic-memory_find` | 20 results | `Found 45 memories (showing first 20):` |
-
-**Implementation:**
-```typescript
-const MAX_RESULTS = 100;
-const total = results.length;
-const truncated = total > MAX_RESULTS;
-const limited = truncated ? results.slice(0, MAX_RESULTS) : results;
-
-if (truncated) {
-  output.unshift(`Found ${total} results (showing first ${MAX_RESULTS}):`);
-}
-```
-
-**Why:** Unbounded results kill context. Truncation with count lets agent know there's more.
-
-### 7. Todo-Aware Completion (Bonus)
-
-Before marking a worker complete, check if it left unfinished work:
-
-```typescript
-async function canMarkComplete(sessionID: string): Promise<boolean> {
-  const todos = await client.session.todo({ path: { id: sessionID } });
-  const incomplete = todos.filter(t => t.status !== "completed");
-  
-  if (incomplete.length > 0) {
-    // Inject continuation prompt
-    await client.session.prompt({
-      path: { id: sessionID },
-      body: { parts: [{ text: "You have incomplete TODOs. Continue working." }] }
-    });
-    return false;
-  }
-  return true;
-}
-```
-
-**Why:** Prevents race conditions where worker marks complete before finishing TODO list.
-
-### 8. Think Mode for Complex Decomposition (Bonus)
-
-Auto-enable extended thinking when decomposing complex tasks:
-
-```typescript
-// In chat.params hook
-const complexityIndicators = [
-  "decompose", "break down", "plan", "architect",
-  "refactor across", "migrate", "redesign"
-];
-
-if (complexityIndicators.some(k => prompt.toLowerCase().includes(k))) {
-  output.message.model = { modelID: "claude-sonnet-4-5-high" };
-  output.message.thinking = { type: "enabled", budget_tokens: 16000 };
-}
-```
-
-**Why:** Complex decomposition benefits from extended reasoning. Auto-switching removes friction.
-
-## Implementation
-
-### Phase 1: Delegation Protocol + Context Injection (Priority)
-1. Update `swarm_subtask_prompt` with 7-section format
-2. Add compaction context injection hook
-3. Test with existing swarm workflows
-
-### Phase 2: Preemptive Compaction + Event Hybrid
-1. Add token monitoring to coordinator/worker sessions
-2. Implement 80% threshold compaction with cooldown
-3. Add event-driven completion detection
-4. Keep polling as fallback
-
-### Phase 3: Tool Limits + Parallel Enforcement
-1. Add limits to repo-autopsy, cass, find-exports, semantic-memory
-2. Update swarm-researcher prompt with parallel minimums
-3. Add output validation for parallel enforcement
-
-### Phase 4: Bonus Features
-1. Todo-aware completion check
-2. Think mode auto-switching for decomposition
-
-## Consequences
-
-### Positive
-- **Better worker behavior**: 7-section protocol reduces rogue actions
-- **Context survives compaction**: Critical info preserved through summarization
-- **No more context overflow**: Preemptive compaction at 80%
-- **Faster completion detection**: Events + polling hybrid
-- **Cheaper research**: Parallel execution reduces round-trips
-- **Predictable tool output**: Hard limits prevent context explosion
-
-### Negative
-- **More complexity**: Additional hooks and state management
-- **Prompt bloat**: 7-section format is verbose (but worth it)
-- **Compaction overhead**: Preemptive compaction adds latency (but prevents crashes)
-
-### Neutral
-- **Attribution**: All patterns credited to code-yeongyu/oh-my-opencode
-- **Not a fork**: We're adopting patterns, not copying code
-
-## Alternatives Considered
-
-### Copy oh-my-opencode Wholesale
-Could fork and adapt. Rejected because:
-- Different architecture (we have Swarm Mail, Hive, etc.)
-- Our patterns complement theirs, not replace
-- Selective adoption is cleaner
-
-### Skip Compaction Handling
-Could rely on OpenCode's built-in compaction. Rejected because:
-- Default compaction loses swarm-specific context
-- Decomposition strategy, dependency graph critical for workers
-
-### Always Use Extended Thinking
-Could enable thinking for all coordinator actions. Rejected because:
-- Overkill for simple tasks
-- Slower and more expensive
-- Auto-detection is smarter
-
-## References
-
-- [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode) by code-yeongyu - Primary source
-- [ADR-007](./ADR-007-swarm-enhancements-worktree-review.md) - Worktree isolation + structured review
-- [ADR-008](./ADR-008-worker-handoff-protocol.md) - Worker handoff protocol
-
-## Acknowledgments
-
-Major thanks to **code-yeongyu** for building oh-my-opencode and open-sourcing these patterns. The OpenCode ecosystem is stronger because of contributions like this.
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                                                                 │
-│   🐝  "Good artists copy, great artists steal"                 │
-│       — Picasso (probably misattributed)                       │
-│                                                                 │
-│   We're stealing the good stuff and making it ours.            │
-│   With proper attribution, of course.                          │
-│                                                                 │
-└─────────────────────────────────────────────────────────────────┘
-```

package/docs/planning/ROADMAP.md

@@ -1,368 +0,0 @@
-# Implementation Roadmap
-
-## Overview
-
-This roadmap implements all 5 ADRs in phased releases over 12 weeks. Each phase delivers incremental value and can ship independently.
-
-## Phase 0: Preparation (Week 0)
-
-**Goal:** Set up monorepo infrastructure and validate all ADRs
-
-**Tasks:**
-
-- [ ] Install Turborepo + configure turbo.json
-- [ ] Set up Changesets for versioning
-- [ ] Configure dependency-cruiser for circular dep detection
-- [ ] Create packages/swarm-mail and packages/opencode-swarm-plugin directories
-- [ ] Set up TypeScript project references
-- [ ] Configure CI/CD with Turborepo caching
-
-**Deliverables:**
-
-- Working monorepo build (`turbo run build`)
-- Published ADRs in docs/planning/
-- CI pipeline running tests for both packages
-
-**Success Criteria:**
-
-- `bun run build` builds both packages in correct order
-- No circular dependencies detected
-- CI completes in <2 minutes (with caching)
-
----
-
-## Phase 1: Package Extraction (Weeks 1-2)
-
-**Goal:** Extract swarm-mail package and publish to npm
-
-**ADRs:** ADR-001, ADR-002
-
-**Tasks:**
-
-- [ ] Move src/streams/\* to packages/swarm-mail/src/streams/
-- [ ] Move agent-mail.ts, swarm-mail.ts to swarm-mail
-- [ ] Update imports in opencode-swarm-plugin to use swarm-mail
-- [ ] Migrate integration tests
-- [ ] Write swarm-mail README with examples
-- [ ] Add deprecation warnings in opencode-swarm-plugin
-- [ ] Publish swarm-mail@0.1.0 to npm
-
-**Deliverables:**
-
-- swarm-mail published on npm
-- opencode-swarm-plugin depends on swarm-mail
-- Migration guide for existing users
-- TypeDoc API documentation
-
-**Success Criteria:**
-
-- All tests pass in both packages
-- swarm-mail works in standalone project
-- No circular dependencies
-- Published tarball <500KB
-
----
-
-## Phase 2: Performance Optimizations (Weeks 3-4)
-
-**Goal:** Replace polling with live queries and add batch operations
-
-**ADRs:** ADR-003
-
-**Tasks:**
-
-- [ ] Create live query wrapper (src/streams/live-query.ts)
-- [ ] Add subscription cleanup tracking
-- [ ] Replace polling in watchInbox()
-- [ ] Replace polling in watchEvents()
-- [ ] Add batch message send API
-- [ ] Add batch event append API
-- [ ] Write integration tests for live queries
-- [ ] Run performance benchmarks (latency, CPU, memory)
-
-**Deliverables:**
-
-- Live queries for inbox, events, file reservations
-- Batch APIs for messages and events
-- Performance benchmarks showing improvements
-- Feature flag for gradual rollout
-
-**Success Criteria:**
-
-- Notification latency <50ms (99th percentile)
-- CPU usage <1% in idle state
-- Batch operations 10x faster than individual
-- Memory usage increase <20%
-
-**Metrics (Before → After):**
-
-- Latency: 250-500ms → <10ms (25-50x improvement)
-- CPU: 5-10% → <1% (5-10x reduction)
-- Queries/sec: 2-4 → 0 (eliminated)
-
----
-
-## Phase 3: Message Queue Features (Weeks 5-7)
-
-**Goal:** Add priority queues, DLQ, TTL, pub/sub
-
-**ADRs:** ADR-004
-
-**Tasks:**
-
-**Week 5: Priority Queues + DLQ**
-
-- [ ] Add priority column to messages table
-- [ ] Update getInbox() to ORDER BY priority DESC
-- [ ] Create failed_messages table
-- [ ] Implement retry logic with exponential backoff
-- [ ] Add DLQ viewer to CLI
-
-**Week 6: TTL + Pub/Sub**
-
-- [ ] Add expires_at column to messages
-- [ ] Implement background TTL cleanup job
-- [ ] Add topic column to messages
-- [ ] Implement subscribeToTopic() using live queries
-- [ ] Support wildcard topic subscriptions
-
-**Week 7: Testing + Documentation**
-
-- [ ] Write integration tests for all features
-- [ ] Add examples to README
-- [ ] Document retry/DLQ behavior
-- [ ] Document pub/sub patterns
-
-**Deliverables:**
-
-- Priority queues (4 levels: 0=urgent, 3=low)
-- DLQ with retry tracking
-- TTL with background cleanup
-- Pub/sub with wildcard topics
-
-**Success Criteria:**
-
-- Priority messages processed first
-- Failed messages retry 3x before DLQ
-- Expired messages cleaned up within 5 minutes
-- Topic subscriptions work with wildcards
-
----
-
-## Phase 4: DevTools + CLI (Weeks 8-10)
-
-**Goal:** Build DevTools UI and CLI for observability
-
-**ADRs:** ADR-005
-
-**Tasks:**
-
-**Week 8: CLI**
-
-- [ ] Add @effect/cli dependency
-- [ ] Implement `swarm events` command
-- [ ] Implement `swarm messages` command
-- [ ] Implement `swarm locks` command
-- [ ] Implement `swarm replay` command
-- [ ] Add `--tail` mode for real-time updates
-
-**Week 9: DevTools UI**
-
-- [ ] Scaffold SvelteKit app in apps/devtools
-- [ ] Build event stream viewer
-- [ ] Build message inbox/outbox viewer
-- [ ] Build file reservation timeline
-- [ ] Add SSE endpoint for real-time updates
-
-**Week 10: Integration + Polish**
-
-- [ ] Static export of DevTools UI
-- [ ] Embed UI in plugin (serve at /\_swarm/devtools)
-- [ ] Add screenshots to README
-- [ ] Write user guide
-
-**Deliverables:**
-
-- CLI with 5 commands (events, messages, locks, replay, metrics)
-- DevTools UI (embeddable SvelteKit app)
-- Real-time updates via SSE
-- User guide with screenshots
-
-**Success Criteria:**
-
-- CLI can tail events in real-time
-- DevTools UI shows live message stream
-- UI works offline (static export)
-- Documentation covers all CLI commands
-
----
-
-## Phase 5: Metrics + Tracing (Weeks 11-12)
-
-**Goal:** Add Prometheus metrics and OpenTelemetry tracing
-
-**ADRs:** ADR-005
-
-**Tasks:**
-
-**Week 11: Metrics**
-
-- [ ] Add prom-client dependency
-- [ ] Instrument message send/receive latency
-- [ ] Add lock contention histogram
-- [ ] Add queue depth gauge
-- [ ] Expose /metrics endpoint
-- [ ] Add Grafana dashboard template
-
-**Week 12: Tracing**
-
-- [ ] Add @effect/opentelemetry dependency
-- [ ] Instrument message send/receive spans
-- [ ] Propagate trace context in messages
-- [ ] Add trace_id to message metadata
-- [ ] Test with Jaeger/Zipkin
-- [ ] Write tracing guide
-
-**Deliverables:**
-
-- Prometheus metrics at /metrics endpoint
-- OpenTelemetry tracing integration
-- Grafana dashboard template
-- Tracing guide with Jaeger setup
-
-**Success Criteria:**
-
-- Metrics exposed and scrapeable by Prometheus
-- Traces visible in Jaeger UI
-- Trace propagation across agents works
-- Documentation for all observability tools
-
----
-
-## Phase 6: Saga Pattern (Future)
-
-**Goal:** Implement saga orchestration for long-running workflows
-
-**ADRs:** ADR-004 (Phase 5)
-
-**Status:** Deferred to v2.0
-
-**Tasks:**
-
-- [ ] Create saga_instances and saga_steps tables
-- [ ] Add saga coordinator logic
-- [ ] Implement compensation pattern
-- [ ] Add saga viewer to DevTools UI
-- [ ] Write saga pattern examples
-
-**Deliverables:**
-
-- Saga orchestration pattern
-- Compensation (undo) support
-- Saga viewer in DevTools
-- 3+ example saga workflows
-
----
-
-## Release Schedule
-
-| Version   | Phase | Features                       | ETA     |
-| --------- | ----- | ------------------------------ | ------- |
-| **0.1.0** | 1     | swarm-mail package extraction | Week 2  |
-| **0.2.0** | 2     | Live queries, batch operations | Week 4  |
-| **0.3.0** | 3     | Priority, DLQ, TTL, pub/sub    | Week 7  |
-| **0.4.0** | 4     | DevTools UI + CLI              | Week 10 |
-| **0.5.0** | 5     | Metrics + tracing              | Week 12 |
-| **1.0.0** | All   | Stable release                 | Week 13 |
-| **2.0.0** | 6     | Saga pattern (future)          | TBD     |
-
----
-
-## Dependencies Between Phases
-
-```
-Phase 0 (Monorepo)
-  └──> Phase 1 (Package Extraction)
-         └──> Phase 2 (Performance)
-                ├──> Phase 3 (Queue Features)
-                └──> Phase 4 (DevTools)
-                       └──> Phase 5 (Metrics/Tracing)
-                              └──> Phase 6 (Sagas, future)
-```
-
-**Critical Path:** Phases 0→1→2 are sequential. Phases 3-5 can partially overlap after Phase 2.
-
----
-
-## Risk Mitigation
-
-| Risk                                     | Phase | Mitigation                                                |
-| ---------------------------------------- | ----- | --------------------------------------------------------- |
-| Breaking changes during extraction       | 1     | Feature branch, comprehensive tests, migration guide      |
-| Performance regression with live queries | 2     | Feature flag, benchmark before/after, fallback to polling |
-| Complexity of saga pattern               | 6     | Defer to v2.0, gather user feedback first                 |
-| DevTools UI maintenance burden           | 4     | Keep UI minimal, focus on CLI for power users             |
-| Metrics overhead                         | 5     | Make metrics opt-in, minimal instrumentation              |
-
----
-
-## Success Metrics
-
-**Phase 1 (Package Extraction):**
-
-- swarm-mail used in 3+ external projects within 3 months
-- Zero breaking changes reported by users
-
-**Phase 2 (Performance):**
-
-- 25x faster notification latency (500ms → <10ms)
-- 5x lower CPU usage (10% → <2%)
-
-**Phase 3 (Queue Features):**
-
-- 95% of messages processed within priority SLA
-- <1% messages fail to DLQ
-
-**Phase 4 (DevTools):**
-
-- 80% of developers use DevTools UI for debugging
-- CLI used in 50%+ of support cases
-
-**Phase 5 (Metrics/Tracing):**
-
-- Metrics dashboard used in production monitoring
-- Distributed traces reduce debugging time by 50%
-
----
-
-## Post-1.0 Backlog (v2.0+)
-
-**Saga Pattern** (ADR-004 Phase 5)
-
-- Long-running multi-agent workflows
-- Compensation (undo) support
-- Saga state visualization
-
-**Advanced Pub/Sub**
-
-- Message routing rules
-- Filter expressions (SQL-like WHERE clauses)
-- At-least-once vs exactly-once delivery guarantees
-
-**Multi-Project Support**
-
-- Cross-project message routing
-- Project-level isolation
-- Shared infra for mono repos
-
-**Performance Tier 2**
-
-- Connection pooling for multi-DB scenarios
-- Message batching optimizations
-- SKIP LOCKED for exactly-once semantics
-
-**Security**
-
-- Message encryption at rest
-- Agent authentication/authorization
-- Audit logging