opencode-swarm-plugin 0.1.0

package/src/pattern-maturity.ts

@@ -0,0 +1,487 @@
+/**
+ * Pattern Maturity Module
+ *
+ * Tracks decomposition pattern maturity states through lifecycle:
+ * candidate → established → proven (or deprecated)
+ *
+ * Patterns start as candidates until they accumulate enough feedback.
+ * Strong positive feedback promotes to proven, strong negative deprecates.
+ *
+ * @see https://github.com/Dicklesworthstone/cass_memory_system/blob/main/src/scoring.ts#L73-L98
+ */
+import { z } from "zod";
+import { calculateDecayedValue } from "./learning";
+
+// ============================================================================
+// Schemas
+// ============================================================================
+
+/**
+ * Maturity state for a decomposition pattern
+ *
+ * - candidate: Not enough feedback to judge (< minFeedback events)
+ * - established: Enough feedback, neither proven nor deprecated
+ * - proven: Strong positive signal (high helpful, low harmful ratio)
+ * - deprecated: Strong negative signal (high harmful ratio)
+ */
+export const MaturityStateSchema = z.enum([
+  "candidate",
+  "established",
+  "proven",
+  "deprecated",
+]);
+export type MaturityState = z.infer<typeof MaturityStateSchema>;
+
+/**
+ * Pattern maturity tracking
+ *
+ * Tracks feedback counts and state transitions for a decomposition pattern.
+ */
+export const PatternMaturitySchema = z.object({
+  /** Unique identifier for the pattern */
+  pattern_id: z.string(),
+  /** Current maturity state */
+  state: MaturityStateSchema,
+  /** Number of helpful feedback events */
+  helpful_count: z.number().int().min(0),
+  /** Number of harmful feedback events */
+  harmful_count: z.number().int().min(0),
+  /** When the pattern was last validated (ISO-8601) */
+  last_validated: z.string(),
+  /** When the pattern was promoted to proven (ISO-8601) */
+  promoted_at: z.string().optional(),
+  /** When the pattern was deprecated (ISO-8601) */
+  deprecated_at: z.string().optional(),
+});
+export type PatternMaturity = z.infer<typeof PatternMaturitySchema>;
+
+/**
+ * Feedback event for maturity tracking
+ */
+export const MaturityFeedbackSchema = z.object({
+  /** Pattern this feedback applies to */
+  pattern_id: z.string(),
+  /** Whether the pattern was helpful or harmful */
+  type: z.enum(["helpful", "harmful"]),
+  /** When this feedback was recorded (ISO-8601) */
+  timestamp: z.string(),
+  /** Raw weight before decay (0-1) */
+  weight: z.number().min(0).max(1).default(1),
+});
+export type MaturityFeedback = z.infer<typeof MaturityFeedbackSchema>;
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+/**
+ * Configuration for maturity calculations
+ */
+export interface MaturityConfig {
+  /** Minimum feedback events before leaving candidate state */
+  minFeedback: number;
+  /** Minimum decayed helpful score to reach proven state */
+  minHelpful: number;
+  /** Maximum harmful ratio to reach/maintain proven state */
+  maxHarmful: number;
+  /** Harmful ratio threshold for deprecation */
+  deprecationThreshold: number;
+  /** Half-life for decay in days */
+  halfLifeDays: number;
+}
+
+export const DEFAULT_MATURITY_CONFIG: MaturityConfig = {
+  minFeedback: 3,
+  minHelpful: 5,
+  maxHarmful: 0.15, // 15% harmful is acceptable for proven
+  deprecationThreshold: 0.3, // 30% harmful triggers deprecation
+  halfLifeDays: 90,
+};
+
+// ============================================================================
+// Core Functions
+// ============================================================================
+
+/**
+ * Calculate decayed feedback counts
+ *
+ * Applies half-life decay to each feedback event based on age.
+ *
+ * @param feedbackEvents - Raw feedback events
+ * @param config - Maturity configuration
+ * @param now - Current timestamp for decay calculation
+ * @returns Decayed helpful and harmful totals
+ */
+export function calculateDecayedCounts(
+  feedbackEvents: MaturityFeedback[],
+  config: MaturityConfig = DEFAULT_MATURITY_CONFIG,
+  now: Date = new Date(),
+): { decayedHelpful: number; decayedHarmful: number } {
+  let decayedHelpful = 0;
+  let decayedHarmful = 0;
+
+  for (const event of feedbackEvents) {
+    const decay = calculateDecayedValue(
+      event.timestamp,
+      now,
+      config.halfLifeDays,
+    );
+    const value = event.weight * decay;
+
+    if (event.type === "helpful") {
+      decayedHelpful += value;
+    } else {
+      decayedHarmful += value;
+    }
+  }
+
+  return { decayedHelpful, decayedHarmful };
+}
+
+/**
+ * Calculate maturity state from feedback events
+ *
+ * State determination logic:
+ * 1. "deprecated" if harmful ratio > 0.3 AND total >= minFeedback
+ * 2. "candidate" if total < minFeedback (not enough data)
+ * 3. "proven" if decayedHelpful >= minHelpful AND harmfulRatio < maxHarmful
+ * 4. "established" otherwise (enough data but not yet proven)
+ *
+ * @param feedbackEvents - Feedback events for this pattern
+ * @param config - Maturity configuration
+ * @param now - Current timestamp for decay calculation
+ * @returns Calculated maturity state
+ */
+export function calculateMaturityState(
+  feedbackEvents: MaturityFeedback[],
+  config: MaturityConfig = DEFAULT_MATURITY_CONFIG,
+  now: Date = new Date(),
+): MaturityState {
+  const { decayedHelpful, decayedHarmful } = calculateDecayedCounts(
+    feedbackEvents,
+    config,
+    now,
+  );
+
+  const total = decayedHelpful + decayedHarmful;
+  const epsilon = 0.01; // Float comparison tolerance
+  const safeTotal = total > 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
+  ) {
+    return "deprecated";
+  }
+
+  // Candidate: not enough feedback yet
+  if (safeTotal < config.minFeedback - epsilon) {
+    return "candidate";
+  }
+
+  // Proven: strong positive signal
+  if (
+    decayedHelpful >= config.minHelpful - epsilon &&
+    harmfulRatio < config.maxHarmful
+  ) {
+    return "proven";
+  }
+
+  // Established: enough data but not proven
+  return "established";
+}
+
+/**
+ * Create initial pattern maturity record
+ *
+ * @param patternId - Unique pattern identifier
+ * @returns New PatternMaturity in candidate state
+ */
+export function createPatternMaturity(patternId: string): PatternMaturity {
+  return {
+    pattern_id: patternId,
+    state: "candidate",
+    helpful_count: 0,
+    harmful_count: 0,
+    last_validated: new Date().toISOString(),
+  };
+}
+
+/**
+ * Update pattern maturity with new feedback
+ *
+ * Records feedback, updates counts, and recalculates state.
+ *
+ * @param maturity - Current maturity record
+ * @param feedbackEvents - All feedback events for this pattern
+ * @param config - Maturity configuration
+ * @returns Updated maturity record
+ */
+export function updatePatternMaturity(
+  maturity: PatternMaturity,
+  feedbackEvents: MaturityFeedback[],
+  config: MaturityConfig = DEFAULT_MATURITY_CONFIG,
+): PatternMaturity {
+  const now = new Date();
+  const newState = calculateMaturityState(feedbackEvents, config, now);
+
+  // Count raw feedback (not decayed)
+  const helpfulCount = feedbackEvents.filter(
+    (e) => e.type === "helpful",
+  ).length;
+  const harmfulCount = feedbackEvents.filter(
+    (e) => e.type === "harmful",
+  ).length;
+
+  const updated: PatternMaturity = {
+    ...maturity,
+    state: newState,
+    helpful_count: helpfulCount,
+    harmful_count: harmfulCount,
+    last_validated: now.toISOString(),
+  };
+
+  // Track state transitions
+  if (newState === "proven" && maturity.state !== "proven") {
+    updated.promoted_at = now.toISOString();
+  }
+  if (newState === "deprecated" && maturity.state !== "deprecated") {
+    updated.deprecated_at = now.toISOString();
+  }
+
+  return updated;
+}
+
+/**
+ * Promote a pattern to proven state
+ *
+ * Manually promotes a pattern regardless of feedback counts.
+ * Use when external validation confirms pattern effectiveness.
+ *
+ * @param maturity - Current maturity record
+ * @returns Updated maturity record with proven state
+ */
+export function promotePattern(maturity: PatternMaturity): PatternMaturity {
+  if (maturity.state === "deprecated") {
+    throw new Error("Cannot promote a deprecated pattern");
+  }
+
+  if (maturity.state === "proven") {
+    return maturity; // Already proven
+  }
+
+  const now = new Date().toISOString();
+  return {
+    ...maturity,
+    state: "proven",
+    promoted_at: now,
+    last_validated: now,
+  };
+}
+
+/**
+ * Deprecate a pattern
+ *
+ * Manually deprecates a pattern regardless of feedback counts.
+ * Use when external validation shows pattern is harmful.
+ *
+ * @param maturity - Current maturity record
+ * @param reason - Optional reason for deprecation
+ * @returns Updated maturity record with deprecated state
+ */
+export function deprecatePattern(
+  maturity: PatternMaturity,
+  _reason?: string,
+): PatternMaturity {
+  if (maturity.state === "deprecated") {
+    return maturity; // Already deprecated
+  }
+
+  const now = new Date().toISOString();
+  return {
+    ...maturity,
+    state: "deprecated",
+    deprecated_at: now,
+    last_validated: now,
+  };
+}
+
+/**
+ * Get maturity score multiplier for pattern ranking
+ *
+ * Higher maturity patterns should be weighted more heavily.
+ *
+ * @param state - Maturity state
+ * @returns Score multiplier (0-1.5)
+ */
+export function getMaturityMultiplier(state: MaturityState): number {
+  const multipliers: Record<MaturityState, number> = {
+    candidate: 0.5,
+    established: 1.0,
+    proven: 1.5,
+    deprecated: 0,
+  };
+  return multipliers[state];
+}
+
+/**
+ * Format maturity state for inclusion in prompts
+ *
+ * Shows pattern reliability to help agents make informed decisions.
+ *
+ * @param maturity - Pattern maturity record
+ * @returns Formatted string describing pattern reliability
+ */
+export function formatMaturityForPrompt(maturity: PatternMaturity): string {
+  const total = maturity.helpful_count + maturity.harmful_count;
+  const harmfulRatio =
+    total > 0 ? Math.round((maturity.harmful_count / total) * 100) : 0;
+  const helpfulRatio =
+    total > 0 ? Math.round((maturity.helpful_count / total) * 100) : 0;
+
+  switch (maturity.state) {
+    case "candidate":
+      return `[CANDIDATE - ${total} observations, needs more data]`;
+    case "established":
+      return `[ESTABLISHED - ${helpfulRatio}% helpful, ${harmfulRatio}% harmful from ${total} observations]`;
+    case "proven":
+      return `[PROVEN - ${helpfulRatio}% helpful from ${total} observations]`;
+    case "deprecated":
+      return `[DEPRECATED - ${harmfulRatio}% harmful, avoid using]`;
+  }
+}
+
+/**
+ * Format multiple patterns with maturity for prompt inclusion
+ *
+ * Groups patterns by maturity state for clear presentation.
+ *
+ * @param patterns - Map of pattern content to maturity record
+ * @returns Formatted string for prompt inclusion
+ */
+export function formatPatternsWithMaturityForPrompt(
+  patterns: Map<string, PatternMaturity>,
+): string {
+  const proven: string[] = [];
+  const established: string[] = [];
+  const candidates: string[] = [];
+  const deprecated: string[] = [];
+
+  for (const [content, maturity] of patterns) {
+    const formatted = `- ${content} ${formatMaturityForPrompt(maturity)}`;
+    switch (maturity.state) {
+      case "proven":
+        proven.push(formatted);
+        break;
+      case "established":
+        established.push(formatted);
+        break;
+      case "candidate":
+        candidates.push(formatted);
+        break;
+      case "deprecated":
+        deprecated.push(formatted);
+        break;
+    }
+  }
+
+  const sections: string[] = [];
+
+  if (proven.length > 0) {
+    sections.push(
+      "## Proven Patterns\n\nThese patterns consistently work well:\n\n" +
+        proven.join("\n"),
+    );
+  }
+
+  if (established.length > 0) {
+    sections.push(
+      "## Established Patterns\n\nThese patterns have track records:\n\n" +
+        established.join("\n"),
+    );
+  }
+
+  if (candidates.length > 0) {
+    sections.push(
+      "## Candidate Patterns\n\nThese patterns need more validation:\n\n" +
+        candidates.join("\n"),
+    );
+  }
+
+  if (deprecated.length > 0) {
+    sections.push(
+      "## Deprecated Patterns\n\nAVOID these patterns - they have poor track records:\n\n" +
+        deprecated.join("\n"),
+    );
+  }
+
+  return sections.join("\n\n");
+}
+
+// ============================================================================
+// Storage
+// ============================================================================
+
+/**
+ * Storage interface for pattern maturity records
+ */
+export interface MaturityStorage {
+  /** Store or update a maturity record */
+  store(maturity: PatternMaturity): Promise<void>;
+  /** Get maturity record by pattern ID */
+  get(patternId: string): Promise<PatternMaturity | null>;
+  /** Get all maturity records */
+  getAll(): Promise<PatternMaturity[]>;
+  /** Get patterns by state */
+  getByState(state: MaturityState): Promise<PatternMaturity[]>;
+  /** Store a feedback event */
+  storeFeedback(feedback: MaturityFeedback): Promise<void>;
+  /** Get all feedback for a pattern */
+  getFeedback(patternId: string): Promise<MaturityFeedback[]>;
+}
+
+/**
+ * In-memory maturity storage (for testing and short-lived sessions)
+ */
+export class InMemoryMaturityStorage implements MaturityStorage {
+  private maturities: Map<string, PatternMaturity> = new Map();
+  private feedback: MaturityFeedback[] = [];
+
+  async store(maturity: PatternMaturity): Promise<void> {
+    this.maturities.set(maturity.pattern_id, maturity);
+  }
+
+  async get(patternId: string): Promise<PatternMaturity | null> {
+    return this.maturities.get(patternId) ?? null;
+  }
+
+  async getAll(): Promise<PatternMaturity[]> {
+    return Array.from(this.maturities.values());
+  }
+
+  async getByState(state: MaturityState): Promise<PatternMaturity[]> {
+    return Array.from(this.maturities.values()).filter(
+      (m) => m.state === state,
+    );
+  }
+
+  async storeFeedback(feedback: MaturityFeedback): Promise<void> {
+    this.feedback.push(feedback);
+  }
+
+  async getFeedback(patternId: string): Promise<MaturityFeedback[]> {
+    return this.feedback.filter((f) => f.pattern_id === patternId);
+  }
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export const maturitySchemas = {
+  MaturityStateSchema,
+  PatternMaturitySchema,
+  MaturityFeedbackSchema,
+};

package/src/plugin.ts

@@ -0,0 +1,11 @@
+/**
+ * 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.)
+ */
+import { SwarmPlugin } from "./index";
+
+// Only export the plugin function - nothing else!
+export { SwarmPlugin };

package/src/schemas/bead.ts

@@ -0,0 +1,152 @@
+/**
+ * Bead schemas for type-safe beads operations
+ *
+ * These schemas validate all data from the `bd` CLI to ensure
+ * type safety and catch malformed responses early.
+ */
+import { z } from "zod";
+
+/** Valid bead statuses */
+export const BeadStatusSchema = z.enum([
+  "open",
+  "in_progress",
+  "blocked",
+  "closed",
+]);
+export type BeadStatus = z.infer<typeof BeadStatusSchema>;
+
+/** Valid bead types */
+export const BeadTypeSchema = z.enum([
+  "bug",
+  "feature",
+  "task",
+  "epic",
+  "chore",
+]);
+export type BeadType = z.infer<typeof BeadTypeSchema>;
+
+/** Dependency relationship between beads */
+export const BeadDependencySchema = z.object({
+  id: z.string(),
+  type: z.enum(["blocks", "blocked-by", "related", "discovered-from"]),
+});
+export type BeadDependency = z.infer<typeof BeadDependencySchema>;
+
+/**
+ * Core bead schema - validates bd CLI JSON output
+ *
+ * ID format:
+ * - Standard: `{project}-{hash}` (e.g., `opencode-swarm-plugin-1i8`)
+ * - Subtask: `{project}-{hash}.{index}` (e.g., `opencode-swarm-plugin-1i8.1`)
+ */
+export const BeadSchema = z.object({
+  id: z
+    .string()
+    .regex(/^[a-z0-9-]+-[a-z0-9]+(\.\d+)?$/, "Invalid bead ID format"),
+  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(), // ISO-8601
+  updated_at: z.string().optional(),
+  closed_at: z.string().optional(),
+  parent_id: z.string().optional(),
+  dependencies: z.array(BeadDependencySchema).optional().default([]),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+export type Bead = z.infer<typeof BeadSchema>;
+
+/** Arguments for creating a bead */
+export const BeadCreateArgsSchema = z.object({
+  title: z.string().min(1, "Title required"),
+  type: BeadTypeSchema.default("task"),
+  priority: z.number().int().min(0).max(3).default(2),
+  description: z.string().optional(),
+  parent_id: z.string().optional(),
+});
+export type BeadCreateArgs = z.infer<typeof BeadCreateArgsSchema>;
+
+/** Arguments for updating a bead */
+export const BeadUpdateArgsSchema = z.object({
+  id: z.string(),
+  status: BeadStatusSchema.optional(),
+  description: z.string().optional(),
+  priority: z.number().int().min(0).max(3).optional(),
+});
+export type BeadUpdateArgs = z.infer<typeof BeadUpdateArgsSchema>;
+
+/** Arguments for closing a bead */
+export const BeadCloseArgsSchema = z.object({
+  id: z.string(),
+  reason: z.string().min(1, "Reason required"),
+});
+export type BeadCloseArgs = z.infer<typeof BeadCloseArgsSchema>;
+
+/** Arguments for querying beads */
+export const BeadQueryArgsSchema = z.object({
+  status: BeadStatusSchema.optional(),
+  type: BeadTypeSchema.optional(),
+  ready: z.boolean().optional(),
+  limit: z.number().int().positive().default(20),
+});
+export type BeadQueryArgs = z.infer<typeof BeadQueryArgsSchema>;
+
+/**
+ * Subtask specification for epic decomposition
+ *
+ * Used when creating an epic with subtasks in one operation.
+ * The `files` array is used for Agent Mail file reservations.
+ */
+export const SubtaskSpecSchema = z.object({
+  title: z.string().min(1),
+  description: z.string().optional().default(""),
+  files: z.array(z.string()).default([]),
+  dependencies: z.array(z.number().int().min(0)).default([]), // Indices of other subtasks
+  estimated_complexity: z.number().int().min(1).max(5).default(3),
+});
+export type SubtaskSpec = z.infer<typeof SubtaskSpecSchema>;
+
+/**
+ * Bead tree for swarm decomposition
+ *
+ * Represents an epic with its subtasks, ready for spawning agents.
+ */
+export const BeadTreeSchema = z.object({
+  epic: z.object({
+    title: z.string().min(1),
+    description: z.string().optional().default(""),
+  }),
+  subtasks: z.array(SubtaskSpecSchema).min(1).max(10),
+});
+export type BeadTree = z.infer<typeof BeadTreeSchema>;
+
+/** Arguments for creating an epic with subtasks */
+export const EpicCreateArgsSchema = z.object({
+  epic_title: z.string().min(1),
+  epic_description: z.string().optional(),
+  subtasks: z
+    .array(
+      z.object({
+        title: z.string().min(1),
+        priority: z.number().int().min(0).max(3).default(2),
+        files: z.array(z.string()).optional().default([]),
+      }),
+    )
+    .min(1)
+    .max(10),
+});
+export type EpicCreateArgs = z.infer<typeof EpicCreateArgsSchema>;
+
+/**
+ * Result of epic creation
+ *
+ * Contains the created epic and all subtasks with their IDs.
+ */
+export const EpicCreateResultSchema = z.object({
+  success: z.boolean(),
+  epic: BeadSchema,
+  subtasks: z.array(BeadSchema),
+  rollback_hint: z.string().optional(),
+});
+export type EpicCreateResult = z.infer<typeof EpicCreateResultSchema>;