opencode-swarm-plugin 0.44.0 → 0.44.1

package/docs/planning/ADR-005-devtools-observability.md

@@ -1,202 +0,0 @@
-# ADR-005: DevTools + Observability
-
-## Status
-
-Proposed
-
-## Context
-
-Swarm Mail currently has no visibility:
-
-- No UI to inspect events, messages, locks
-- No metrics on latency, queue depth, throughput
-- No distributed tracing across agents
-- Hard to debug coordination issues
-
-Need both developer tools (UI + CLI) and production observability (metrics + tracing).
-
-## Decision
-
-Build layered observability:
-
-### 1. DevTools UI (SvelteKit)
-
-**Stack:**
-
-- SvelteKit for SSR + static export
-- Vite for dev server + build
-- Server-Sent Events (SSE) for real-time updates
-- Embeddable static build
-
-**Features:**
-
-- Event stream viewer (filterable, searchable)
-- Message inbox/outbox per agent
-- File reservation timeline
-- Saga instance tracker (future)
-
-**Build:**
-
-```bash
-cd apps/devtools
-bun run build  # Static export to apps/devtools/build
-```
-
-**Embed in plugin:**
-
-```typescript
-// Serve static UI at /_swarm/devtools
-const server = serve({
-  port: 4000,
-  fetch: (req) => {
-    if (req.url.startsWith("/_swarm/devtools")) {
-      return serveStatic("apps/devtools/build");
-    }
-  },
-});
-```
-
-### 2. CLI (@effect/cli)
-
-**Commands:**
-
-```bash
-swarm events [--project <key>] [--type <type>] [--tail]
-swarm messages [--agent <name>] [--unread]
-swarm locks [--agent <name>]
-swarm replay --from <sequence> [--to <sequence>]
-swarm metrics
-```
-
-**Implementation:**
-
-```typescript
-import { Command } from "@effect/cli";
-
-const eventsCommand = Command.make(
-  "events",
-  {
-    project: Options.string("project").optional,
-    type: Options.string("type").optional,
-    tail: Options.boolean("tail"),
-  },
-  ({ project, type, tail }) => {
-    // Query events table, optionally --tail with live query
-  },
-);
-```
-
-### 3. Metrics (Prometheus)
-
-**Histograms:**
-
-- `swarm_message_latency_seconds` - Send to receive time
-- `swarm_lock_contention_seconds` - Time waiting for lock
-- `swarm_queue_depth` - Unread messages per agent
-
-**Counters:**
-
-- `swarm_events_total{type}` - Events by type
-- `swarm_messages_sent_total{sender, recipient}`
-- `swarm_locks_acquired_total{agent}`
-
-**Example:**
-
-```typescript
-import { Registry, Histogram } from 'prom-client'
-
-const messageLat ency = new Histogram({
-  name: 'swarm_message_latency_seconds',
-  help: 'Message delivery latency',
-  buckets: [0.01, 0.05, 0.1, 0.5, 1.0, 5.0]
-})
-
-// Record latency
-const start = Date.now()
-await sendMessage(msg)
-const latency = (Date.now() - start) / 1000
-messageLatency.observe(latency)
-```
-
-### 4. Distributed Tracing (OpenTelemetry)
-
-**Integration:**
-
-```typescript
-import { @effect/opentelemetry } from '@effect/opentelemetry'
-import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node'
-
-const provider = new NodeTracerProvider()
-const tracer = provider.getTracer('swarm-mail')
-
-// Trace message send
-const span = tracer.startSpan('sendMessage', {
-  attributes: {
-    'swarm.sender': 'AgentA',
-    'swarm.recipient': 'AgentB',
-    'swarm.thread_id': 'bd-123'
-  }
-})
-
-await sendMessage(msg)
-span.end()
-```
-
-**Trace Propagation:**
-
-- Add trace_id to message metadata
-- Worker agents continue traces from parents
-- Visualize full swarm execution flow
-
-## Consequences
-
-### Easier
-
-- **Visibility** - See all events, messages, locks in real-time
-- **Debugging** - Trace issues across agents via distributed tracing
-- **Performance** - Identify slow operations via histograms
-- **Operations** - CLI for prod debugging without UI
-
-### More Difficult
-
-- **Maintenance** - Another app to maintain (DevTools UI)
-- **Bundle size** - Metrics/tracing deps increase plugin size
-- **Performance overhead** - Instrumentation adds latency
-- **Configuration** - Metrics exporters, trace backends
-
-## Implementation Notes
-
-### Phase 1: CLI (Week 1)
-
-- Add @effect/cli dependency
-- Implement events, messages, locks commands
-- Test with real swarm sessions
-
-### Phase 2: DevTools UI (Week 2-3)
-
-- Scaffold SvelteKit app
-- Build event stream viewer
-- Add SSE endpoint for real-time updates
-- Static export + embed in plugin
-
-### Phase 3: Metrics (Week 4)
-
-- Add prom-client dependency
-- Instrument send/receive latency
-- Add queue depth gauge
-- Expose /metrics endpoint
-
-### Phase 4: Tracing (Week 5)
-
-- Add @effect/opentelemetry
-- Instrument message send/receive
-- Propagate trace context
-- Test with Jaeger/Zipkin
-
-### Success Criteria
-
-- [ ] CLI can tail events in real-time
-- [ ] DevTools UI shows live message stream
-- [ ] Metrics exposed at /metrics endpoint
-- [ ] Traces visible in Jaeger UI
-- [ ] Documentation for all observability tools

