opencode-swarm-plugin 0.43.0 → 0.44.1

package/src/schemas/task.ts

@@ -1,161 +0,0 @@
-/**
- * Task decomposition schemas
- *
- * These schemas define the structure for breaking down tasks
- * into parallelizable subtasks for swarm execution.
- */
-import { z } from "zod";
-
-/**
- * Effort estimation for subtasks.
- *
- * Time ranges:
- * - `trivial`: < 5 minutes (simple rename, typo fix)
- * - `small`: 5-30 minutes (single function, simple feature)
- * - `medium`: 30 min - 2 hours (multi-file change, moderate complexity)
- * - `large`: 2+ hours (significant feature, refactoring)
- */
-export const EffortLevelSchema = z.enum([
-  "trivial",
-  "small",
-  "medium",
-  "large",
-]);
-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,
-  /** Potential risks or complications (e.g., 'tight coupling', 'data migration required', 'breaking change') */
-  risks: z.array(z.string()).optional().default([]),
-  /** 
-   * Optional explicit model override for this subtask.
-   * If not specified, model will be selected based on file types.
-   */
-  model: z.string().optional(),
-});
-export type DecomposedSubtask = z.infer<typeof DecomposedSubtaskSchema>;
-
-/**
- * Dependency between subtasks
- */
-export const SubtaskDependencySchema = z.object({
-  /** Zero-based index of the dependency source subtask */
-  from: z.number().int().min(0),
-  /** Zero-based index of the dependency target subtask */
-  to: z.number().int().min(0),
-  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
-  /** Rationale for this decomposition strategy (why these subtasks, why this order) */
-  reasoning: z.string().optional(),
-  subtasks: z.array(DecomposedSubtaskSchema).min(1),
-  dependencies: z.array(SubtaskDependencySchema).optional().default([]),
-  /**
-   * Context shared with all spawned agents.
-   * Examples: API contracts, shared types, project conventions, architectural decisions.
-   */
-  shared_context: z.string().optional(),
-});
-export type TaskDecomposition = z.infer<typeof TaskDecompositionSchema>;
-
-/**
- * Arguments for task decomposition
- */
-export const DecomposeArgsSchema = z.object({
-  task: z.string().min(1),
-  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 Mail assigned name (e.g., 'BlueLake', 'CrimsonRiver').
-   * Generated by Agent Mail on session init.
-   */
-  agent_name: z.string(),
-  task_id: z.string().optional(), // OpenCode task ID
-  status: z.enum(["pending", "running", "completed", "failed"]),
-  files: z.array(z.string()), // Reserved files
-  /**
-   * Agent Mail reservation IDs for file locking.
-   * Used to release locks on task completion via agentmail_release.
-   */
-  reservation_ids: z.array(z.number()).optional(),
-});
-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().datetime({ offset: true }), // ISO-8601 with timezone
-});
-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().datetime({ offset: true }), // ISO-8601 with timezone
-  })
-  .refine(
-    (data) =>
-      data.status !== "blocked" || (data.blockers && data.blockers.length > 0),
-    { message: "blockers array required when status is 'blocked'" },
-  );
-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().datetime({ offset: true }), // ISO-8601 with timezone
-});
-export type SwarmStatus = z.infer<typeof SwarmStatusSchema>;

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

@@ -1,302 +0,0 @@
-/**
- * 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("empty task_id fails", () => {
-    const invalidContract = {
-      task_id: "", // Empty string not allowed
-      files_owned: ["src/auth.ts"],
-      files_readonly: [],
-      dependencies_completed: [],
-      success_criteria: ["Auth works"],
-    };
-
-    const result = WorkerHandoffContractSchema.safeParse(invalidContract);
-    expect(result.success).toBe(false);
-    if (!result.success) {
-      expect(result.error.issues[0].message).toContain("cannot be empty");
-    }
-  });
-
-  test("short project name with hash is valid", () => {
-    // Regression test: single-word project names like "swarm-lf2p4u-abc123" should work
-    const shortProjectContract = {
-      task_id: "swarm-lf2p4u-abc123", // Only 2 segments before timestamp
-      files_owned: ["src/auth.ts"],
-      files_readonly: [],
-      dependencies_completed: [],
-      success_criteria: ["Auth works"],
-    };
-
-    const result = WorkerHandoffContractSchema.safeParse(shortProjectContract);
-    expect(result.success).toBe(true);
-  });
-
-  test("partial hash is valid (resolvePartialId will expand it)", () => {
-    // Partial hashes should be accepted - resolvePartialId will expand them
-    const partialHashContract = {
-      task_id: "mjd4pjuj", // Short hash only
-      files_owned: ["src/auth.ts"],
-      files_readonly: [],
-      dependencies_completed: [],
-      success_criteria: ["Auth works"],
-    };
-
-    const result = WorkerHandoffContractSchema.safeParse(partialHashContract);
-    expect(result.success).toBe(true);
-  });
-});
-
-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

@@ -1,131 +0,0 @@
-/**
- * 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.
-   * Can be a full cell ID, hash, or partial hash.
-   * Examples: 
-   * - Full ID: `opencode-swarm-monorepo-lf2p4u-abc123`
-   * - Hash only: `lf2p4u`
-   * - Partial hash: `mjd4pjuj`
-   *
-   * The hive tools use resolvePartialId() to expand short IDs before lookup.
-   */
-  task_id: z
-    .string()
-    .min(1, "Task ID cannot be empty"),
-
-  /**
-   * 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>;