opencode-swarm-plugin 0.19.0 → 0.21.0

package/src/schemas/index.ts

@@ -125,3 +125,21 @@ export {
   type QueryMandatesArgs,
   type ScoreCalculationResult,
 } from "./mandate";
+
+// Swarm context schemas
+export {
+  SwarmStrategySchema,
+  SwarmDirectivesSchema,
+  SwarmRecoverySchema,
+  SwarmBeadContextSchema,
+  CreateSwarmContextArgsSchema,
+  UpdateSwarmContextArgsSchema,
+  QuerySwarmContextsArgsSchema,
+  type SwarmStrategy,
+  type SwarmDirectives,
+  type SwarmRecovery,
+  type SwarmBeadContext,
+  type CreateSwarmContextArgs,
+  type UpdateSwarmContextArgs,
+  type QuerySwarmContextsArgs,
+} from "./swarm-context";

package/src/schemas/swarm-context.ts

@@ -0,0 +1,115 @@
+/**
+ * Swarm Context Schemas
+ *
+ * These schemas define the structure for storing and recovering swarm execution context.
+ * Used for checkpoint/recovery, continuation after crashes, and swarm state management.
+ */
+import { z } from "zod";
+
+/**
+ * Decomposition strategy used for the swarm
+ */
+export const SwarmStrategySchema = z.enum([
+  "file-based",
+  "feature-based",
+  "risk-based",
+]);
+export type SwarmStrategy = z.infer<typeof SwarmStrategySchema>;
+
+/**
+ * Shared directives and context for all agents in a swarm
+ */
+export const SwarmDirectivesSchema = z.object({
+  /** Context shared with all agents (API contracts, conventions, arch decisions) */
+  shared_context: z.string(),
+  /** Skills to load in agent context (e.g., ['testing-patterns', 'swarm-coordination']) */
+  skills_to_load: z.array(z.string()).default([]),
+  /** Notes from coordinator to agents (gotchas, important context) */
+  coordinator_notes: z.string().default(""),
+});
+export type SwarmDirectives = z.infer<typeof SwarmDirectivesSchema>;
+
+/**
+ * Recovery state for checkpoint/resume
+ */
+export const SwarmRecoverySchema = z.object({
+  /** Last known checkpoint (ISO-8601 timestamp or checkpoint ID) */
+  last_checkpoint: z.string(),
+  /** Files modified since checkpoint (for rollback/recovery) */
+  files_modified: z.array(z.string()).default([]),
+  /** Progress percentage (0-100) */
+  progress_percent: z.number().min(0).max(100).default(0),
+  /** Last status message from agent */
+  last_message: z.string().default(""),
+  /** Error context if agent failed (for retry/recovery) */
+  error_context: z.string().optional(),
+});
+export type SwarmRecovery = z.infer<typeof SwarmRecoverySchema>;
+
+/**
+ * Complete context for a single bead in a swarm
+ *
+ * Stored in swarm_contexts table for recovery, continuation, and state management.
+ */
+export const SwarmBeadContextSchema = z.object({
+  /** ID of the swarm context record */
+  id: z.string(),
+  /** Epic this bead belongs to */
+  epic_id: z.string(),
+  /** Bead ID being executed */
+  bead_id: z.string(),
+  /** Decomposition strategy used */
+  strategy: SwarmStrategySchema,
+  /** Files this bead is responsible for */
+  files: z.array(z.string()),
+  /** Bead IDs this task depends on */
+  dependencies: z.array(z.string()).default([]),
+  /** Shared directives and context */
+  directives: SwarmDirectivesSchema,
+  /** Recovery state */
+  recovery: SwarmRecoverySchema,
+  /** Creation timestamp (epoch ms) */
+  created_at: z.number().int().positive(),
+  /** Last update timestamp (epoch ms) */
+  updated_at: z.number().int().positive(),
+});
+export type SwarmBeadContext = z.infer<typeof SwarmBeadContextSchema>;
+
+/**
+ * Args for creating a swarm context
+ */
+export const CreateSwarmContextArgsSchema = SwarmBeadContextSchema.omit({
+  id: true,
+  created_at: true,
+  updated_at: true,
+});
+export type CreateSwarmContextArgs = z.infer<
+  typeof CreateSwarmContextArgsSchema
+>;
+
+/**
+ * Args for updating a swarm context
+ */
+export const UpdateSwarmContextArgsSchema = z.object({
+  id: z.string(),
+  recovery: SwarmRecoverySchema.partial().optional(),
+  files: z.array(z.string()).optional(),
+  dependencies: z.array(z.string()).optional(),
+  directives: SwarmDirectivesSchema.partial().optional(),
+});
+export type UpdateSwarmContextArgs = z.infer<
+  typeof UpdateSwarmContextArgsSchema
+>;
+
+/**
+ * Args for querying swarm contexts
+ */
+export const QuerySwarmContextsArgsSchema = z.object({
+  epic_id: z.string().optional(),
+  bead_id: z.string().optional(),
+  strategy: SwarmStrategySchema.optional(),
+  has_errors: z.boolean().optional(), // Filter by presence of error_context
+});
+export type QuerySwarmContextsArgs = z.infer<
+  typeof QuerySwarmContextsArgsSchema
+>;

