opencode-swarm-plugin 0.1.0

package/src/schemas/evaluation.ts

@@ -0,0 +1,133 @@
+/**
+ * Evaluation schemas for structured agent output validation
+ *
+ * These schemas define the expected format for agent self-evaluations
+ * and coordinator evaluations of completed work.
+ *
+ * Includes support for confidence decay - criteria weights fade over time
+ * unless revalidated by successful outcomes.
+ *
+ * @see src/learning.ts for decay calculations
+ */
+import { z } from "zod";
+
+/**
+ * Single criterion evaluation
+ *
+ * Each criterion (type_safe, no_bugs, etc.) gets its own evaluation.
+ */
+export const CriterionEvaluationSchema = z.object({
+  passed: z.boolean(),
+  feedback: z.string(),
+  score: z.number().min(0).max(1).optional(), // 0-1 normalized score
+});
+export type CriterionEvaluation = z.infer<typeof CriterionEvaluationSchema>;
+
+/**
+ * Weighted criterion evaluation with confidence decay
+ *
+ * Extends CriterionEvaluation with weight information from learning.
+ * Lower weights indicate criteria that have been historically unreliable.
+ */
+export const WeightedCriterionEvaluationSchema =
+  CriterionEvaluationSchema.extend({
+    /** Current weight after decay (0-1, lower = less reliable) */
+    weight: z.number().min(0).max(1).default(1),
+    /** Weighted score = score * weight */
+    weighted_score: z.number().min(0).max(1).optional(),
+    /** Whether this criterion is deprecated due to high failure rate */
+    deprecated: z.boolean().default(false),
+  });
+export type WeightedCriterionEvaluation = z.infer<
+  typeof WeightedCriterionEvaluationSchema
+>;
+
+/**
+ * Full evaluation result
+ *
+ * Returned by agents after completing a subtask.
+ * Used by coordinator to determine if work is acceptable.
+ */
+export const EvaluationSchema = z.object({
+  passed: z.boolean(),
+  criteria: z.record(z.string(), CriterionEvaluationSchema),
+  overall_feedback: z.string(),
+  retry_suggestion: z.string().nullable(),
+  timestamp: z.string().optional(), // ISO-8601
+});
+export type Evaluation = z.infer<typeof EvaluationSchema>;
+
+/**
+ * Default evaluation criteria
+ *
+ * These are the standard criteria used when none are specified.
+ * Can be overridden per-task or per-project.
+ */
+export const DEFAULT_CRITERIA = [
+  "type_safe",
+  "no_bugs",
+  "patterns",
+  "readable",
+] as const;
+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(),
+});
+export type EvaluationRequest = z.infer<typeof EvaluationRequestSchema>;
+
+/**
+ * Weighted evaluation result with confidence-adjusted scores
+ *
+ * Used when applying learned weights to evaluation criteria.
+ */
+export const WeightedEvaluationSchema = z.object({
+  passed: z.boolean(),
+  criteria: z.record(z.string(), WeightedCriterionEvaluationSchema),
+  overall_feedback: z.string(),
+  retry_suggestion: z.string().nullable(),
+  timestamp: z.string().optional(), // ISO-8601
+  /** Average weight across all criteria (indicates overall confidence) */
+  average_weight: z.number().min(0).max(1).optional(),
+  /** Raw score before weighting */
+  raw_score: z.number().min(0).max(1).optional(),
+  /** Weighted score after applying criterion weights */
+  weighted_score: z.number().min(0).max(1).optional(),
+});
+export type WeightedEvaluation = z.infer<typeof WeightedEvaluationSchema>;
+
+/**
+ * Aggregated evaluation results for a swarm
+ */
+export const SwarmEvaluationResultSchema = z.object({
+  epic_id: z.string(),
+  total: z.number().int().min(0),
+  passed: z.number().int().min(0),
+  failed: z.number().int().min(0),
+  evaluations: z.array(
+    z.object({
+      bead_id: z.string(),
+      evaluation: EvaluationSchema,
+    }),
+  ),
+  overall_passed: z.boolean(),
+  retry_needed: z.array(z.string()), // Bead IDs that need retry
+});
+export type SwarmEvaluationResult = z.infer<typeof SwarmEvaluationResultSchema>;
+
+/**
+ * Validation result with retry info
+ */
+export const ValidationResultSchema = z.object({
+  success: z.boolean(),
+  data: z.unknown().optional(),
+  attempts: z.number().int().min(1),
+  errors: z.array(z.string()).optional(),
+  extractionMethod: z.string().optional(),
+});
+export type ValidationResult = z.infer<typeof ValidationResultSchema>;

