opencode-swarm-plugin 0.18.0 → 0.20.0

package/src/pattern-maturity.ts

@@ -12,6 +12,16 @@
 import { z } from "zod";
 import { calculateDecayedValue } from "./learning";
 
+// ============================================================================
+// Constants
+// ============================================================================
+
+/**
+ * Tolerance for floating-point comparisons.
+ * Used when comparing success rates to avoid floating-point precision issues.
+ */
+const FLOAT_EPSILON = 0.01;
+
 // ============================================================================
 // Schemas
 // ============================================================================
@@ -164,26 +174,26 @@ export function calculateMaturityState(
   );
 
   const total = decayedHelpful + decayedHarmful;
-  const epsilon = 0.01; // Float comparison tolerance
-  const safeTotal = total > epsilon ? total : 0;
+  // Use FLOAT_EPSILON constant (defined at module level)
+  const safeTotal = total > FLOAT_EPSILON ? total : 0;
   const harmfulRatio = safeTotal > 0 ? decayedHarmful / safeTotal : 0;
 
   // Deprecated: high harmful ratio with enough feedback
   if (
     harmfulRatio > config.deprecationThreshold &&
-    safeTotal >= config.minFeedback - epsilon
+    safeTotal >= config.minFeedback - FLOAT_EPSILON
   ) {
     return "deprecated";
   }
 
   // Candidate: not enough feedback yet