package/src/streams/events.test.ts

@@ -21,6 +21,9 @@ import {
   TaskProgressEventSchema,
   TaskCompletedEventSchema,
   TaskBlockedEventSchema,
+  DecompositionGeneratedEventSchema,
+  SubtaskOutcomeEventSchema,
+  HumanFeedbackEventSchema,
   createEvent,
   isEventType,
   type AgentEvent,
@@ -361,6 +364,299 @@ describe("TaskBlockedEventSchema", () => {
   });
 });
 
+describe("DecompositionGeneratedEventSchema", () => {
+  it("validates a complete decomposition_generated event", () => {
+    const event = {
+      type: "decomposition_generated",
+      project_key: "/test/project",
+      timestamp: Date.now(),
+      epic_id: "bd-123",
+      task: "Add user authentication",
+      context: "OAuth integration for GitHub",
+      strategy: "feature-based",
+      epic_title: "User Authentication",
+      subtasks: [
+        {
+          title: "Create OAuth flow",
+          files: ["src/auth/oauth.ts"],
+          priority: 2,
+        },
+        { title: "Add login UI", files: ["src/ui/login.tsx"], priority: 1 },
+      ],
+    };
+    expect(() => DecompositionGeneratedEventSchema.parse(event)).not.toThrow();
+  });
+
+  it("validates without optional context", () => {
+    const event = {
+      type: "decomposition_generated",
+      project_key: "/test/project",
+      timestamp: Date.now(),
+      epic_id: "bd-123",
+      task: "Add user authentication",
+      strategy: "file-based",
+      epic_title: "User Authentication",
+      subtasks: [{ title: "Create OAuth flow", files: ["src/auth/oauth.ts"] }],
+    };
+    expect(() => DecompositionGeneratedEventSchema.parse(event)).not.toThrow();
+  });
+
+  it("validates strategy enum values", () => {
+    const validStrategies = ["file-based", "feature-based", "risk-based"];
+    for (const strategy of validStrategies) {
+      const event = {
+        type: "decomposition_generated",
+        project_key: "/test/project",
+        timestamp: Date.now(),
+        epic_id: "bd-123",
+        task: "Test task",
+        strategy,
+        epic_title: "Test",
+        subtasks: [{ title: "Subtask", files: ["test.ts"] }],
+      };
+      expect(() =>
+        DecompositionGeneratedEventSchema.parse(event),
+      ).not.toThrow();
+    }
+  });
+
+  it("rejects invalid strategy value", () => {
+    const event = {
+      type: "decomposition_generated",
+      project_key: "/test/project",
+      timestamp: Date.now(),
+      epic_id: "bd-123",
+      task: "Test task",
+      strategy: "invalid-strategy",
+      epic_title: "Test",
+      subtasks: [{ title: "Subtask", files: ["test.ts"] }],
+    };
+    expect(() => DecompositionGeneratedEventSchema.parse(event)).toThrow();
+  });
+
+  it("validates subtask priority bounds", () => {
+    const baseEvent = {
+      type: "decomposition_generated",
+      project_key: "/test/project",
+      timestamp: Date.now(),
+      epic_id: "bd-123",
+      task: "Test",
+      strategy: "file-based",
+      epic_title: "Test",
+    };
+
+    // Valid: 0
+    expect(() =>
+      DecompositionGeneratedEventSchema.parse({
+        ...baseEvent,
+        subtasks: [{ title: "Test", files: ["test.ts"], priority: 0 }],
+      }),
+    ).not.toThrow();
+
+    // Valid: 3
+    expect(() =>
+      DecompositionGeneratedEventSchema.parse({
+        ...baseEvent,
+        subtasks: [{ title: "Test", files: ["test.ts"], priority: 3 }],
+      }),
+    ).not.toThrow();
+
+    // Invalid: -1
+    expect(() =>
+      DecompositionGeneratedEventSchema.parse({
+        ...baseEvent,
+        subtasks: [{ title: "Test", files: ["test.ts"], priority: -1 }],
+      }),
+    ).toThrow();
+
+    // Invalid: 4
+    expect(() =>
+      DecompositionGeneratedEventSchema.parse({
+        ...baseEvent,
+        subtasks: [{ title: "Test", files: ["test.ts"], priority: 4 }],
+      }),
+    ).toThrow();
+  });
+
+  it("rejects empty subtasks array", () => {
+    const event = {
+      type: "decomposition_generated",
+      project_key: "/test/project",
+      timestamp: Date.now(),
+      epic_id: "bd-123",
+      task: "Test",
+      strategy: "file-based",
+      epic_title: "Test",
+      subtasks: [],
+    };
+    // Empty subtasks is valid per schema but semantically questionable
+    expect(() => DecompositionGeneratedEventSchema.parse(event)).not.toThrow();
+  });
+});
+
+describe("SubtaskOutcomeEventSchema", () => {
+  it("validates a complete subtask_outcome event", () => {
+    const event = {
+      type: "subtask_outcome",
+      project_key: "/test/project",
+      timestamp: Date.now(),
+      epic_id: "bd-123",
+      bead_id: "bd-123.1",
+      planned_files: ["src/auth.ts", "src/config.ts"],
+      actual_files: ["src/auth.ts", "src/config.ts", "src/utils.ts"],
+      duration_ms: 45000,
+      error_count: 2,
+      retry_count: 1,
+      success: true,
+    };
+    expect(() => SubtaskOutcomeEventSchema.parse(event)).not.toThrow();
+  });
+
+  it("applies defaults for error_count and retry_count", () => {
+    const event = {
+      type: "subtask_outcome",
+      project_key: "/test/project",
+      timestamp: Date.now(),
+      epic_id: "bd-123",
+      bead_id: "bd-123.1",
+      planned_files: ["src/auth.ts"],
+      actual_files: ["src/auth.ts"],
+      duration_ms: 10000,
+      success: true,
+    };
+    const parsed = SubtaskOutcomeEventSchema.parse(event);
+    expect(parsed.error_count).toBe(0);
+    expect(parsed.retry_count).toBe(0);
+  });
+
+  it("validates duration_ms is non-negative", () => {
+    const baseEvent = {
+      type: "subtask_outcome",
+      project_key: "/test/project",
+      timestamp: Date.now(),
+      epic_id: "bd-123",
+      bead_id: "bd-123.1",
+      planned_files: ["test.ts"],
+      actual_files: ["test.ts"],
+      success: true,
+    };
+
+    // Valid: 0
+    expect(() =>
+      SubtaskOutcomeEventSchema.parse({ ...baseEvent, duration_ms: 0 }),
+    ).not.toThrow();
+
+    // Valid: positive
+    expect(() =>
+      SubtaskOutcomeEventSchema.parse({ ...baseEvent, duration_ms: 1000 }),
+    ).not.toThrow();
+
+    // Invalid: negative
+    expect(() =>
+      SubtaskOutcomeEventSchema.parse({ ...baseEvent, duration_ms: -1 }),
+    ).toThrow();
+  });
+
+  it("validates error_count is non-negative", () => {
+    const baseEvent = {
+      type: "subtask_outcome",
+      project_key: "/test/project",
+      timestamp: Date.now(),
+      epic_id: "bd-123",
+      bead_id: "bd-123.1",
+      planned_files: ["test.ts"],
+      actual_files: ["test.ts"],
+      duration_ms: 1000,
+      success: true,
+    };
+
+    // Invalid: negative
+    expect(() =>
+      SubtaskOutcomeEventSchema.parse({ ...baseEvent, error_count: -1 }),
+    ).toThrow();
+  });
+
+  it("handles file lists with different lengths", () => {
+    const event = {
+      type: "subtask_outcome",
+      project_key: "/test/project",
+      timestamp: Date.now(),
+      epic_id: "bd-123",
+      bead_id: "bd-123.1",
+      planned_files: ["a.ts", "b.ts"],
+      actual_files: ["a.ts", "b.ts", "c.ts", "d.ts"],
+      duration_ms: 5000,
+      success: true,
+    };
+    expect(() => SubtaskOutcomeEventSchema.parse(event)).not.toThrow();
+  });
+});
+
+describe("HumanFeedbackEventSchema", () => {
+  it("validates a complete human_feedback event", () => {
+    const event = {
+      type: "human_feedback",
+      project_key: "/test/project",
+      timestamp: Date.now(),
+      epic_id: "bd-123",
+      accepted: true,
+      modified: false,
+      notes: "Looks good, no changes needed",
+    };
+    expect(() => HumanFeedbackEventSchema.parse(event)).not.toThrow();
+  });
+
+  it("validates accepted with modification", () => {
+    const event = {
+      type: "human_feedback",
+      project_key: "/test/project",
+      timestamp: Date.now(),
+      epic_id: "bd-123",
+      accepted: true,
+      modified: true,
+      notes: "Changed priority on subtask 2",
+    };
+    expect(() => HumanFeedbackEventSchema.parse(event)).not.toThrow();
+  });
+
+  it("validates rejected feedback", () => {
+    const event = {
+      type: "human_feedback",
+      project_key: "/test/project",
+      timestamp: Date.now(),
+      epic_id: "bd-123",
+      accepted: false,
+      modified: false,
+      notes: "Decomposition too granular, needs consolidation",
+    };
+    expect(() => HumanFeedbackEventSchema.parse(event)).not.toThrow();
+  });
+
+  it("applies default for modified", () => {
+    const event = {
+      type: "human_feedback",
+      project_key: "/test/project",
+      timestamp: Date.now(),
+      epic_id: "bd-123",
+      accepted: true,
+    };
+    const parsed = HumanFeedbackEventSchema.parse(event);
+    expect(parsed.modified).toBe(false);
+  });
+
+  it("validates without notes", () => {
+    const event = {
+      type: "human_feedback",
+      project_key: "/test/project",
+      timestamp: Date.now(),
+      epic_id: "bd-123",
+      accepted: true,
+      modified: false,
+    };
+    expect(() => HumanFeedbackEventSchema.parse(event)).not.toThrow();
+  });
+});
+
 // ============================================================================
 // Discriminated Union Tests
 // ============================================================================