package/src/schemas/index.test.ts

@@ -0,0 +1,199 @@
+import { describe, expect, it } from "vitest";
+import {
+  BeadSchema,
+  BeadTypeSchema,
+  BeadCreateArgsSchema,
+  EpicCreateArgsSchema,
+  EvaluationSchema,
+  TaskDecompositionSchema,
+  DecomposedSubtaskSchema,
+  SwarmStatusSchema,
+  ValidationResultSchema,
+} from "./index";
+
+describe("BeadSchema", () => {
+  it("validates a complete bead", () => {
+    const bead = {
+      id: "bd-abc123",
+      title: "Fix the thing",
+      type: "bug",
+      status: "open",
+      priority: 1,
+      created_at: "2025-01-01T00:00:00Z",
+      updated_at: "2025-01-01T00:00:00Z",
+    };
+    expect(() => BeadSchema.parse(bead)).not.toThrow();
+  });
+
+  it("rejects invalid priority", () => {
+    const bead = {
+      id: "bd-abc123",
+      title: "Fix the thing",
+      type: "bug",
+      status: "open",
+      priority: 5, // Invalid: max is 3
+      created_at: "2025-01-01T00:00:00Z",
+      updated_at: "2025-01-01T00:00:00Z",
+    };
+    expect(() => BeadSchema.parse(bead)).toThrow();
+  });
+
+  it("accepts all valid types", () => {
+    const types = ["bug", "feature", "task", "epic", "chore"];
+    for (const type of types) {
+      expect(() => BeadTypeSchema.parse(type)).not.toThrow();
+    }
+  });
+});
+
+describe("BeadCreateArgsSchema", () => {
+  it("validates minimal create args", () => {
+    const args = { title: "New bead" };
+    const result = BeadCreateArgsSchema.parse(args);
+    expect(result.title).toBe("New bead");
+    expect(result.type).toBe("task"); // default
+    expect(result.priority).toBe(2); // default
+  });
+
+  it("rejects empty title", () => {
+    const args = { title: "" };
+    expect(() => BeadCreateArgsSchema.parse(args)).toThrow();
+  });
+});
+
+describe("EpicCreateArgsSchema", () => {
+  it("validates epic with subtasks", () => {
+    const args = {
+      epic_title: "Big feature",
+      subtasks: [
+        { title: "Part 1", priority: 2 },
+        { title: "Part 2", priority: 3 },
+      ],
+    };
+    expect(() => EpicCreateArgsSchema.parse(args)).not.toThrow();
+  });
+
+  it("requires at least one subtask", () => {
+    const args = {
+      epic_title: "Big feature",
+      subtasks: [],
+    };
+    expect(() => EpicCreateArgsSchema.parse(args)).toThrow();
+  });
+});
+
+describe("EvaluationSchema", () => {
+  it("validates a passing evaluation", () => {
+    const evaluation = {
+      passed: true,
+      criteria: {
+        type_safe: { passed: true, feedback: "All types correct" },
+        no_bugs: { passed: true, feedback: "No issues found" },
+      },
+      overall_feedback: "Good work",
+      retry_suggestion: null,
+    };
+    expect(() => EvaluationSchema.parse(evaluation)).not.toThrow();
+  });
+
+  it("validates a failing evaluation with retry suggestion", () => {
+    const evaluation = {
+      passed: false,
+      criteria: {
+        type_safe: { passed: false, feedback: "Missing types on line 42" },
+      },
+      overall_feedback: "Needs work",
+      retry_suggestion: "Add explicit types to the handler function",
+    };
+    expect(() => EvaluationSchema.parse(evaluation)).not.toThrow();
+  });
+});
+
+describe("TaskDecompositionSchema", () => {
+  it("validates a decomposition", () => {
+    const decomposition = {
+      task: "Add OAuth authentication",
+      reasoning: "Breaking into provider setup and integration",
+      subtasks: [
+        {
+          title: "Add OAuth provider",
+          description: "Configure Google OAuth",
+          files: ["src/auth/google.ts"],
+          estimated_effort: "medium" as const,
+        },
+      ],
+      dependencies: [],
+      shared_context: "Using NextAuth.js",
+    };
+    expect(() => TaskDecompositionSchema.parse(decomposition)).not.toThrow();
+  });
+
+  it("validates subtask effort levels", () => {
+    const efforts = ["trivial", "small", "medium", "large"];
+    for (const effort of efforts) {
+      const subtask = {
+        title: "Test",
+        description: "Test description",
+        files: [],
+        estimated_effort: effort,
+      };
+      expect(() => DecomposedSubtaskSchema.parse(subtask)).not.toThrow();
+    }
+  });
+});
+
+describe("SwarmStatusSchema", () => {
+  it("validates swarm status", () => {
+    const status = {
+      epic_id: "bd-epic123",
+      total_agents: 3,
+      running: 1,
+      completed: 1,
+      failed: 0,
+      blocked: 1,
+      agents: [
+        {
+          bead_id: "bd-1",
+          agent_name: "BlueLake",
+          status: "completed" as const,
+          files: ["src/a.ts"],
+        },
+        {
+          bead_id: "bd-2",
+          agent_name: "RedStone",
+          status: "running" as const,
+          files: ["src/b.ts"],
+        },
+        {
+          bead_id: "bd-3",
+          agent_name: "GreenCastle",
+          status: "pending" as const,
+          files: ["src/c.ts"],
+        },
+      ],
+      last_update: "2025-01-01T00:00:00Z",
+    };
+    expect(() => SwarmStatusSchema.parse(status)).not.toThrow();
+  });
+});
+
+describe("ValidationResultSchema", () => {
+  it("validates success result", () => {
+    const result = {
+      success: true,
+      data: { foo: "bar" },
+      attempts: 1,
+      extractionMethod: "direct",
+    };
+    expect(() => ValidationResultSchema.parse(result)).not.toThrow();
+  });
+
+  it("validates failure result with errors", () => {
+    const result = {
+      success: false,
+      attempts: 2,
+      errors: ["Missing required field: name", "Invalid type for age"],
+    };
+    expect(() => ValidationResultSchema.parse(result)).not.toThrow();
+  });
+});

