opencode-swarm-plugin 0.43.0 → 0.44.1

package/src/schemas/cell.ts

@@ -1,257 +0,0 @@
-/**
- * Cell schemas for type-safe cell operations
- *
- * These schemas validate all data from the `bd` CLI to ensure
- * type safety and catch malformed responses early.
- *
- * Cells are work items in the Hive (honeycomb metaphor).
- * Backward compatibility: Bead* aliases provided for gradual migration.
- */
-import { z } from "zod";
-
-/** Valid cell statuses */
-export const CellStatusSchema = z.enum([
-  "open",
-  "in_progress",
-  "blocked",
-  "closed",
-]);
-export type CellStatus = z.infer<typeof CellStatusSchema>;
-
-/** Valid cell types */
-export const CellTypeSchema = z.enum([
-  "bug",
-  "feature",
-  "task",
-  "epic",
-  "chore",
-]);
-export type CellType = z.infer<typeof CellTypeSchema>;
-
-/** Dependency relationship between cells */
-export const CellDependencySchema = z.object({
-  id: z.string(),
-  type: z.enum(["blocks", "blocked-by", "related", "discovered-from"]),
-});
-export type CellDependency = z.infer<typeof CellDependencySchema>;
-
-/**
- * Core cell 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`)
- * - Custom: `{project}-{custom-id}` (e.g., `migrate-egghead-phase-0`)
- * - Custom subtask: `{project}-{custom-id}.{suffix}` (e.g., `migrate-egghead-phase-0.e2e-test`)
- */
-export const CellSchema = z.object({
-  /**
-   * Cell ID format: project-slug-hash with optional subtask index.
-   *
-   * Pattern: `project-name-xxxxx` or `project-name-xxxxx.N`
-   * Examples:
-   * - `my-project-abc12` (main cell)
-   * - `my-project-abc12.1` (first subtask)
-   * - `my-project-abc12.2` (second subtask)
-   */
-  id: z
-    .string()
-    .regex(
-      /^[a-z0-9]+(-[a-z0-9]+)+(\.[\w-]+)?$/,
-      "Invalid cell ID format (expected: project-slug-hash or project-slug-hash.N)",
-    ),
-  title: z.string().min(1, "Title required"),
-  description: z.string().optional().default(""),
-  status: CellStatusSchema.default("open"),
-  priority: z.number().int().min(0).max(3).default(2),
-  issue_type: CellTypeSchema.default("task"),
-  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(CellDependencySchema).default([]),
-  metadata: z.record(z.string(), z.unknown()).optional(),
-});
-export type Cell = z.infer<typeof CellSchema>;
-
-/** Arguments for creating a cell */
-export const CellCreateArgsSchema = z.object({
-  title: z.string().min(1, "Title required"),
-  type: CellTypeSchema.default("task"),
-  priority: z.number().int().min(0).max(3).default(2),
-  description: z.string().optional(),
-  parent_id: z.string().optional(),
-  /**
-   * Custom ID for human-readable cell names.
-   * MUST include project prefix (e.g., 'migrate-egghead-phase-0', not just 'phase-0').
-   * For subtasks, use dot notation: 'migrate-egghead-phase-0.e2e-test'
-   */
-  id: z.string().optional(),
-});
-export type CellCreateArgs = z.infer<typeof CellCreateArgsSchema>;
-
-/** Arguments for updating a cell */
-export const CellUpdateArgsSchema = z.object({
-  id: z.string(),
-  status: CellStatusSchema.optional(),
-  description: z.string().optional(),
-  priority: z.number().int().min(0).max(3).optional(),
-});
-export type CellUpdateArgs = z.infer<typeof CellUpdateArgsSchema>;
-
-/** Arguments for closing a cell */
-export const CellCloseArgsSchema = z.object({
-  id: z.string(),
-  reason: z.string().min(1, "Reason required"),
-});
-export type CellCloseArgs = z.infer<typeof CellCloseArgsSchema>;
-
-/** Arguments for querying cells */
-export const CellQueryArgsSchema = z.object({
-  status: CellStatusSchema.optional(),
-  type: CellTypeSchema.optional(),
-  ready: z.boolean().optional(),
-  parent_id: z.string().optional(),
-  limit: z.number().int().positive().default(20),
-});
-export type CellQueryArgs = z.infer<typeof CellQueryArgsSchema>;
-
-/**
- * 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
-  /**
-   * 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>;
-
-/**
- * Cell tree for swarm decomposition
- *
- * Represents an epic with its subtasks, ready for spawning agents.
- */
-export const CellTreeSchema = z.object({
-  epic: z.object({
-    title: z.string().min(1),
-    description: z.string().optional().default(""),
-  }),
-  subtasks: z.array(SubtaskSpecSchema).min(1),
-});
-export type CellTree = z.infer<typeof CellTreeSchema>;
-
-/** Arguments for creating an epic with subtasks */
-export const EpicCreateArgsSchema = z.object({
-  epic_title: z.string().min(1),
-  epic_description: z.string().optional(),
-  /**
-   * Custom ID for the epic. MUST include project prefix.
-   * Example: 'migrate-egghead-phase-0' (not just 'phase-0')
-   * If not provided, bd generates a random ID.
-   */
-  epic_id: 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([]),
-        /**
-         * Custom ID suffix for subtask. Combined with epic_id using dot notation.
-         * Example: epic_id='migrate-egghead-phase-0', id_suffix='e2e-test'
-         *          → subtask ID: 'migrate-egghead-phase-0.e2e-test'
-         */
-        id_suffix: z.string().optional(),
-      }),
-    )
-    .min(1),
-});
-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: CellSchema,
-  subtasks: z.array(CellSchema),
-  rollback_hint: z.string().optional(),
-});
-export type EpicCreateResult = z.infer<typeof EpicCreateResultSchema>;
-
-// ============================================================================
-// BACKWARD COMPATIBILITY ALIASES
-// These aliases maintain compatibility with existing code using Bead* names.
-// Gradually migrate to Cell* names in new code.
-// ============================================================================
-
-/** @deprecated Use CellStatusSchema instead */
-export const BeadStatusSchema = CellStatusSchema;
-/** @deprecated Use CellStatus instead */
-export type BeadStatus = CellStatus;
-
-/** @deprecated Use CellTypeSchema instead */
-export const BeadTypeSchema = CellTypeSchema;
-/** @deprecated Use CellType instead */
-export type BeadType = CellType;
-
-/** @deprecated Use CellDependencySchema instead */
-export const BeadDependencySchema = CellDependencySchema;
-/** @deprecated Use CellDependency instead */
-export type BeadDependency = CellDependency;
-
-/** @deprecated Use CellSchema instead */
-export const BeadSchema = CellSchema;
-/** @deprecated Use Cell instead */
-export type Bead = Cell;
-
-/** @deprecated Use CellCreateArgsSchema instead */
-export const BeadCreateArgsSchema = CellCreateArgsSchema;
-/** @deprecated Use CellCreateArgs instead */
-export type BeadCreateArgs = CellCreateArgs;
-
-/** @deprecated Use CellUpdateArgsSchema instead */
-export const BeadUpdateArgsSchema = CellUpdateArgsSchema;
-/** @deprecated Use CellUpdateArgs instead */
-export type BeadUpdateArgs = CellUpdateArgs;
-
-/** @deprecated Use CellCloseArgsSchema instead */
-export const BeadCloseArgsSchema = CellCloseArgsSchema;
-/** @deprecated Use CellCloseArgs instead */
-export type BeadCloseArgs = CellCloseArgs;
-
-/** @deprecated Use CellQueryArgsSchema instead */
-export const BeadQueryArgsSchema = CellQueryArgsSchema;
-/** @deprecated Use CellQueryArgs instead */
-export type BeadQueryArgs = CellQueryArgs;
-
-/** @deprecated Use CellTreeSchema instead */
-export const BeadTreeSchema = CellTreeSchema;
-/** @deprecated Use CellTree instead */
-export type BeadTree = CellTree;