package/src/streams/events.ts

@@ -141,6 +141,85 @@ export const TaskBlockedEventSchema = BaseEventSchema.extend({
   reason: z.string(),
 });
 
+// ============================================================================
+// Eval Capture Events (for learning system)
+// ============================================================================
+
+export const DecompositionGeneratedEventSchema = BaseEventSchema.extend({
+  type: z.literal("decomposition_generated"),
+  epic_id: z.string(),
+  task: z.string(),
+  context: z.string().optional(),
+  strategy: z.enum(["file-based", "feature-based", "risk-based"]),
+  epic_title: z.string(),
+  subtasks: z.array(
+    z.object({
+      title: z.string(),
+      files: z.array(z.string()),
+      priority: z.number().min(0).max(3).optional(),
+    }),
+  ),
+  recovery_context: z
+    .object({
+      shared_context: z.string().optional(),
+      skills_to_load: z.array(z.string()).optional(),
+      coordinator_notes: z.string().optional(),
+    })
+    .optional(),
+});
+
+export const SubtaskOutcomeEventSchema = BaseEventSchema.extend({
+  type: z.literal("subtask_outcome"),
+  epic_id: z.string(),
+  bead_id: z.string(),
+  planned_files: z.array(z.string()),
+  actual_files: z.array(z.string()),
+  duration_ms: z.number().min(0),
+  error_count: z.number().min(0).default(0),
+  retry_count: z.number().min(0).default(0),
+  success: z.boolean(),
+});
+
+export const HumanFeedbackEventSchema = BaseEventSchema.extend({
+  type: z.literal("human_feedback"),
+  epic_id: z.string(),
+  accepted: z.boolean(),
+  modified: z.boolean().default(false),
+  notes: z.string().optional(),
+});
+
+// ============================================================================
+// Swarm Checkpoint Events (for recovery and coordination)
+// ============================================================================
+
+export const SwarmCheckpointedEventSchema = BaseEventSchema.extend({
+  type: z.literal("swarm_checkpointed"),
+  epic_id: z.string(),
+  bead_id: z.string(),
+  strategy: z.enum(["file-based", "feature-based", "risk-based"]),
+  files: z.array(z.string()),
+  dependencies: z.array(z.string()),
+  directives: z.object({
+    shared_context: z.string().optional(),
+    skills_to_load: z.array(z.string()).optional(),
+    coordinator_notes: z.string().optional(),
+  }),
+  recovery: z.object({
+    last_checkpoint: z.number(),
+    files_modified: z.array(z.string()),
+    progress_percent: z.number().min(0).max(100),
+    last_message: z.string().optional(),
+    error_context: z.string().optional(),
+  }),
+});
+
+export const SwarmRecoveredEventSchema = BaseEventSchema.extend({
+  type: z.literal("swarm_recovered"),
+  epic_id: z.string(),
+  bead_id: z.string(),
+  recovered_from_checkpoint: z.number(), // timestamp
+});
+
 // ============================================================================
 // Union Type
 // ============================================================================