package/src/schemas/index.ts

@@ -0,0 +1,77 @@
+/**
+ * Schema exports
+ *
+ * Re-export all schemas for convenient importing.
+ */
+
+// Bead schemas
+export {
+  BeadStatusSchema,
+  BeadTypeSchema,
+  BeadDependencySchema,
+  BeadSchema,
+  BeadCreateArgsSchema,
+  BeadUpdateArgsSchema,
+  BeadCloseArgsSchema,
+  BeadQueryArgsSchema,
+  SubtaskSpecSchema,
+  BeadTreeSchema,
+  EpicCreateArgsSchema,
+  EpicCreateResultSchema,
+  type BeadStatus,
+  type BeadType,
+  type BeadDependency,
+  type Bead,
+  type BeadCreateArgs,
+  type BeadUpdateArgs,
+  type BeadCloseArgs,
+  type BeadQueryArgs,
+  type SubtaskSpec,
+  type BeadTree,
+  type EpicCreateArgs,
+  type EpicCreateResult,
+} from "./bead";
+
+// Evaluation schemas
+export {
+  CriterionEvaluationSchema,
+  WeightedCriterionEvaluationSchema,
+  EvaluationSchema,
+  WeightedEvaluationSchema,
+  EvaluationRequestSchema,
+  SwarmEvaluationResultSchema,
+  ValidationResultSchema,
+  DEFAULT_CRITERIA,
+  type CriterionEvaluation,
+  type WeightedCriterionEvaluation,
+  type Evaluation,
+  type WeightedEvaluation,
+  type EvaluationRequest,
+  type SwarmEvaluationResult,
+  type ValidationResult,
+  type DefaultCriterion,
+} from "./evaluation";
+
+// Task schemas
+export {
+  EffortLevelSchema,
+  DependencyTypeSchema,
+  DecomposedSubtaskSchema,
+  SubtaskDependencySchema,
+  TaskDecompositionSchema,
+  DecomposeArgsSchema,
+  SpawnedAgentSchema,
+  SwarmSpawnResultSchema,
+  AgentProgressSchema,
+  SwarmStatusSchema,
+  type EffortLevel,
+  type DependencyType,
+  type DecomposedSubtask,
+  type SubtaskDependency,
+  type TaskDecomposition,
+  type DecomposeArgs,
+  type SpawnedAgent,
+  type SwarmSpawnResult,
+  type AgentProgress,
+  type SwarmStatus,
+} from "./task";