package/docs/planning/ADR-007-swarm-enhancements-worktree-review.md

@@ -1,168 +0,0 @@
-# ADR-007: Swarm Enhancements - Worktree Isolation + Structured Review
-
-## Status
-
-Proposed
-
-## Context
-
-After reviewing [nexxeln/opencode-config](https://github.com/nexxeln/opencode-config), we identified several patterns that would strengthen our swarm coordination:
-
-1. **Git worktree isolation** - Each worker gets a complete isolated copy of the repo
-2. **Structured review loop** - Workers must pass review before completion
-3. **Retry options on abort** - Clean recovery paths when things go wrong
-
-Currently our swarm uses:
-- **File reservations** via Swarm Mail for conflict prevention
-- **UBS scan** on completion for bug detection
-- **Manual cleanup** on abort
-
-## Decision
-
-### 1. Optional Worktree Isolation Mode
-
-Add `isolation` parameter to swarm initialization:
-
-```typescript
-swarm_init({
-  task: "Large refactor across 50 files",
-  isolation: "worktree"  // or "reservation" (default)
-})
-```
-
-**When to use worktrees:**
-- Large refactors touching many files
-- High risk of merge conflicts
-- Need complete isolation (different node_modules, etc.)
-
-**When to use reservations (default):**
-- Most swarm tasks
-- Quick parallel work
-- Lower overhead
-
-**Worktree lifecycle:**
-```
-swarm_worktree_create(task_id) → /path/to/worktree
-  ↓
-worker does work in worktree
-  ↓
-swarm_worktree_merge(task_id)  → cherry-pick commit to main
-  ↓
-swarm_worktree_cleanup(task_id) → remove worktree
-```
-
-**On abort:** Hard reset main to start commit, delete all worktrees.
-
-### 2. Structured Review Step
-
-The coordinator reviews worker output before marking complete. This replaces the current "trust but verify with UBS" approach.
-
-**Review flow:**
-```
-worker completes → coordinator reviews → approved/needs_changes
-                                              ↓
-                                    if needs_changes: worker fixes (max 3 attempts)
-                                              ↓
-                                    if approved: mark complete
-```
-
-**Review prompt includes:**
-- Epic goal (the big picture)
-- Task requirements
-- What completed tasks this builds on (dependency context)
-- What future tasks depend on this (downstream context)
-- The actual code changes
-
-**Why coordinator reviews (not separate reviewer agent):**
-- Coordinator already has full epic context loaded
-- Avoids spawning another agent just for review
-- Keeps the feedback loop tight
-- Coordinator can make judgment calls about "good enough"
-
-**Review criteria:**
-1. Does it fulfill the task requirements?
-2. Does it serve the epic goal?
-3. Will downstream tasks be able to use it?
-4. Are there critical bugs? (UBS scan still runs)
-
-### 3. Retry Options on Abort
-
-When a swarm aborts (user request or failure), provide clear recovery paths:
-
-```json
-{
-  "retry_options": {
-    "same_plan": "/swarm --retry",
-    "edit_plan": "/swarm --retry --edit",
-    "fresh_start": "/swarm \"original task\""
-  }
-}
-```
-
-**`--retry`**: Resume with same plan, skip completed tasks
-**`--retry --edit`**: Show plan for modification before resuming
-**Fresh start**: Decompose from scratch
-
-This requires persisting swarm session state (already have this via Hive cells).
-
-## Implementation
-
-### Phase 1: Structured Review (Priority)
-1. Add review step to `swarm_complete`
-2. Create review prompt with epic context injection
-3. Handle needs_changes → worker retry loop (max 3)
-4. Keep UBS scan as additional safety net
-
-### Phase 2: Worktree Isolation
-1. Add `isolation` mode to `swarm_init`
-2. Implement worktree lifecycle tools
-3. Update worker prompts to work in worktree path
-4. Add cherry-pick merge on completion
-5. Add cleanup on abort
-
-### Phase 3: Retry Options
-1. Persist session state for recovery
-2. Add `--retry` and `--retry --edit` flags
-3. Skip completed tasks on retry
-4. Show plan editor for `--edit` mode
-
-## Consequences
-
-### Positive
-- **Better quality**: Structured review catches issues before integration
-- **Safer large refactors**: Worktree isolation eliminates merge conflicts
-- **Cleaner recovery**: Retry options reduce friction after failures
-- **Coordinator stays in control**: Review keeps human-in-the-loop feel
-
-### Negative
-- **More complexity**: Two isolation modes to maintain
-- **Slower completion**: Review step adds latency
-- **Disk usage**: Worktrees consume space (mitigated by cleanup)
-
-### Neutral
-- **Credit**: Patterns inspired by nexxeln/opencode-config - should acknowledge in docs
-
-## Alternatives Considered
-
-### Separate Reviewer Agent
-nexxeln uses a dedicated reviewer subagent. We chose coordinator-as-reviewer because:
-- Avoids context duplication (coordinator already has epic context)
-- Faster feedback loop
-- Coordinator can make "ship it" judgment calls
-
-### Staged Changes on Finalize
-nexxeln soft-resets to leave changes staged for user review. We're skipping this because:
-- Our flow already has explicit commit step
-- Hive tracks what changed
-- User can always `git diff` before committing
-
-### Always Use Worktrees
-Could simplify by always using worktrees. Rejected because:
-- Overkill for most tasks
-- Slower setup/teardown
-- File reservations work fine for typical parallel work
-
-## References
-
-- [nexxeln/opencode-config](https://github.com/nexxeln/opencode-config) - Source of inspiration
-- Epic: `bd-lf2p4u-mjaja96b9da` - Swarm Enhancements

package/docs/planning/ADR-008-worker-handoff-protocol.md

@@ -1,293 +0,0 @@
-# ADR-008: Worker Handoff Protocol - Structured Contracts Over Prose
-
-## Status
-
-Proposed
-
-## Context
-
-The current `SUBTASK_PROMPT_V2` is a **280-line prose instruction manual** that gets injected into every swarm worker's context. This approach has fundamental problems:
-
-### Current Problems
-
-1. **Workers ignore prose** - Long text instructions get skimmed or missed entirely
-2. **No validation** - Can't programmatically verify workers followed protocol
-3. **Context bloat** - 280 lines * N workers burns tokens fast
-4. **Drift and violations** - Workers modify files outside their scope, no automatic detection
-5. **Manual error recovery** - Coordinator can't auto-detect contract violations
-
-**Concrete example of failure:**
-```
-Worker assigned: ["src/auth/service.ts"]
-Worker actually touched: ["src/auth/service.ts", "src/lib/jwt.ts", "src/types/user.ts"]
-                         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-                         Scope creep undetected until swarm_complete
-```
-
-Current `swarm_complete` validates `files_touched ⊆ files_owned`, but the **contract** was never machine-readable to begin with.
-
-### Research & Inspirations
-
-From "Patterns for Building AI Agents" and production event-driven systems:
-
-**mdflow adapter pattern:**
-- Convention-based behavior inference
-- Template variables define expectations
-- Minimal configuration, maximum clarity
-
-**Bellemare's event-driven orchestration:**
-- Explicit contracts between services
-- Commands vs Events distinction
-- Contract violations fail fast with clear errors
-
-**Key insight:** Agents need **two channels**:
-1. **Contract** (machine-readable, validated) - WHAT to do, WHERE to do it
-2. **Context** (human-readable, advisory) - WHY it matters, HOW it fits together
-
-## Decision
-
-Replace 280-line prose with **WorkerHandoff envelope** that separates contract from context.
-
-### WorkerHandoff Structure
-
-```typescript
-interface WorkerHandoff {
-  // Machine-readable - enforced by tools
-  contract: {
-    task_id: string;              // Cell ID for tracking
-    files_owned: string[];        // Exclusive write access (validated)
-    files_readonly: string[];     // Can read, MUST NOT modify (validated)
-    dependencies_completed: string[];  // Tasks that finished before this
-    success_criteria: string[];   // Exit conditions (checkable)
-  };
-  
-  // Human-readable - advisory context
-  context: {
-    epic_summary: string;         // Big picture goal
-    your_role: string;            // What this subtask accomplishes
-    what_others_did: string;      // Dependency outputs
-    what_comes_next: string;      // Downstream task expectations
-  };
-  
-  // Escalation paths - when things go wrong
-  escalation: {
-    blocked_contact: string;      // "coordinator" or agent name
-    scope_change_protocol: string; // "swarmmail_send + await approval"
-  };
-}
-```
-
-### Example Handoff
-
-```json
-{
-  "contract": {
-    "task_id": "bd-123.2",
-    "files_owned": ["src/auth/service.ts", "src/auth/service.test.ts"],
-    "files_readonly": ["src/types/user.ts", "src/lib/jwt.ts"],
-    "dependencies_completed": ["bd-123.1"],
-    "success_criteria": [
-      "AuthService.login() returns JWT token",
-      "Tests pass: bun test src/auth/service.test.ts",
-      "Type check passes: tsc --noEmit"
-    ]
-  },
-  "context": {
-    "epic_summary": "Add OAuth authentication to user service",
-    "your_role": "Implement AuthService with JWT token generation",
-    "what_others_did": "bd-123.1 created User schema with email/password fields",
-    "what_comes_next": "bd-123.3 will integrate this service into API routes"
-  },
-  "escalation": {
-    "blocked_contact": "coordinator",
-    "scope_change_protocol": "swarmmail_send(subject='Scope Change', ack_required=true)"
-  }
-}
-```
-
-### Validation in swarm_complete
-
-```typescript
-// swarm_complete now validates against contract
-function validateCompletion(handoff: WorkerHandoff, result: CompletionReport) {
-  const violations: string[] = [];
-  
-  // 1. File scope violations
-  const unauthorized = result.files_touched.filter(
-    f => !handoff.contract.files_owned.includes(f)
-  );
-  if (unauthorized.length > 0) {
-    violations.push(`Touched unauthorized files: ${unauthorized.join(", ")}`);
-  }
-  
-  // 2. Success criteria (checkable ones)
-  for (const criterion of handoff.contract.success_criteria) {
-    if (criterion.startsWith("Tests pass:")) {
-      // Run the test command, validate exit 0
-    }
-    if (criterion.startsWith("Type check passes:")) {
-      // Run tsc --noEmit, validate exit 0
-    }
-  }
-  
-  // 3. Learning signals from violations
-  if (violations.length > 0) {
-    recordLearningSignal({
-      task_id: handoff.contract.task_id,
-      violation_type: "scope_creep",
-      details: violations,
-      impact: "negative"  // Penalize decomposition strategy
-    });
-  }
-  
-  return { valid: violations.length === 0, violations };
-}
-```
-
-### Integration with Existing Tools
-
-**swarm_spawn_subtask generates handoffs:**
-
-```typescript
-export const swarm_spawn_subtask = tool(/* ... */)
-  .handler(async ({ input, context }) => {
-    const handoff: WorkerHandoff = {
-      contract: {
-        task_id: input.bead_id,
-        files_owned: input.files,
-        files_readonly: inferReadonlyFiles(input.files, epicContext),
-        dependencies_completed: input.dependencies_completed || [],
-        success_criteria: generateSuccessCriteria(input.subtask_description)
-      },
-      context: {
-        epic_summary: epicContext.summary,
-        your_role: input.subtask_title,
-        what_others_did: summarizeDependencies(input.dependencies_completed),
-        what_comes_next: summarizeDownstream(input.bead_id)
-      },
-      escalation: {
-        blocked_contact: "coordinator",
-        scope_change_protocol: "swarmmail_send(subject='Scope Change', ack_required=true)"
-      }
-    };
-    
-    return formatHandoff(handoff); // Compact JSON + minimal prose wrapper
-  });
-```
-
-**swarm_complete validates contract:**
-
-```typescript
-export const swarm_complete = tool(/* ... */)
-  .handler(async ({ input, context }) => {
-    const handoff = getStoredHandoff(input.bead_id);
-    const validation = validateCompletion(handoff, {
-      files_touched: input.files_touched,
-      summary: input.summary
-    });
-    
-    if (!validation.valid) {
-      throw new Error(
-        `Contract violations detected:\n${validation.violations.join("\n")}`
-      );
-    }
-    
-    // Proceed with UBS scan, reservation release, etc.
-  });
-```
-
-## Consequences
-
-### Positive
-
-- **Validation enforced** - Can't complete with contract violations
-- **Clear boundaries** - Workers know exactly what's in/out of scope
-- **Better learning** - Scope creep violations feed back into strategy selection
-- **Context efficiency** - Contract is ~30 lines JSON vs 280 lines prose
-- **Fail fast** - Violations detected immediately, not during merge
-- **Programmatic recovery** - Coordinator can auto-detect and reassign work
-
-### Negative
-
-- **Requires storage** - Handoffs must persist (already have event store)
-- **Success criteria limited** - Can't validate all criteria automatically
-- **Migration cost** - Existing `SUBTASK_PROMPT_V2` users need update
-- **More upfront work** - Coordinator must generate better contracts
-
-### Neutral
-
-- **Prose still exists** - `context` field provides human explanation, just smaller
-- **Not eliminating checklist** - 9-step survival checklist stays, but moves to tool enforcement
-
-## Implementation Notes
-
-### Phase 1: Storage & Schema
-
-1. Add `WorkerHandoff` schema to swarm-mail event types
-2. Store handoffs in event log when spawning subtasks
-3. Retrieve handoffs in `swarm_complete` for validation
-
-### Phase 2: Generation Logic
-
-1. Implement `inferReadonlyFiles()` - analyze imports/dependencies
-2. Implement `generateSuccessCriteria()` - parse task description for checkable conditions
-3. Implement `summarizeDependencies()` and `summarizeDownstream()` - build context from epic graph
-
-### Phase 3: Validation
-
-1. Add contract validation to `swarm_complete`
-2. Implement checkable criteria runners (test commands, type checks)
-3. Record learning signals for violations
-
-### Phase 4: Migration
-
-1. Update `formatSubtaskPromptV2` to generate handoff JSON
-2. Deprecate 280-line prose template
-3. Update tests for new handoff format
-
-### Phase 5: Enhanced Features (Future)
-
-1. **Readonly enforcement** - Detect modifications to `files_readonly` via git diff
-2. **Dependency validation** - Verify `dependencies_completed` actually ran first
-3. **Auto-generated success criteria** - Parse test files, infer criteria from code
-
-## Alternatives Considered
-
-### Keep Prose, Add Validation
-
-Keep `SUBTASK_PROMPT_V2` but add validation after-the-fact. **Rejected** because:
-- Still burns 280 lines of context per worker
-- Workers still ignore prose
-- Validation happens too late (after work done)
-
-### Minimal Contract Only
-
-Remove context entirely, pure machine contract. **Rejected** because:
-- Workers need WHY to make good judgment calls
-- Context helps with edge cases not in contract
-- Loss of human readability hurts debugging
-
-### Command Pattern (Bellemare Style)
-
-Full event-sourcing with Command objects. **Rejected** because:
-- Over-engineered for current needs
-- Already have event store for coordination
-- Contract + context is simpler and sufficient
-
-## References
-
-- **"Patterns for Building AI Agents"** - Subagent context sharing patterns
-- **mdflow** - Convention-based adapter design, template variable contracts
-- **Bellemare's "Building Event-Driven Microservices"** - Explicit contracts, fail-fast validation
-- **Current implementation:** `src/swarm-prompts.ts` (SUBTASK_PROMPT_V2, lines 253-530)
-- **Related:** ADR-007 (Structured Review), ADR-002 (Package Extraction)
-
-## Success Criteria
-
-- [ ] `WorkerHandoff` schema defined and validated with Zod
-- [ ] `swarm_spawn_subtask` generates handoffs instead of raw prose
-- [ ] `swarm_complete` validates contract before accepting completion
-- [ ] Scope violations trigger learning signals (negative feedback)
-- [ ] Workers receive handoff as JSON + compact context wrapper (<50 lines)
-- [ ] Test suite validates contract enforcement catches violations
-- [ ] Migration path documented for existing swarm users