-  if (safeTotal < config.minFeedback - epsilon) {
+  if (safeTotal < config.minFeedback - FLOAT_EPSILON) {
     return "candidate";
   }
 
   // Proven: strong positive signal
   if (
-    decayedHelpful >= config.minHelpful - epsilon &&
+    decayedHelpful >= config.minHelpful - FLOAT_EPSILON &&
     harmfulRatio < config.maxHarmful
   ) {
     return "proven";
@@ -210,14 +220,23 @@ export function createPatternMaturity(patternId: string): PatternMaturity {
 }
 
 /**
- * Update pattern maturity with new feedback
+ * Update pattern maturity with new feedback.
+ *
+ * Side Effects:
+ * - Sets `promoted_at` timestamp on first entry into 'proven' status
+ * - Sets `deprecated_at` timestamp on first entry into 'deprecated' status
+ * - Updates `helpful_count` and `harmful_count` based on feedback events
+ * - Recalculates `state` based on decayed feedback counts
  *
- * Records feedback, updates counts, and recalculates state.
+ * State Transitions:
+ * - candidate → established: After minFeedback observations (default 3)
+ * - established → proven: When decayedHelpful >= minHelpful (5) AND harmfulRatio < maxHarmful (15%)
+ * - any → deprecated: When harmfulRatio > deprecationThreshold (30%) AND total >= minFeedback
  *
  * @param maturity - Current maturity record
  * @param feedbackEvents - All feedback events for this pattern
  * @param config - Maturity configuration
- * @returns Updated maturity record
+ * @returns Updated maturity record with new state
  */
 export function updatePatternMaturity(
   maturity: PatternMaturity,
@@ -269,7 +288,16 @@ export function promotePattern(maturity: PatternMaturity): PatternMaturity {
   }
 
   if (maturity.state === "proven") {
-    return maturity; // Already proven
+    console.warn(
+      `[PatternMaturity] Pattern already proven: ${maturity.pattern_id}`,
+    );
+    return maturity; // No-op but warn
+  }
+
+  if (maturity.state === "candidate" && maturity.helpful_count < 3) {
+    console.warn(
+      `[PatternMaturity] Promoting candidate with insufficient data: ${maturity.pattern_id} (${maturity.helpful_count} helpful observations)`,
+    );
   }
 
   const now = new Date().toISOString();
@@ -309,12 +337,16 @@ export function deprecatePattern(
 }
 
 /**
- * Get maturity score multiplier for pattern ranking
+ * Get weight multiplier based on pattern maturity status.
  *
- * Higher maturity patterns should be weighted more heavily.
+ * Multipliers chosen to:
+ * - Heavily penalize deprecated patterns (0x) - never recommend
+ * - Slightly boost proven patterns (1.5x) - reward validated success
+ * - Penalize unvalidated candidates (0.5x) - reduce impact until proven
+ * - Neutral for established (1.0x) - baseline weight
  *
- * @param state - Maturity state
- * @returns Score multiplier (0-1.5)
+ * @param state - Pattern maturity status
+ * @returns Multiplier to apply to pattern weight
  */
 export function getMaturityMultiplier(state: MaturityState): number {
   const multipliers: Record<MaturityState, number> = {
@@ -336,6 +368,12 @@ export function getMaturityMultiplier(state: MaturityState): number {
  */
 export function formatMaturityForPrompt(maturity: PatternMaturity): string {
   const total = maturity.helpful_count + maturity.harmful_count;
+
+  // Don't show percentages for insufficient data
+  if (total < 3) {
+    return `[LIMITED DATA - ${total} observation${total !== 1 ? "s" : ""}]`;
+  }
+
   const harmfulRatio =
     total > 0 ? Math.round((maturity.harmful_count / total) * 100) : 0;
   const helpfulRatio =

package/src/plugin.ts

@@ -1,9 +1,21 @@
 /**
  * OpenCode Plugin Entry Point
  *
- * This file ONLY exports the plugin function.
- * The plugin loader iterates over all exports and calls them as functions,
- * so we cannot export anything else here (classes, constants, types, etc.)
+ * CRITICAL: Only export the plugin function from this file.
+ *
+ * OpenCode's plugin loader calls ALL exports as functions during initialization.
+ * Exporting classes, constants, or non-function values will cause the plugin
+ * to fail to load with cryptic errors.
+ *
+ * If you need to export utilities for external use, add them to src/index.ts instead.
+ *
+ * @example
+ * // ✅ CORRECT - only export the plugin function
+ * export default SwarmPlugin;
+ *
+ * // ❌ WRONG - will break plugin loading
+ * export const VERSION = "1.0.0";
+ * export class Helper {}
  */
 import { SwarmPlugin } from "./index";
 

package/src/schemas/bead.ts

@@ -42,19 +42,42 @@ export type BeadDependency = z.infer<typeof BeadDependencySchema>;
  * - Custom subtask: `{project}-{custom-id}.{suffix}` (e.g., `migrate-egghead-phase-0.e2e-test`)
  */
 export const BeadSchema = z.object({
+  /**
+   * Bead ID format: project-slug-hash with optional subtask index.
+   *
+   * Pattern: `project-name-xxxxx` or `project-name-xxxxx.N`
+   * Examples:
+   * - `my-project-abc12` (main bead)
+   * - `my-project-abc12.1` (first subtask)
+   * - `my-project-abc12.2` (second subtask)
+   */
   id: z
     .string()
-    .regex(/^[a-z0-9]+(-[a-z0-9]+)+(\.[\w-]+)?$/, "Invalid bead ID format"),
+    .regex(
+      /^[a-z0-9]+(-[a-z0-9]+)+(\.[\w-]+)?$/,
+      "Invalid bead ID format (expected: project-slug-hash or project-slug-hash.N)",
+    ),
   title: z.string().min(1, "Title required"),
   description: z.string().optional().default(""),
   status: BeadStatusSchema.default("open"),
   priority: z.number().int().min(0).max(3).default(2),
   issue_type: BeadTypeSchema.default("task"),
-  created_at: z.string().datetime({ offset: true }), // ISO-8601 with timezone offset
-  updated_at: z.string().datetime({ offset: true }).optional(),
+  created_at: z.string().datetime({
+    offset: true,
+    message:
+      "Must be ISO-8601 datetime with timezone (e.g., 2024-01-15T10:30:00Z)",
+  }),
+  updated_at: z
+    .string()
+    .datetime({
+      offset: true,
+      message:
+        "Must be ISO-8601 datetime with timezone (e.g., 2024-01-15T10:30:00Z)",
+    })
+    .optional(),
   closed_at: z.string().datetime({ offset: true }).optional(),
   parent_id: z.string().optional(),
-  dependencies: z.array(BeadDependencySchema).optional().default([]),
+  dependencies: z.array(BeadDependencySchema).default([]),
   metadata: z.record(z.string(), z.unknown()).optional(),
 });
 export type Bead = z.infer<typeof BeadSchema>;
@@ -111,6 +134,14 @@ export const SubtaskSpecSchema = z.object({
   description: z.string().optional().default(""),
   files: z.array(z.string()).default([]),
   dependencies: z.array(z.number().int().min(0)).default([]), // Indices of other subtasks
+  /**
+   * Complexity estimate on 1-5 scale:
+   * 1 = trivial (typo fix, simple rename)
+   * 2 = simple (single function change)
+   * 3 = moderate (multi-file, some coordination)
+   * 4 = complex (significant refactoring)
+   * 5 = very complex (architectural change)
+   */
   estimated_complexity: z.number().int().min(1).max(5).default(3),
 });
 export type SubtaskSpec = z.infer<typeof SubtaskSpecSchema>;

package/src/schemas/evaluation.ts

@@ -12,9 +12,15 @@
 import { z } from "zod";
 
 /**
- * Single criterion evaluation
+ * Evaluation of a single criterion.
  *
- * Each criterion (type_safe, no_bugs, etc.) gets its own evaluation.
+ * @example
+ * // Passing criterion
+ * { passed: true, feedback: "All types validated", score: 0.95 }
+ *
+ * @example
+ * // Failing criterion
+ * { passed: false, feedback: "Missing error handling in auth flow", score: 0.3 }
  */
 export const CriterionEvaluationSchema = z.object({
   passed: z.boolean(),
@@ -31,7 +37,11 @@ export type CriterionEvaluation = z.infer<typeof CriterionEvaluationSchema>;
  */
 export const WeightedCriterionEvaluationSchema =
   CriterionEvaluationSchema.extend({
-    /** Current weight after decay (0-1, lower = less reliable) */
+    /**
+     * Current weight after 90-day half-life decay.
+     * Range: 0-1 where 1 = recent/validated, 0 = old/unreliable.
+     * Weights decay over time unless revalidated via semantic-memory_validate.
+     */
     weight: z.number().min(0).max(1).default(1),
     /** Weighted score = score * weight */
     weighted_score: z.number().min(0).max(1).optional(),
@@ -75,9 +85,11 @@ export type DefaultCriterion = (typeof DEFAULT_CRITERIA)[number];
  * Evaluation request arguments
  */
 export const EvaluationRequestSchema = z.object({
-  subtask_id: z.string(),
-  criteria: z.array(z.string()).default([...DEFAULT_CRITERIA]),
-  context: z.string().optional(),
+  bead_id: z.string(),
+  subtask_title: z.string(),
+  files_touched: z.array(z.string()),
+  /** ISO-8601 timestamp when evaluation was requested */
+  requested_at: z.string().datetime().optional(),
 });
 export type EvaluationRequest = z.infer<typeof EvaluationRequestSchema>;
 

package/src/schemas/index.ts

@@ -1,7 +1,30 @@
 /**
- * Schema exports
+ * Schema Definitions - Central export point for all Zod schemas
  *
- * Re-export all schemas for convenient importing.
+ * This module re-exports all schema definitions used throughout the plugin.
+ * Schemas are organized by domain:
+ *
+ * ## Bead Schemas (Issue Tracking)
+ * - `BeadSchema` - Core bead/issue definition
+ * - `BeadStatusSchema` - Status enum (open, in_progress, blocked, closed)
+ * - `BeadTypeSchema` - Type enum (bug, feature, task, epic, chore)
+ * - `SubtaskSpecSchema` - Subtask specification for epic creation
+ *
+ * ## Task Schemas (Swarm Decomposition)
+ * - `TaskDecompositionSchema` - Full task breakdown
+ * - `DecomposedSubtaskSchema` - Individual subtask definition
+ * - `BeadTreeSchema` - Epic + subtasks structure
+ *
+ * ## Evaluation Schemas (Agent Self-Assessment)
+ * - `EvaluationSchema` - Complete evaluation with criteria
+ * - `CriterionEvaluationSchema` - Single criterion result
+ *
+ * ## Progress Schemas (Swarm Coordination)
+ * - `SwarmStatusSchema` - Overall swarm progress
+ * - `AgentProgressSchema` - Individual agent status
+ * - `SpawnedAgentSchema` - Spawned agent metadata
+ *
+ * @module schemas
  */
 
 // Bead schemas

package/src/schemas/task.ts

@@ -7,13 +7,19 @@
 import { z } from "zod";
 
 /**
- * Effort estimation levels
+ * Effort estimation for subtasks.
+ *
+ * Time ranges:
+ * - `trivial`: < 5 minutes (simple rename, typo fix)
+ * - `small`: 5-30 minutes (single function, simple feature)
+ * - `medium`: 30 min - 2 hours (multi-file change, moderate complexity)
+ * - `large`: 2+ hours (significant feature, refactoring)
  */
 export const EffortLevelSchema = z.enum([
-  "trivial", // < 5 min
-  "small", // 5-30 min
-  "medium", // 30 min - 2 hours
-  "large", // 2+ hours
+  "trivial",
+  "small",
+  "medium",
+  "large",
 ]);
 export type EffortLevel = z.infer<typeof EffortLevelSchema>;
 
@@ -35,6 +41,7 @@ export const DecomposedSubtaskSchema = z.object({
   description: z.string(),
   files: z.array(z.string()), // File paths this subtask will modify
   estimated_effort: EffortLevelSchema,
+  /** Potential risks or complications (e.g., 'tight coupling', 'data migration required', 'breaking change') */
   risks: z.array(z.string()).optional().default([]),
 });
 export type DecomposedSubtask = z.infer<typeof DecomposedSubtaskSchema>;
@@ -43,8 +50,10 @@ export type DecomposedSubtask = z.infer<typeof DecomposedSubtaskSchema>;
  * Dependency between subtasks
  */
 export const SubtaskDependencySchema = z.object({
-  from: z.number().int().min(0), // Subtask index
-  to: z.number().int().min(0), // Subtask index
+  /** Zero-based index of the dependency source subtask */
+  from: z.number().int().min(0),
+  /** Zero-based index of the dependency target subtask */
+  to: z.number().int().min(0),
   type: DependencyTypeSchema,
 });
 export type SubtaskDependency = z.infer<typeof SubtaskDependencySchema>;
@@ -56,10 +65,15 @@ export type SubtaskDependency = z.infer<typeof SubtaskDependencySchema>;
  */
 export const TaskDecompositionSchema = z.object({
   task: z.string(), // Original task description
-  reasoning: z.string().optional(), // Why this decomposition
+  /** Rationale for this decomposition strategy (why these subtasks, why this order) */
+  reasoning: z.string().optional(),
   subtasks: z.array(DecomposedSubtaskSchema).min(1),
   dependencies: z.array(SubtaskDependencySchema).optional().default([]),
-  shared_context: z.string().optional(), // Context to pass to all agents
+  /**
+   * Context shared with all spawned agents.
+   * Examples: API contracts, shared types, project conventions, architectural decisions.
+   */
+  shared_context: z.string().optional(),
 });
 export type TaskDecomposition = z.infer<typeof TaskDecompositionSchema>;
 
@@ -78,11 +92,19 @@ export type DecomposeArgs = z.infer<typeof DecomposeArgsSchema>;
  */
 export const SpawnedAgentSchema = z.object({
   bead_id: z.string(),
-  agent_name: z.string(), // Agent Mail name (e.g., "BlueLake")
+  /**
+   * Agent Mail assigned name (e.g., 'BlueLake', 'CrimsonRiver').
+   * Generated by Agent Mail on session init.
+   */
+  agent_name: z.string(),
   task_id: z.string().optional(), // OpenCode task ID
   status: z.enum(["pending", "running", "completed", "failed"]),
   files: z.array(z.string()), // Reserved files
-  reservation_ids: z.array(z.number()).optional(), // Agent Mail reservation IDs
+  /**
+   * Agent Mail reservation IDs for file locking.
+   * Used to release locks on task completion via agentmail_release.
+   */
+  reservation_ids: z.array(z.number()).optional(),
 });
 export type SpawnedAgent = z.infer<typeof SpawnedAgentSchema>;
 
@@ -101,16 +123,22 @@ export type SwarmSpawnResult = z.infer<typeof SwarmSpawnResultSchema>;
 /**
  * Progress update from an agent
  */
-export const AgentProgressSchema = z.object({
-  bead_id: z.string(),
-  agent_name: z.string(),
-  status: z.enum(["in_progress", "blocked", "completed", "failed"]),
-  progress_percent: z.number().min(0).max(100).optional(),
-  message: z.string().optional(),
-  files_touched: z.array(z.string()).optional(),
-  blockers: z.array(z.string()).optional(),
-  timestamp: z.string().datetime({ offset: true }), // ISO-8601 with timezone
-});
+export const AgentProgressSchema = z
+  .object({
+    bead_id: z.string(),
+    agent_name: z.string(),
+    status: z.enum(["in_progress", "blocked", "completed", "failed"]),
+    progress_percent: z.number().min(0).max(100).optional(),
+    message: z.string().optional(),
+    files_touched: z.array(z.string()).optional(),
+    blockers: z.array(z.string()).optional(),
+    timestamp: z.string().datetime({ offset: true }), // ISO-8601 with timezone
+  })
+  .refine(
+    (data) =>
+      data.status !== "blocked" || (data.blockers && data.blockers.length > 0),
+    { message: "blockers array required when status is 'blocked'" },
+  );
 export type AgentProgress = z.infer<typeof AgentProgressSchema>;
 
 /**

package/src/streams/debug.ts

@@ -5,7 +5,7 @@
  * Useful for debugging issues and understanding system behavior.
  */
 import { getDatabase, getDatabaseStats } from "./index";
-import { readEvents, getLatestSequence } from "./store";
+import { readEvents, getLatestSequence, replayEventsBatched } from "./store";
 import { getAgent, getActiveReservations, getMessage } from "./projections";
 import type { AgentEvent } from "./events";
 
@@ -231,11 +231,27 @@ function getAgentFromEvent(event: AgentEvent): string {
 
 /**
  * Get recent events with filtering
+ *
+ * For large event logs (>100k events), consider using batchSize option
+ * to paginate through results instead of loading all events.
  */
 export async function debugEvents(
-  options: DebugEventsOptions,
+  options: DebugEventsOptions & { batchSize?: number },
 ): Promise<DebugEventsResult> {
-  const { projectPath, types, agentName, limit = 50, since, until } = options;
+  const {
+    projectPath,
+    types,
+    agentName,
+    limit = 50,
+    since,
+    until,
+    batchSize,
+  } = options;
+
+  // If batchSize is specified, use pagination to avoid OOM
+  if (batchSize && batchSize > 0) {
+    return await debugEventsPaginated({ ...options, batchSize });
+  }
 
   // Get all events first (we'll filter in memory for agent name)
   const allEvents = await readEvents(
@@ -284,6 +300,88 @@ export async function debugEvents(
   };
 }
 
+/**
+ * Get events using pagination to avoid OOM on large logs
+ */
+async function debugEventsPaginated(
+  options: DebugEventsOptions & { batchSize: number },
+): Promise<DebugEventsResult> {
+  const {
+    projectPath,
+    types,
+    agentName,
+    limit = 50,
+    since,
+    until,
+    batchSize,
+  } = options;
+
+  const allEvents: Array<AgentEvent & { id: number; sequence: number }> = [];
+  let offset = 0;
+  let hasMore = true;
+
+  // Fetch in batches until we have enough events or run out
+  while (hasMore && allEvents.length < limit) {
+    const batch = await readEvents(
+      {
+        projectKey: projectPath,
+        types,
+        since,
+        until,
+        limit: batchSize,
+        offset,
+      },
+      projectPath,
+    );
+
+    if (batch.length === 0) {
+      hasMore = false;
+      break;
+    }
+
+    // Filter by agent name if specified
+    const filtered = agentName
+      ? batch.filter((e) => {
+          if ("agent_name" in e && e.agent_name === agentName) return true;
+          if ("from_agent" in e && e.from_agent === agentName) return true;
+          if ("to_agents" in e && e.to_agents?.includes(agentName)) return true;
+          return false;
+        })
+      : batch;
+
+    allEvents.push(...filtered);
+    offset += batchSize;
+
+    console.log(
+      `[SwarmMail] Fetched ${allEvents.length} events (batch size: ${batchSize})`,
+    );
+  }
+
+  // Sort by sequence descending (most recent first)
+  allEvents.sort((a, b) => b.sequence - a.sequence);
+
+  // Apply limit
+  const limitedEvents = allEvents.slice(0, limit);
+
+  // Format for output
+  const events: DebugEventResult[] = limitedEvents.map((e) => {
+    const { id, sequence, type, timestamp, project_key, ...rest } = e;
+    return {
+      id,
+      sequence,
+      type,
+      timestamp,
+      timestamp_human: formatTimestamp(timestamp),
+      ...rest,
+    };
+  });
+
+  return {
+    events,
+    total: allEvents.length,
+  };
+}
+
 /**
  * Get detailed agent information
  */

package/src/streams/events.ts

@@ -174,6 +174,28 @@ export type TaskProgressEvent = z.infer<typeof TaskProgressEventSchema>;
 export type TaskCompletedEvent = z.infer<typeof TaskCompletedEventSchema>;
 export type TaskBlockedEvent = z.infer<typeof TaskBlockedEventSchema>;
 
+// ============================================================================
+// Session State Types
+// ============================================================================
+
+/**
+ * Shared session state for Agent Mail and Swarm Mail
+ *
+ * Common fields for tracking agent coordination session across both
+ * the MCP-based implementation (agent-mail) and the embedded event-sourced
+ * implementation (swarm-mail).
+ */
+export interface MailSessionState {
+  /** Project key (usually absolute path) */
+  projectKey: string;
+  /** Agent name for this session */
+  agentName: string;
+  /** Active reservation IDs */
+  reservations: number[];
+  /** Session start timestamp (ISO-8601) */
+  startedAt: string;
+}
+
 // ============================================================================
 // Event Helpers
 // ============================================================================

package/src/streams/index.ts

@@ -1,5 +1,30 @@
 /**
- * PGLite Event Store Setup
+ * SwarmMail Event Store - PGLite-based event sourcing
+ *
+ * ## Thread Safety
+ *
+ * PGLite runs in-process as a single-threaded SQLite-compatible database.
+ * While Node.js is single-threaded, async operations can interleave.
+ *
+ * **Concurrency Model:**
+ * - Single PGLite instance per project (singleton pattern via LRU cache)
+ * - Transactions provide isolation for multi-statement operations
+ * - appendEvents uses BEGIN/COMMIT for atomic event batches
+ * - Concurrent reads are safe (no locks needed)
+ * - Concurrent writes are serialized by PGLite internally
+ *
+ * **Race Condition Mitigations:**
+ * - File reservations use INSERT with conflict detection
+ * - Sequence numbers are auto-incremented by database
+ * - Materialized views updated within same transaction as events
+ * - Pending instance promises prevent duplicate initialization
+ *
+ * **Known Limitations:**
+ * - No distributed locking (single-process only)
+ * - Large transactions may block other operations
+ * - No connection pooling (embedded database)
+ *
+ * ## Database Setup
  *
  * Embedded PostgreSQL database for event sourcing.
  * No external server required - runs in-process.
@@ -41,6 +66,38 @@ export async function withTimeout<T>(
   return Promise.race([promise, timeout]);
 }
 
+// ============================================================================
+// Performance Monitoring
+// ============================================================================
+
+/** Threshold for slow query warnings in milliseconds */
+const SLOW_QUERY_THRESHOLD_MS = 100;
+
+/**
+ * Execute a database operation with timing instrumentation.
+ * Logs a warning if the operation exceeds SLOW_QUERY_THRESHOLD_MS.
+ *
+ * @param operation - Name of the operation for logging
+ * @param fn - Async function to execute
+ * @returns Result of the function
+ */
+export async function withTiming<T>(
+  operation: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const start = performance.now();
+  try {
+    return await fn();
+  } finally {
+    const duration = performance.now() - start;
+    if (duration > SLOW_QUERY_THRESHOLD_MS) {
+      console.warn(
+        `[SwarmMail] Slow operation: ${operation} took ${duration.toFixed(1)}ms`,
+      );
+    }
+  }
+}
+
 // ============================================================================
 // Debug Logging
 // ============================================================================