package/src/schemas/task.ts

@@ -0,0 +1,129 @@
+/**
+ * Task decomposition schemas
+ *
+ * These schemas define the structure for breaking down tasks
+ * into parallelizable subtasks for swarm execution.
+ */
+import { z } from "zod";
+
+/**
+ * Effort estimation levels
+ */
+export const EffortLevelSchema = z.enum([
+  "trivial", // < 5 min
+  "small", // 5-30 min
+  "medium", // 30 min - 2 hours
+  "large", // 2+ hours
+]);
+export type EffortLevel = z.infer<typeof EffortLevelSchema>;
+
+/**
+ * Dependency type between subtasks
+ */
+export const DependencyTypeSchema = z.enum([
+  "blocks", // Must complete before dependent can start
+  "requires", // Needs output from another task
+  "related", // Informational relationship
+]);
+export type DependencyType = z.infer<typeof DependencyTypeSchema>;
+
+/**
+ * Subtask in a decomposition
+ */
+export const DecomposedSubtaskSchema = z.object({
+  title: z.string().min(1),
+  description: z.string(),
+  files: z.array(z.string()), // File paths this subtask will modify
+  estimated_effort: EffortLevelSchema,
+  risks: z.array(z.string()).optional().default([]),
+});
+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
+  type: DependencyTypeSchema,
+});
+export type SubtaskDependency = z.infer<typeof SubtaskDependencySchema>;
+
+/**
+ * Full task decomposition result
+ *
+ * Returned by the decomposition agent, validated before spawning.
+ */
+export const TaskDecompositionSchema = z.object({
+  task: z.string(), // Original task description
+  reasoning: z.string().optional(), // Why this decomposition
+  subtasks: z.array(DecomposedSubtaskSchema).min(1).max(10),
+  dependencies: z.array(SubtaskDependencySchema).optional().default([]),
+  shared_context: z.string().optional(), // Context to pass to all agents
+});
+export type TaskDecomposition = z.infer<typeof TaskDecompositionSchema>;
+
+/**
+ * Arguments for task decomposition
+ */
+export const DecomposeArgsSchema = z.object({
+  task: z.string().min(1),
+  max_subtasks: z.number().int().min(1).max(10).default(5),
+  context: z.string().optional(),
+});
+export type DecomposeArgs = z.infer<typeof DecomposeArgsSchema>;
+
+/**
+ * Spawn result for a single agent
+ */
+export const SpawnedAgentSchema = z.object({
+  bead_id: z.string(),
+  agent_name: z.string(), // Agent Mail name (e.g., "BlueLake")
+  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
+});
+export type SpawnedAgent = z.infer<typeof SpawnedAgentSchema>;
+
+/**
+ * Result of spawning a swarm
+ */
+export const SwarmSpawnResultSchema = z.object({
+  epic_id: z.string(),
+  coordinator_name: z.string(), // Agent Mail name of coordinator
+  thread_id: z.string(), // Agent Mail thread for this swarm
+  agents: z.array(SpawnedAgentSchema),
+  started_at: z.string(), // ISO-8601
+});
+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(), // ISO-8601
+});
+export type AgentProgress = z.infer<typeof AgentProgressSchema>;
+
+/**
+ * Swarm status summary
+ */
+export const SwarmStatusSchema = z.object({
+  epic_id: z.string(),
+  total_agents: z.number().int().min(0),
+  running: z.number().int().min(0),
+  completed: z.number().int().min(0),
+  failed: z.number().int().min(0),
+  blocked: z.number().int().min(0),
+  agents: z.array(SpawnedAgentSchema),
+  last_update: z.string(), // ISO-8601
+});
+export type SwarmStatus = z.infer<typeof SwarmStatusSchema>;