opencode-swarm-plugin 0.26.1 → 0.27.0

package/src/schemas/{bead.ts → cell.ts}

@@ -1,39 +1,42 @@
 /**
- * Bead schemas for type-safe beads operations
+ * 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 bead statuses */
-export const BeadStatusSchema = z.enum([
+/** Valid cell statuses */
+export const CellStatusSchema = z.enum([
   "open",
   "in_progress",
   "blocked",
   "closed",
 ]);
-export type BeadStatus = z.infer<typeof BeadStatusSchema>;
+export type CellStatus = z.infer<typeof CellStatusSchema>;
 
-/** Valid bead types */
-export const BeadTypeSchema = z.enum([
+/** Valid cell types */
+export const CellTypeSchema = z.enum([
   "bug",
   "feature",
   "task",
   "epic",
   "chore",
 ]);
-export type BeadType = z.infer<typeof BeadTypeSchema>;
+export type CellType = z.infer<typeof CellTypeSchema>;
 
-/** Dependency relationship between beads */
-export const BeadDependencySchema = z.object({
+/** Dependency relationship between cells */
+export const CellDependencySchema = z.object({
   id: z.string(),
   type: z.enum(["blocks", "blocked-by", "related", "discovered-from"]),
 });
-export type BeadDependency = z.infer<typeof BeadDependencySchema>;
+export type CellDependency = z.infer<typeof CellDependencySchema>;
 
 /**
- * Core bead schema - validates bd CLI JSON output
+ * Core cell schema - validates bd CLI JSON output
  *
  * ID format:
  * - Standard: `{project}-{hash}` (e.g., `opencode-swarm-plugin-1i8`)
@@ -41,13 +44,13 @@ export type BeadDependency = z.infer<typeof BeadDependencySchema>;
  * - 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 BeadSchema = z.object({
+export const CellSchema = z.object({
   /**
-   * Bead ID format: project-slug-hash with optional subtask index.
+   * Cell 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` (main cell)
    * - `my-project-abc12.1` (first subtask)
    * - `my-project-abc12.2` (second subtask)
    */
@@ -55,13 +58,13 @@ export const BeadSchema = z.object({
     .string()
     .regex(
       /^[a-z0-9]+(-[a-z0-9]+)+(\.[\w-]+)?$/,
-      "Invalid bead ID format (expected: project-slug-hash or project-slug-hash.N)",
+      "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: BeadStatusSchema.default("open"),
+  status: CellStatusSchema.default("open"),
   priority: z.number().int().min(0).max(3).default(2),
-  issue_type: BeadTypeSchema.default("task"),
+  issue_type: CellTypeSchema.default("task"),
   created_at: z.string().datetime({
     offset: true,
     message:
@@ -77,51 +80,51 @@ export const BeadSchema = z.object({
     .optional(),
   closed_at: z.string().datetime({ offset: true }).optional(),
   parent_id: z.string().optional(),
-  dependencies: z.array(BeadDependencySchema).default([]),
+  dependencies: z.array(CellDependencySchema).default([]),
   metadata: z.record(z.string(), z.unknown()).optional(),
 });
-export type Bead = z.infer<typeof BeadSchema>;
+export type Cell = z.infer<typeof CellSchema>;
 
-/** Arguments for creating a bead */
-export const BeadCreateArgsSchema = z.object({
+/** Arguments for creating a cell */
+export const CellCreateArgsSchema = z.object({
   title: z.string().min(1, "Title required"),
-  type: BeadTypeSchema.default("task"),
+  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 bead names.
+   * 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 BeadCreateArgs = z.infer<typeof BeadCreateArgsSchema>;
+export type CellCreateArgs = z.infer<typeof CellCreateArgsSchema>;
 
-/** Arguments for updating a bead */
-export const BeadUpdateArgsSchema = z.object({
+/** Arguments for updating a cell */
+export const CellUpdateArgsSchema = z.object({
   id: z.string(),
-  status: BeadStatusSchema.optional(),
+  status: CellStatusSchema.optional(),
   description: z.string().optional(),
   priority: z.number().int().min(0).max(3).optional(),
 });
-export type BeadUpdateArgs = z.infer<typeof BeadUpdateArgsSchema>;
+export type CellUpdateArgs = z.infer<typeof CellUpdateArgsSchema>;
 
-/** Arguments for closing a bead */
-export const BeadCloseArgsSchema = z.object({
+/** Arguments for closing a cell */
+export const CellCloseArgsSchema = z.object({
   id: z.string(),
   reason: z.string().min(1, "Reason required"),
 });
-export type BeadCloseArgs = z.infer<typeof BeadCloseArgsSchema>;
+export type CellCloseArgs = z.infer<typeof CellCloseArgsSchema>;
 
-/** Arguments for querying beads */
-export const BeadQueryArgsSchema = z.object({
-  status: BeadStatusSchema.optional(),
-  type: BeadTypeSchema.optional(),
+/** Arguments for querying cells */
+export const CellQueryArgsSchema = z.object({
+  status: CellStatusSchema.optional(),
+  type: CellTypeSchema.optional(),
   ready: z.boolean().optional(),
   limit: z.number().int().positive().default(20),
 });
-export type BeadQueryArgs = z.infer<typeof BeadQueryArgsSchema>;
+export type CellQueryArgs = z.infer<typeof CellQueryArgsSchema>;
 
 /**
  * Subtask specification for epic decomposition
@@ -147,18 +150,18 @@ export const SubtaskSpecSchema = z.object({
 export type SubtaskSpec = z.infer<typeof SubtaskSpecSchema>;
 
 /**
- * Bead tree for swarm decomposition
+ * Cell tree for swarm decomposition
  *
  * Represents an epic with its subtasks, ready for spawning agents.
  */
-export const BeadTreeSchema = z.object({
+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 BeadTree = z.infer<typeof BeadTreeSchema>;
+export type CellTree = z.infer<typeof CellTreeSchema>;
 
 /** Arguments for creating an epic with subtasks */
 export const EpicCreateArgsSchema = z.object({
@@ -195,8 +198,59 @@ export type EpicCreateArgs = z.infer<typeof EpicCreateArgsSchema>;
  */
 export const EpicCreateResultSchema = z.object({
   success: z.boolean(),
-  epic: BeadSchema,
-  subtasks: z.array(BeadSchema),
+  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

@@ -128,7 +128,7 @@ export const SwarmEvaluationResultSchema = z.object({
     }),
   ),
   overall_passed: z.boolean(),
-  retry_needed: z.array(z.string()), // Bead IDs that need retry
+  retry_needed: z.array(z.string()), // Cell IDs that need retry
 });
 export type SwarmEvaluationResult = z.infer<typeof SwarmEvaluationResultSchema>;
 

package/src/schemas/index.ts

@@ -4,16 +4,18 @@
  * 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)
+ * ## Cell Schemas (Issue Tracking) - PRIMARY
+ * - `CellSchema` - Core cell/issue definition (formerly BeadSchema)
+ * - `CellStatusSchema` - Status enum (open, in_progress, blocked, closed)
+ * - `CellTypeSchema` - Type enum (bug, feature, task, epic, chore)
  * - `SubtaskSpecSchema` - Subtask specification for epic creation
+ * - `CellTreeSchema` - Epic + subtasks structure (formerly CellTreeSchema)
+ *
+ * **Backward compatibility:** All Bead* names are exported as deprecated aliases.
  *
  * ## 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
@@ -27,7 +29,35 @@
  * @module schemas
  */
 
-// Bead schemas
+// Cell schemas (primary names)
+export {
+  CellStatusSchema,
+  CellTypeSchema,
+  CellDependencySchema,
+  CellSchema,
+  CellCreateArgsSchema,
+  CellUpdateArgsSchema,
+  CellCloseArgsSchema,
+  CellQueryArgsSchema,
+  SubtaskSpecSchema,
+  CellTreeSchema,
+  EpicCreateArgsSchema,
+  EpicCreateResultSchema,
+  type CellStatus,
+  type CellType,
+  type CellDependency,
+  type Cell,
+  type CellCreateArgs,
+  type CellUpdateArgs,
+  type CellCloseArgs,
+  type CellQueryArgs,
+  type SubtaskSpec,
+  type CellTree,
+  type EpicCreateArgs,
+  type EpicCreateResult,
+} from "./cell";
+
+// Bead schemas (backward compatibility aliases)
 export {
   BeadStatusSchema,
   BeadTypeSchema,
@@ -37,10 +67,7 @@ export {
   BeadUpdateArgsSchema,
   BeadCloseArgsSchema,
   BeadQueryArgsSchema,
-  SubtaskSpecSchema,
   BeadTreeSchema,
-  EpicCreateArgsSchema,
-  EpicCreateResultSchema,
   type BeadStatus,
   type BeadType,
   type BeadDependency,
@@ -49,11 +76,8 @@ export {
   type BeadUpdateArgs,
   type BeadCloseArgs,
   type BeadQueryArgs,
-  type SubtaskSpec,
   type BeadTree,
-  type EpicCreateArgs,
-  type EpicCreateResult,
-} from "./bead";
+} from "./cell";
 
 // Evaluation schemas
 export {
@@ -144,7 +168,58 @@ export {
   type QuerySwarmContextsArgs,
 } from "./swarm-context";
 
-// Bead event schemas
+// Cell event schemas (PRIMARY)
+export {
+  BaseCellEventSchema,
+  CellCreatedEventSchema,
+  CellUpdatedEventSchema,
+  CellStatusChangedEventSchema,
+  CellClosedEventSchema,
+  CellReopenedEventSchema,
+  CellDeletedEventSchema,
+  CellDependencyAddedEventSchema,
+  CellDependencyRemovedEventSchema,
+  CellLabelAddedEventSchema,
+  CellLabelRemovedEventSchema,
+  CellCommentAddedEventSchema,
+  CellCommentUpdatedEventSchema,
+  CellCommentDeletedEventSchema,
+  CellEpicChildAddedEventSchema,
+  CellEpicChildRemovedEventSchema,
+  CellEpicClosureEligibleEventSchema,
+  CellAssignedEventSchema,
+  CellWorkStartedEventSchema,
+  CellCompactedEventSchema,
+  CellEventSchema,
+  createCellEvent,
+  isCellEventType,
+  getCellIdFromEvent,
+  isStateTransitionEvent,
+  isEpicEvent,
+  isAgentEvent,
+  type CellEvent,
+  type CellCreatedEvent,
+  type CellUpdatedEvent,
+  type CellStatusChangedEvent,
+  type CellClosedEvent,
+  type CellReopenedEvent,
+  type CellDeletedEvent,
+  type CellDependencyAddedEvent,
+  type CellDependencyRemovedEvent,
+  type CellLabelAddedEvent,
+  type CellLabelRemovedEvent,
+  type CellCommentAddedEvent,
+  type CellCommentUpdatedEvent,
+  type CellCommentDeletedEvent,
+  type CellEpicChildAddedEvent,
+  type CellEpicChildRemovedEvent,
+  type CellEpicClosureEligibleEvent,
+  type CellAssignedEvent,
+  type CellWorkStartedEvent,
+  type CellCompactedEvent,
+} from "./cell-events";
+
+// Bead event schemas (DEPRECATED - backward compatibility)
 export {
   BaseBeadEventSchema,
   BeadCreatedEventSchema,
@@ -170,9 +245,6 @@ export {
   createBeadEvent,
   isBeadEventType,
   getBeadIdFromEvent,
-  isStateTransitionEvent,
-  isEpicEvent,
-  isAgentEvent,
   type BeadEvent,
   type BeadCreatedEvent,
   type BeadUpdatedEvent,
@@ -193,4 +265,4 @@ export {
   type BeadAssignedEvent,
   type BeadWorkStartedEvent,
   type BeadCompactedEvent,
-} from "./bead-events";
+} from "./cell-events";

package/src/schemas/swarm-context.ts

@@ -56,13 +56,13 @@ export const SwarmBeadContextSchema = z.object({
   id: z.string(),
   /** Epic this bead belongs to */
   epic_id: z.string(),
-  /** Bead ID being executed */
+  /** Cell 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 */
+  /** Cell IDs this task depends on */
   dependencies: z.array(z.string()).default([]),
   /** Shared directives and context */
   directives: SwarmDirectivesSchema,

package/src/structured.test.ts

@@ -7,7 +7,7 @@ import type { ToolContext } from "@opencode-ai/plugin";
 import { describe, expect, it } from "bun:test";
 import { z } from "zod";
 import {
-  BeadTreeSchema,
+  CellTreeSchema,
   EvaluationSchema,
   TaskDecompositionSchema,
 } from "./schemas";
@@ -18,7 +18,7 @@ import {
   formatZodErrors,
   getSchemaByName,
   structured_extract_json,
-  structured_parse_bead_tree,
+  structured_parse_cell_tree,
   structured_parse_decomposition,
   structured_parse_evaluation,
   structured_validate,
@@ -337,9 +337,9 @@ describe("getSchemaByName", () => {
     expect(schema).toBe(TaskDecompositionSchema);
   });
 
-  it("returns BeadTreeSchema for 'bead_tree'", () => {
-    const schema = getSchemaByName("bead_tree");
-    expect(schema).toBe(BeadTreeSchema);
+  it("returns CellTreeSchema for 'cell_tree'", () => {
+    const schema = getSchemaByName("cell_tree");
+    expect(schema).toBe(CellTreeSchema);
   });
 
   it("throws error for unknown schema name", () => {
@@ -353,7 +353,7 @@ describe("getSchemaByName", () => {
       if (error instanceof Error) {
         expect(error.message).toContain("evaluation");
         expect(error.message).toContain("task_decomposition");
-        expect(error.message).toContain("bead_tree");
+        expect(error.message).toContain("cell_tree");
       }
     }
   });
@@ -552,7 +552,7 @@ describe("structured_validate", () => {
     });
   });
 
-  describe("bead_tree schema", () => {
+  describe("cell_tree schema", () => {
     it("validates correct bead tree", async () => {
       const validTree = {
         epic: { title: "Epic", description: "Desc" },
@@ -568,7 +568,7 @@ describe("structured_validate", () => {
       const result = await structured_validate.execute(
         {
           response: JSON.stringify(validTree),
-          schema_name: "bead_tree",
+          schema_name: "cell_tree",
         },
         mockCtx,
       );
@@ -852,10 +852,10 @@ describe("structured_parse_decomposition", () => {
 });
 
 // ============================================================================
-// 9. structured_parse_bead_tree tool
+// 9. structured_parse_cell_tree tool
 // ============================================================================
 
-describe("structured_parse_bead_tree", () => {
+describe("structured_parse_cell_tree", () => {
   const mockCtx = {} as ToolContext;
 
   it("parses valid bead tree", async () => {
@@ -881,7 +881,7 @@ describe("structured_parse_bead_tree", () => {
         },
       ],
     };
-    const result = await structured_parse_bead_tree.execute(
+    const result = await structured_parse_cell_tree.execute(
       { response: JSON.stringify(validTree) },
       mockCtx,
     );
@@ -917,7 +917,7 @@ describe("structured_parse_bead_tree", () => {
         },
       ],
     };
-    const result = await structured_parse_bead_tree.execute(
+    const result = await structured_parse_cell_tree.execute(
       { response: JSON.stringify(tree) },
       mockCtx,
     );
@@ -944,7 +944,7 @@ describe("structured_parse_bead_tree", () => {
         },
       ],
     };
-    const result = await structured_parse_bead_tree.execute(
+    const result = await structured_parse_cell_tree.execute(
       { response: JSON.stringify(tree) },
       mockCtx,
     );
@@ -955,7 +955,7 @@ describe("structured_parse_bead_tree", () => {
   });
 
   it("returns error for invalid bead tree", async () => {
-    const result = await structured_parse_bead_tree.execute(
+    const result = await structured_parse_cell_tree.execute(
       { response: '{"epic": {}}' }, // Missing required fields
       mockCtx,
     );
@@ -966,7 +966,7 @@ describe("structured_parse_bead_tree", () => {
   });
 
   it("includes expected shape in error", async () => {
-    const result = await structured_parse_bead_tree.execute(
+    const result = await structured_parse_cell_tree.execute(
       { response: '{"wrong": true}' },
       mockCtx,
     );

package/src/structured.ts

@@ -9,7 +9,7 @@
  * 2. `structured_validate` - Extract + validate against named schema
  * 3. `structured_parse_evaluation` - Typed parsing for agent self-evaluations
  * 4. `structured_parse_decomposition` - Typed parsing for task breakdowns
- * 5. `structured_parse_bead_tree` - Typed parsing for epic + subtasks
+ * 5. `structured_parse_cell_tree` - Typed parsing for epic + subtasks
  *
  * @module structured
  */
@@ -18,12 +18,12 @@ import { z, type ZodSchema } from "zod";
 import {
   EvaluationSchema,
   TaskDecompositionSchema,
-  BeadTreeSchema,
+  CellTreeSchema,
   ValidationResultSchema,
   CriterionEvaluationSchema,
   type Evaluation,
   type TaskDecomposition,
-  type BeadTree,
+  type CellTree,
   type ValidationResult,
 } from "./schemas";
 
@@ -96,7 +96,7 @@ function formatZodErrors(error: z.ZodError): string[] {
 const SCHEMA_REGISTRY: Record<string, ZodSchema> = {
   evaluation: EvaluationSchema,
   task_decomposition: TaskDecompositionSchema,
-  bead_tree: BeadTreeSchema,
+  cell_tree: CellTreeSchema,
 };
 
 /**
@@ -377,12 +377,12 @@ export const structured_validate = tool({
   args: {
     response: tool.schema.string().describe("Agent response to validate"),
     schema_name: tool.schema
-      .enum(["evaluation", "task_decomposition", "bead_tree"])
+      .enum(["evaluation", "task_decomposition", "cell_tree"])
       .describe(
         "Schema to validate against: " +
           "evaluation = agent self-eval with criteria, " +
           "task_decomposition = swarm task breakdown, " +
-          "bead_tree = epic with subtasks",
+          "cell_tree = epic with subtasks",
       ),
     max_retries: tool.schema
       .number()
@@ -650,11 +650,11 @@ export const structured_parse_decomposition = tool({
 /**
  * Parse and validate a bead tree (epic with subtasks)
  *
- * Validates the structure before creating beads.
+ * Validates the structure before creating cells.
  */
-export const structured_parse_bead_tree = tool({
+export const structured_parse_cell_tree = tool({
   description:
-    "Parse and validate bead tree response. Uses BeadTreeSchema. Validates before creating epic with subtasks.",
+    "Parse and validate bead tree response. Uses CellTreeSchema. Validates before creating epic with subtasks.",
   args: {
     response: tool.schema
       .string()
@@ -663,7 +663,7 @@ export const structured_parse_bead_tree = tool({
   async execute(args, ctx) {
     try {
       const [extracted, method] = extractJsonFromText(args.response);
-      const validated = BeadTreeSchema.parse(extracted) as BeadTree;
+      const validated = CellTreeSchema.parse(extracted) as CellTree;
 
       // Collect all files for reservation planning
       const allFiles = validated.subtasks.flatMap((s) => s.files);
@@ -751,5 +751,12 @@ export const structuredTools = {
   structured_validate: structured_validate,
   structured_parse_evaluation: structured_parse_evaluation,
   structured_parse_decomposition: structured_parse_decomposition,
-  structured_parse_bead_tree: structured_parse_bead_tree,
+  structured_parse_cell_tree: structured_parse_cell_tree,
 };
+
+// ============================================================================
+// Backward Compatibility Aliases
+// ============================================================================
+
+/** @deprecated Use structured_parse_cell_tree instead */
+export const structured_parse_bead_tree = structured_parse_cell_tree;