package/src/schemas/evaluation.ts

@@ -1,166 +0,0 @@
-/**
- * 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";
-
-/**
- * Evaluation of a single criterion.
- *
- * @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(),
-  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 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(),
-    /** 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().datetime({ offset: true }).optional(), // ISO-8601 with timezone
-});
-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({
-  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>;
-
-/**
- * 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().datetime({ offset: true }).optional(), // ISO-8601 with timezone
-  /** 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()), // Cell 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>;
-
-/**
- * Failure mode taxonomy for task failures
- *
- * Classifies WHY tasks fail, not just that they failed.
- * Used in outcome tracking to learn from failure patterns.
- *
- * @see src/learning.ts OutcomeSignalsSchema
- * @see "Patterns for Building AI Agents" p.46
- */
-export const FailureModeSchema = z.enum([
-  "timeout", // Task exceeded time limit
-  "conflict", // File reservation conflict
-  "validation", // Output failed schema validation
-  "tool_failure", // Tool call returned error
-  "context_overflow", // Ran out of context window
-  "dependency_blocked", // Waiting on another subtask
-  "user_cancelled", // User interrupted
-  "unknown", // Unclassified
-]);
-export type FailureMode = z.infer<typeof FailureModeSchema>;

package/src/schemas/index.test.ts

@@ -1,199 +0,0 @@
-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();
-  });
-});