@@ -157,6 +236,11 @@ export const AgentEventSchema = z.discriminatedUnion("type", [
   TaskProgressEventSchema,
   TaskCompletedEventSchema,
   TaskBlockedEventSchema,
+  DecompositionGeneratedEventSchema,
+  SubtaskOutcomeEventSchema,
+  HumanFeedbackEventSchema,
+  SwarmCheckpointedEventSchema,
+  SwarmRecoveredEventSchema,
 ]);
 
 export type AgentEvent = z.infer<typeof AgentEventSchema>;
@@ -173,6 +257,37 @@ export type TaskStartedEvent = z.infer<typeof TaskStartedEventSchema>;
 export type TaskProgressEvent = z.infer<typeof TaskProgressEventSchema>;
 export type TaskCompletedEvent = z.infer<typeof TaskCompletedEventSchema>;
 export type TaskBlockedEvent = z.infer<typeof TaskBlockedEventSchema>;
+export type DecompositionGeneratedEvent = z.infer<
+  typeof DecompositionGeneratedEventSchema
+>;
+export type SubtaskOutcomeEvent = z.infer<typeof SubtaskOutcomeEventSchema>;
+export type HumanFeedbackEvent = z.infer<typeof HumanFeedbackEventSchema>;
+export type SwarmCheckpointedEvent = z.infer<
+  typeof SwarmCheckpointedEventSchema
+>;
+export type SwarmRecoveredEvent = z.infer<typeof SwarmRecoveredEventSchema>;
+
+// ============================================================================
+// 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