opencode-swarm-plugin 0.30.0 → 0.30.3

package/src/schemas/worker-handoff.test.ts

@@ -0,0 +1,271 @@
+/**
+ * Tests for WorkerHandoff schema validation
+ *
+ * WorkerHandoff replaces prose instructions with structured contracts.
+ * These tests ensure runtime validation catches malformed handoffs.
+ */
+import { describe, expect, test } from "bun:test";
+import {
+  WorkerHandoffContractSchema,
+  WorkerHandoffContextSchema,
+  WorkerHandoffEscalationSchema,
+  WorkerHandoffSchema,
+  type WorkerHandoff,
+  type WorkerHandoffContract,
+  type WorkerHandoffContext,
+  type WorkerHandoffEscalation,
+} from "./worker-handoff";
+
+describe("WorkerHandoffContractSchema", () => {
+  test("valid contract parses correctly", () => {
+    const validContract = {
+      task_id: "opencode-swarm-monorepo-lf2p4u-abc123",
+      files_owned: ["src/auth/service.ts", "src/auth/schema.ts"],
+      files_readonly: ["src/lib/jwt.ts"],
+      dependencies_completed: ["opencode-swarm-monorepo-lf2p4u-abc122"],
+      success_criteria: [
+        "Auth service implements JWT strategy",
+        "All tests pass",
+      ],
+    };
+
+    const result = WorkerHandoffContractSchema.safeParse(validContract);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.task_id).toBe("opencode-swarm-monorepo-lf2p4u-abc123");
+      expect(result.data.files_owned).toHaveLength(2);
+      expect(result.data.success_criteria).toHaveLength(2);
+    }
+  });
+
+  test("missing task_id fails", () => {
+    const invalidContract = {
+      files_owned: ["src/auth.ts"],
+      files_readonly: [],
+      dependencies_completed: [],
+      success_criteria: ["Auth works"],
+    };
+
+    const result = WorkerHandoffContractSchema.safeParse(invalidContract);
+    expect(result.success).toBe(false);
+  });
+
+  test("empty files_owned is valid (read-only tasks)", () => {
+    const readOnlyContract = {
+      task_id: "opencode-swarm-monorepo-lf2p4u-abc123",
+      files_owned: [], // Read-only task
+      files_readonly: ["src/types.ts"],
+      dependencies_completed: [],
+      success_criteria: ["Documentation updated"],
+    };
+
+    const result = WorkerHandoffContractSchema.safeParse(readOnlyContract);
+    expect(result.success).toBe(true);
+  });
+
+  test("empty success_criteria fails", () => {
+    const invalidContract = {
+      task_id: "opencode-swarm-monorepo-lf2p4u-abc123",
+      files_owned: ["src/auth.ts"],
+      files_readonly: [],
+      dependencies_completed: [],
+      success_criteria: [], // Must have at least one
+    };
+
+    const result = WorkerHandoffContractSchema.safeParse(invalidContract);
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error.issues[0].message).toContain(
+        "at least one success criterion",
+      );
+    }
+  });
+
+  test("invalid task_id format fails", () => {
+    const invalidContract = {
+      task_id: "invalid-format", // Missing hash component
+      files_owned: ["src/auth.ts"],
+      files_readonly: [],
+      dependencies_completed: [],
+      success_criteria: ["Auth works"],
+    };
+
+    const result = WorkerHandoffContractSchema.safeParse(invalidContract);
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("WorkerHandoffContextSchema", () => {
+  test("valid context parses correctly", () => {
+    const validContext = {
+      epic_summary: "Add authentication system",
+      your_role: "Implement JWT auth service",
+      what_others_did: "Schema defined by agent-1",
+      what_comes_next: "Integration tests in next subtask",
+    };
+
+    const result = WorkerHandoffContextSchema.safeParse(validContext);
+    expect(result.success).toBe(true);
+  });
+
+  test("missing required fields fails", () => {
+    const invalidContext = {
+      epic_summary: "Add auth",
+      your_role: "Implement service",
+      // Missing what_others_did and what_comes_next
+    };
+
+    const result = WorkerHandoffContextSchema.safeParse(invalidContext);
+    expect(result.success).toBe(false);
+  });
+
+  test("empty strings are valid", () => {
+    const contextWithEmptyStrings = {
+      epic_summary: "Add auth",
+      your_role: "Implement service",
+      what_others_did: "", // Valid for first subtask
+      what_comes_next: "", // Valid for last subtask
+    };
+
+    const result = WorkerHandoffContextSchema.safeParse(
+      contextWithEmptyStrings,
+    );
+    expect(result.success).toBe(true);
+  });
+});
+
+describe("WorkerHandoffEscalationSchema", () => {
+  test("valid escalation parses correctly", () => {
+    const validEscalation = {
+      blocked_contact: "Message coordinator via swarmmail_send(importance='high')",
+      scope_change_protocol:
+        "Request approval before expanding scope beyond files_owned",
+    };
+
+    const result = WorkerHandoffEscalationSchema.safeParse(validEscalation);
+    expect(result.success).toBe(true);
+  });
+
+  test("missing required fields fails", () => {
+    const invalidEscalation = {
+      blocked_contact: "Message coordinator",
+      // Missing scope_change_protocol
+    };
+
+    const result = WorkerHandoffEscalationSchema.safeParse(invalidEscalation);
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("WorkerHandoffSchema", () => {
+  test("complete valid handoff parses correctly", () => {
+    const validHandoff = {
+      contract: {
+        task_id: "opencode-swarm-monorepo-lf2p4u-abc123",
+        files_owned: ["src/auth/service.ts"],
+        files_readonly: ["src/lib/jwt.ts"],
+        dependencies_completed: [],
+        success_criteria: ["Service implemented", "Tests pass"],
+      },
+      context: {
+        epic_summary: "Add authentication",
+        your_role: "Implement auth service",
+        what_others_did: "Schema defined",
+        what_comes_next: "Integration tests",
+      },
+      escalation: {
+        blocked_contact: "Message coordinator",
+        scope_change_protocol: "Request approval first",
+      },
+    };
+
+    const result = WorkerHandoffSchema.safeParse(validHandoff);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      const handoff: WorkerHandoff = result.data;
+      expect(handoff.contract.task_id).toBe(
+        "opencode-swarm-monorepo-lf2p4u-abc123",
+      );
+      expect(handoff.context.your_role).toBe("Implement auth service");
+      expect(handoff.escalation.blocked_contact).toBe("Message coordinator");
+    }
+  });
+
+  test("missing contract section fails", () => {
+    const invalidHandoff = {
+      context: {
+        epic_summary: "Add auth",
+        your_role: "Implement",
+        what_others_did: "Schema",
+        what_comes_next: "Tests",
+      },
+      escalation: {
+        blocked_contact: "Message coordinator",
+        scope_change_protocol: "Request approval",
+      },
+    };
+
+    const result = WorkerHandoffSchema.safeParse(invalidHandoff);
+    expect(result.success).toBe(false);
+  });
+
+  test("nested validation catches contract errors", () => {
+    const handoffWithInvalidContract = {
+      contract: {
+        task_id: "opencode-swarm-monorepo-lf2p4u-abc123",
+        files_owned: ["src/auth.ts"],
+        files_readonly: [],
+        dependencies_completed: [],
+        success_criteria: [], // Invalid: empty
+      },
+      context: {
+        epic_summary: "Add auth",
+        your_role: "Implement",
+        what_others_did: "Schema",
+        what_comes_next: "Tests",
+      },
+      escalation: {
+        blocked_contact: "Message coordinator",
+        scope_change_protocol: "Request approval",
+      },
+    };
+
+    const result = WorkerHandoffSchema.safeParse(handoffWithInvalidContract);
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      const errorMessage = result.error.issues[0].message;
+      expect(errorMessage).toContain("at least one success criterion");
+    }
+  });
+
+  test("type inference works correctly", () => {
+    const handoff: WorkerHandoff = {
+      contract: {
+        task_id: "opencode-swarm-monorepo-lf2p4u-abc123",
+        files_owned: [],
+        files_readonly: [],
+        dependencies_completed: [],
+        success_criteria: ["Done"],
+      },
+      context: {
+        epic_summary: "Summary",
+        your_role: "Role",
+        what_others_did: "Nothing",
+        what_comes_next: "More work",
+      },
+      escalation: {
+        blocked_contact: "Coordinator",
+        scope_change_protocol: "Ask first",
+      },
+    };
+
+    // Type check only - verify TypeScript inference
+    const contract: WorkerHandoffContract = handoff.contract;
+    const context: WorkerHandoffContext = handoff.context;
+    const escalation: WorkerHandoffEscalation = handoff.escalation;
+
+    expect(contract.task_id).toBeDefined();
+    expect(context.your_role).toBeDefined();
+    expect(escalation.blocked_contact).toBeDefined();
+  });
+});

package/src/schemas/worker-handoff.ts

@@ -0,0 +1,131 @@
+/**
+ * WorkerHandoff schemas - structured contracts replacing prose instructions
+ *
+ * Replaces the 400-line SUBTASK_PROMPT_V2 with machine-readable contracts.
+ * Workers receive typed handoffs with explicit files, criteria, and escalation paths.
+ */
+import { z } from "zod";
+
+/**
+ * Contract section - the binding agreement between coordinator and worker
+ *
+ * Defines:
+ * - What task to complete (task_id)
+ * - What files to modify (files_owned) vs read (files_readonly)
+ * - What's already done (dependencies_completed)
+ * - How to know you're done (success_criteria)
+ */
+export const WorkerHandoffContractSchema = z.object({
+  /**
+   * Cell ID for this subtask.
+   * Format: `{project}-{hash}` or `{project}-{hash}.{index}`
+   * Example: `opencode-swarm-monorepo-lf2p4u-abc123`
+   *
+   * Requires at least 3 segments (project can be multi-word, must have hash).
+   */
+  task_id: z
+    .string()
+    .regex(
+      /^[a-z0-9]+(-[a-z0-9]+){2,}(\.[\w-]+)?$/,
+      "Invalid task ID format (expected: project-slug-hash with minimum 3 segments)",
+    ),
+
+  /**
+   * Files this worker owns (exclusive write access).
+   * Empty array is valid for read-only tasks (e.g., documentation review).
+   */
+  files_owned: z.array(z.string()).default([]),
+
+  /**
+   * Files this worker can read but must not modify.
+   * Coordinator reserves these for other workers.
+   */
+  files_readonly: z.array(z.string()).default([]),
+
+  /**
+   * Subtask IDs that must complete before this one.
+   * Empty if no dependencies (can start immediately).
+   */
+  dependencies_completed: z.array(z.string()).default([]),
+
+  /**
+   * Success criteria - how to know the task is complete.
+   * Must have at least one criterion to prevent ambiguous completion.
+   */
+  success_criteria: z
+    .array(z.string())
+    .min(1, "Must have at least one success criterion"),
+});
+export type WorkerHandoffContract = z.infer<typeof WorkerHandoffContractSchema>;
+
+/**
+ * Context section - the narrative explaining the "why"
+ *
+ * Provides:
+ * - Big picture (epic_summary)
+ * - This worker's specific role
+ * - What's already been done
+ * - What comes after
+ */
+export const WorkerHandoffContextSchema = z.object({
+  /**
+   * High-level summary of the entire epic.
+   * Helps worker understand how their piece fits.
+   */
+  epic_summary: z.string(),
+
+  /**
+   * This worker's specific role/responsibility.
+   * Should align with files_owned in contract.
+   */
+  your_role: z.string(),
+
+  /**
+   * What previous subtasks accomplished.
+   * Empty string is valid for first subtask.
+   */
+  what_others_did: z.string(),
+
+  /**
+   * What happens after this subtask completes.
+   * Empty string is valid for last subtask.
+   */
+  what_comes_next: z.string(),
+});
+export type WorkerHandoffContext = z.infer<typeof WorkerHandoffContextSchema>;
+
+/**
+ * Escalation section - what to do when things go wrong
+ *
+ * Defines:
+ * - How to report blockers
+ * - Protocol for scope changes
+ */
+export const WorkerHandoffEscalationSchema = z.object({
+  /**
+   * Instructions for reporting blockers.
+   * Typically: "Message coordinator via swarmmail_send(importance='high')"
+   */
+  blocked_contact: z.string(),
+
+  /**
+   * Protocol for requesting scope changes.
+   * Typically: "Request approval before expanding scope beyond files_owned"
+   */
+  scope_change_protocol: z.string(),
+});
+export type WorkerHandoffEscalation = z.infer<
+  typeof WorkerHandoffEscalationSchema
+>;
+
+/**
+ * Complete WorkerHandoff - combines all three sections
+ *
+ * This is the full structured contract that replaces prose instructions.
+ */
+export const WorkerHandoffSchema = z.object({
+  contract: WorkerHandoffContractSchema,
+  context: WorkerHandoffContextSchema,
+  escalation: WorkerHandoffEscalationSchema,
+});
+export type WorkerHandoff = z.infer<typeof WorkerHandoffSchema>;