opencode-swarm-plugin 0.35.0 → 0.36.0

package/src/compaction-hook.ts

@@ -236,29 +236,30 @@ interface ToolPart {
 /**
  * Tool state (completed tools have input/output we need)
  */
-type ToolState = {
-  status: "completed";
-  input: { [key: string]: unknown };
-  output: string;
-  title: string;
-  metadata: { [key: string]: unknown };
-  time: { start: number; end: number };
-} | {
-  status: string;
-  [key: string]: unknown;
-};
+type ToolState =
+  | {
+      status: "completed";
+      input: { [key: string]: unknown };
+      output: string;
+      title: string;
+      metadata: { [key: string]: unknown };
+      time: { start: number; end: number };
+    }
+  | {
+      status: string;
+      [key: string]: unknown;
+    };
 
 /**
  * SDK Client type (minimal interface for scanSessionMessages)
+ * 
+ * The actual SDK client uses a more complex Options-based API:
+ * client.session.messages({ path: { id: sessionID }, query: { limit } })
+ * 
+ * We accept `unknown` and handle the type internally to avoid
+ * tight coupling to SDK internals.
  */
-interface OpencodeClient {
-  session: {
-    messages: (opts: { sessionID: string; limit?: number }) => Promise<{
-      info: { id: string; sessionID: string };
-      parts: ToolPart[];
-    }[]>;
-  };
-}
+export type OpencodeClient = unknown;
 
 /**
  * Scanned swarm state extracted from session messages
@@ -268,29 +269,32 @@ export interface ScannedSwarmState {
   epicTitle?: string;
   projectPath?: string;
   agentName?: string;
-  subtasks: Map<string, { title: string; status: string; worker?: string; files?: string[] }>;
+  subtasks: Map<
+    string,
+    { title: string; status: string; worker?: string; files?: string[] }
+  >;
   lastAction?: { tool: string; args: unknown; timestamp: number };
 }
 
 /**
  * Scan session messages for swarm state using SDK client
- * 
+ *
  * Extracts swarm coordination state from actual tool calls:
  * - swarm_spawn_subtask → subtask tracking
  * - swarmmail_init → agent name, project path
  * - hive_create_epic → epic ID and title
  * - swarm_status → epic reference
  * - swarm_complete → subtask completion
- * 
+ *
  * @param client - OpenCode SDK client (undefined if not available)
  * @param sessionID - Session to scan
  * @param limit - Max messages to fetch (default 100)
  * @returns Extracted swarm state
  */
 export async function scanSessionMessages(
-  client: OpencodeClient | undefined,
+  client: OpencodeClient,
   sessionID: string,
-  limit: number = 100
+  limit: number = 100,
 ): Promise<ScannedSwarmState> {
   const state: ScannedSwarmState = {
     subtasks: new Map(),
@@ -301,7 +305,22 @@ export async function scanSessionMessages(
   }
 
   try {
-    const messages = await client.session.messages({ sessionID, limit });
+    // SDK client uses Options-based API: { path: { id }, query: { limit } }
+    const sdkClient = client as {
+      session: {
+        messages: (opts: {
+          path: { id: string };
+          query?: { limit?: number };
+        }) => Promise<{ data?: Array<{ info: unknown; parts: ToolPart[] }> }>;
+      };
+    };
+
+    const response = await sdkClient.session.messages({
+      path: { id: sessionID },
+      query: { limit },
+    });
+
+    const messages = response.data || [];
 
     for (const message of messages) {
       for (const part of message.parts) {
@@ -310,7 +329,10 @@ export async function scanSessionMessages(
         }
 
         const { tool, state: toolState } = part;
-        const { input, output, time } = toolState as Extract<ToolState, { status: "completed" }>;
+        const { input, output, time } = toolState as Extract<
+          ToolState,
+          { status: "completed" }
+        >;
 
         // Track last action
         state.lastAction = {
@@ -407,12 +429,102 @@ export async function scanSessionMessages(
       }
     }
   } catch (error) {
+    getLog().debug(
+      {
+        error: error instanceof Error ? error.message : String(error),
+      },
+      "SDK message scanning failed",
+    );
     // SDK not available or error fetching messages - return what we have
   }
 
   return state;
 }
 
+/**
+ * Build dynamic swarm state from scanned messages (more precise than hive detection)
+ */
+function buildDynamicSwarmStateFromScanned(
+  scanned: ScannedSwarmState,
+  detected: SwarmState,
+): string {
+  const parts: string[] = [];
+
+  parts.push("## 🐝 Current Swarm State\n");
+
+  // Prefer scanned data over detected
+  const epicId = scanned.epicId || detected.epicId;
+  const epicTitle = scanned.epicTitle || detected.epicTitle;
+  const projectPath = scanned.projectPath || detected.projectPath;
+
+  if (epicId) {
+    parts.push(`**Epic:** ${epicId}${epicTitle ? ` - ${epicTitle}` : ""}`);
+  }
+
+  if (scanned.agentName) {
+    parts.push(`**Coordinator:** ${scanned.agentName}`);
+  }
+
+  parts.push(`**Project:** ${projectPath}`);
+
+  // Show detailed subtask info from scanned state
+  if (scanned.subtasks.size > 0) {
+    parts.push(`\n**Subtasks:**`);
+    for (const [id, subtask] of scanned.subtasks) {
+      const status = subtask.status === "completed" ? "✓" : `[${subtask.status}]`;
+      const worker = subtask.worker ? ` → ${subtask.worker}` : "";
+      const files = subtask.files?.length ? ` (${subtask.files.join(", ")})` : "";
+      parts.push(`  - ${id}: ${subtask.title} ${status}${worker}${files}`);
+    }
+  } else if (detected.subtasks) {
+    // Fall back to counts from hive detection
+    const total =
+      detected.subtasks.closed +
+      detected.subtasks.in_progress +
+      detected.subtasks.open +
+      detected.subtasks.blocked;
+
+    if (total > 0) {
+      parts.push(`**Subtasks:**`);
+      if (detected.subtasks.closed > 0)
+        parts.push(`  - ${detected.subtasks.closed} closed`);
+      if (detected.subtasks.in_progress > 0)
+        parts.push(`  - ${detected.subtasks.in_progress} in_progress`);
+      if (detected.subtasks.open > 0)
+        parts.push(`  - ${detected.subtasks.open} open`);
+      if (detected.subtasks.blocked > 0)
+        parts.push(`  - ${detected.subtasks.blocked} blocked`);
+    }
+  }
+
+  // Show last action if available
+  if (scanned.lastAction) {
+    parts.push(`\n**Last Action:** \`${scanned.lastAction.tool}\``);
+  }
+
+  if (epicId) {
+    parts.push(`\n## 🎯 YOU ARE THE COORDINATOR`);
+    parts.push(``);
+    parts.push(
+      `**Primary role:** Orchestrate workers, review their output, unblock dependencies.`,
+    );
+    parts.push(`**Spawn workers** for implementation tasks - don't do them yourself.`);
+    parts.push(``);
+    parts.push(`**RESUME STEPS:**`);
+    parts.push(
+      `1. Check swarm status: \`swarm_status(epic_id="${epicId}", project_key="${projectPath}")\``,
+    );
+    parts.push(`2. Check inbox for worker messages: \`swarmmail_inbox(limit=5)\``);
+    parts.push(
+      `3. For in_progress subtasks: Review worker results with \`swarm_review\``,
+    );
+    parts.push(`4. For open subtasks: Spawn workers with \`swarm_spawn_subtask\``);
+    parts.push(`5. For blocked subtasks: Investigate and unblock`);
+  }
+
+  return parts.join("\n");
+}
+
 // ============================================================================
 // Swarm Detection
 // ============================================================================
@@ -678,17 +790,21 @@ async function detectSwarm(): Promise<SwarmDetection> {
  * Philosophy: Err on the side of continuation. A false positive costs
  * a bit of context space. A false negative loses the swarm.
  *
+ * @param client - Optional OpenCode SDK client for scanning session messages.
+ *                 When provided, extracts PRECISE swarm state from actual tool calls.
+ *                 When undefined, falls back to hive/swarm-mail heuristic detection.
+ *
  * @example
  * ```typescript
  * import { createCompactionHook } from "opencode-swarm-plugin";
  *
- * export const SwarmPlugin: Plugin = async () => ({
+ * export const SwarmPlugin: Plugin = async (input) => ({
  *   tool: { ... },
- *   "experimental.session.compacting": createCompactionHook(),
+ *   "experimental.session.compacting": createCompactionHook(input.client),
  * });
  * ```
  */
-export function createCompactionHook() {
+export function createCompactionHook(client?: OpencodeClient) {
   return async (
     input: { sessionID: string },
     output: { context: string[] },
@@ -699,41 +815,73 @@ export function createCompactionHook() {
       {
         session_id: input.sessionID,
         trigger: "session_compaction",
+        has_sdk_client: !!client,
       },
       "compaction started",
     );
 
     try {
+      // Scan session messages for precise swarm state (if client available)
+      const scannedState = await scanSessionMessages(client, input.sessionID);
+      
+      // Also run heuristic detection from hive/swarm-mail
       const detection = await detectSwarm();
 
+      // Boost confidence if we found swarm evidence in session messages
+      let effectiveConfidence = detection.confidence;
+      if (scannedState.epicId || scannedState.subtasks.size > 0) {
+        // Session messages show swarm activity - this is HIGH confidence
+        if (effectiveConfidence === "none" || effectiveConfidence === "low") {
+          effectiveConfidence = "medium";
+          detection.reasons.push("swarm tool calls found in session");
+        }
+        if (scannedState.subtasks.size > 0) {
+          effectiveConfidence = "high";
+          detection.reasons.push(`${scannedState.subtasks.size} subtasks spawned`);
+        }
+      }
+
       if (
-        detection.confidence === "high" ||
-        detection.confidence === "medium"
+        effectiveConfidence === "high" ||
+        effectiveConfidence === "medium"
       ) {
         // Definite or probable swarm - inject full context
         const header = `[Swarm detected: ${detection.reasons.join(", ")}]\n\n`;
-        
-        // Build dynamic state section if we have specific data
+
+        // Build dynamic state section - prefer scanned state (ground truth) over detected
         let dynamicState = "";
-        if (detection.state && detection.state.epicId) {
+        if (scannedState.epicId || scannedState.subtasks.size > 0) {
+          // Use scanned state (more precise)
+          dynamicState =
+            buildDynamicSwarmStateFromScanned(
+              scannedState,
+              detection.state || {
+                projectPath: scannedState.projectPath || process.cwd(),
+                subtasks: { closed: 0, in_progress: 0, open: 0, blocked: 0 },
+              },
+            ) + "\n\n";
+        } else if (detection.state && detection.state.epicId) {
+          // Fall back to hive-detected state
           dynamicState = buildDynamicSwarmState(detection.state) + "\n\n";
         }
-        
+
         const contextContent = header + dynamicState + SWARM_COMPACTION_CONTEXT;
         output.context.push(contextContent);
 
         getLog().info(
           {
-            confidence: detection.confidence,
+            confidence: effectiveConfidence,
             context_length: contextContent.length,
             context_type: "full",
             reasons: detection.reasons,
             has_dynamic_state: !!dynamicState,
-            epic_id: detection.state?.epicId,
+            epic_id: scannedState.epicId || detection.state?.epicId,
+            scanned_subtasks: scannedState.subtasks.size,
+            scanned_agent: scannedState.agentName,
           },
           "injected swarm context",
         );
-      } else if (detection.confidence === "low") {
+      } else if (effectiveConfidence === "low") {
         // Possible swarm - inject fallback detection prompt
         const header = `[Possible swarm: ${detection.reasons.join(", ")}]\n\n`;
         const contextContent = header + SWARM_DETECTION_FALLBACK;
@@ -741,7 +889,7 @@ export function createCompactionHook() {
 
         getLog().info(
           {
-            confidence: detection.confidence,
+            confidence: effectiveConfidence,
             context_length: contextContent.length,
             context_type: "fallback",
             reasons: detection.reasons,
@@ -751,7 +899,7 @@ export function createCompactionHook() {
       } else {
         getLog().debug(
           {
-            confidence: detection.confidence,
+            confidence: effectiveConfidence,
             context_type: "none",
           },
           "no swarm detected, skipping injection",
@@ -764,8 +912,8 @@ export function createCompactionHook() {
         {
           duration_ms: duration,
           success: true,
-          detected: detection.detected,
-          confidence: detection.confidence,
+          detected: detection.detected || scannedState.epicId !== undefined,
+          confidence: effectiveConfidence,
           context_injected: output.context.length > 0,
         },
         "compaction complete",

package/src/eval-capture.ts

@@ -63,8 +63,8 @@ export const EvalRecordSchema = z.object({
   context: z.string().optional(),
   /** Strategy used for decomposition */
   strategy: z.enum(["file-based", "feature-based", "risk-based", "auto"]),
-  /** Max subtasks requested */
-  max_subtasks: z.number().int().min(1).max(10),
+  /** Number of subtasks generated */
+  subtask_count: z.number().int().min(1),
 
   // OUTPUT (the decomposition)
   /** Epic title */
@@ -238,7 +238,6 @@ export function captureDecomposition(params: {
   task: string;
   context?: string;
   strategy: "file-based" | "feature-based" | "risk-based" | "auto";
-  maxSubtasks: number;
   epicTitle: string;
   epicDescription?: string;
   subtasks: Array<{
@@ -256,7 +255,7 @@ export function captureDecomposition(params: {
     task: params.task,
     context: params.context,
     strategy: params.strategy,
-    max_subtasks: params.maxSubtasks,
+    subtask_count: params.subtasks.length,
     epic_title: params.epicTitle,
     epic_description: params.epicDescription,
     subtasks: params.subtasks,
@@ -409,7 +408,7 @@ export function exportForEvalite(projectPath: string): Array<{
   input: { task: string; context?: string };
   expected: {
     minSubtasks: number;
-    maxSubtasks: number;
+    subtaskCount: number;
     requiredFiles?: string[];
     overallSuccess?: boolean;
   };
@@ -426,7 +425,7 @@ export function exportForEvalite(projectPath: string): Array<{
       },
       expected: {
         minSubtasks: 2,
-        maxSubtasks: record.max_subtasks,
+        subtaskCount: record.subtask_count,
         requiredFiles: record.subtasks.flatMap((s) => s.files),
         overallSuccess: record.overall_success,
       },

package/src/index.ts

@@ -58,6 +58,7 @@ import {
   analyzeTodoWrite,
   shouldAnalyzeTool,
 } from "./planning-guardrails";
+import { createCompactionHook } from "./compaction-hook";
 
 /**
  * OpenCode Swarm Plugin
@@ -80,7 +81,7 @@ import {
 export const SwarmPlugin: Plugin = async (
   input: PluginInput,
 ): Promise<Hooks> => {
-  const { $, directory } = input;
+  const { $, directory, client } = input;
 
   // Set the working directory for hive commands
   // This ensures hive operations run in the project directory, not ~/.config/opencode
@@ -261,6 +262,25 @@ export const SwarmPlugin: Plugin = async (
       // Auto-sync was removed because bd CLI is deprecated
       // The hive_sync tool handles flushing to JSONL and git commit/push
     },
+
+    /**
+     * Compaction hook for swarm context preservation
+     *
+     * When OpenCode compacts session context, this hook injects swarm state
+     * to ensure coordinators can resume orchestration seamlessly.
+     *
+     * Uses SDK client to scan actual session messages for precise swarm state
+     * (epic IDs, subtask status, agent names) rather than relying solely on
+     * heuristic detection from hive/swarm-mail.
+     *
+     * Note: This hook is experimental and may not be in the published Hooks type yet.
+     */
+    "experimental.session.compacting": createCompactionHook(client),
+  } as Hooks & {
+    "experimental.session.compacting"?: (
+      input: { sessionID: string },
+      output: { context: string[] },
+    ) => Promise<void>;
   };
 };
 

package/src/learning.integration.test.ts

@@ -976,7 +976,6 @@ describe("Swarm Tool Integrations", () => {
       const result = await swarm_decompose.execute(
         {
           task: "Add user authentication",
-          max_subtasks: 3,
           query_cass: true,
         },
         mockContext,
@@ -992,7 +991,6 @@ describe("Swarm Tool Integrations", () => {
       const result = await swarm_decompose.execute(
         {
           task: "Add user authentication",
-          max_subtasks: 3,
           query_cass: false,
         },
         mockContext,

package/src/schemas/task.ts

@@ -87,7 +87,6 @@ export type TaskDecomposition = z.infer<typeof TaskDecompositionSchema>;
  */
 export const DecomposeArgsSchema = z.object({
   task: z.string().min(1),
-  max_subtasks: z.number().int().min(1).default(5),
   context: z.string().optional(),
 });
 export type DecomposeArgs = z.infer<typeof DecomposeArgsSchema>;

package/src/swarm-decompose.ts

@@ -690,12 +690,6 @@ export const swarm_delegate_planning = tool({
       .string()
       .optional()
       .describe("Additional context to include"),
-    max_subtasks: tool.schema
-      .number()
-      .int()
-      .min(1)
-      .optional()
-      .describe("Suggested max subtasks (optional - LLM decides if not specified)"),
     strategy: tool.schema
       .enum(["auto", "file-based", "feature-based", "risk-based"])
       .optional()
@@ -797,8 +791,7 @@ export const swarm_delegate_planning = tool({
       .replace("{strategy_guidelines}", strategyGuidelines)
       .replace("{context_section}", contextSection)
       .replace("{cass_history}", cassContext || "")
-      .replace("{skills_context}", skillsContext || "")
-      .replace("{max_subtasks}", (args.max_subtasks ?? 5).toString());
+      .replace("{skills_context}", skillsContext || "");
 
     // Add strict JSON-only instructions for the subagent
     const subagentInstructions = `

package/src/swarm.integration.test.ts

@@ -79,7 +79,6 @@ describe("swarm_decompose", () => {
     const result = await swarm_decompose.execute(
       {
         task: "Add user authentication with OAuth",
-        max_subtasks: 3,
       },
       mockContext,
     );
@@ -97,7 +96,6 @@ describe("swarm_decompose", () => {
     const result = await swarm_decompose.execute(
       {
         task: "Refactor the API routes",
-        max_subtasks: 5,
         context: "Using Next.js App Router with RSC",
       },
       mockContext,
@@ -109,20 +107,6 @@ describe("swarm_decompose", () => {
     expect(parsed.prompt).toContain("Additional Context");
   });
 
-  it("uses default max_subtasks when not provided", async () => {
-    const result = await swarm_decompose.execute(
-      {
-        task: "Simple task",
-        max_subtasks: 5, // Explicit default since schema requires it
-      },
-      mockContext,
-    );
-
-    const parsed = JSON.parse(result);
-
-    // Prompt should say "as many as needed" (max_subtasks no longer in template)
-    expect(parsed.prompt).toContain("as many as needed");
-  });
 });
 
 // ============================================================================
@@ -262,7 +246,6 @@ describe("swarm_plan_prompt", () => {
     const result = await swarm_plan_prompt.execute(
       {
         task: "Add user settings page",
-        max_subtasks: 3,
         query_cass: false, // Disable CASS to isolate test
       },
       mockContext,
@@ -281,7 +264,6 @@ describe("swarm_plan_prompt", () => {
       {
         task: "Do something",
         strategy: "risk-based",
-        max_subtasks: 3,
         query_cass: false,
       },
       mockContext,
@@ -296,7 +278,6 @@ describe("swarm_plan_prompt", () => {
     const result = await swarm_plan_prompt.execute(
       {
         task: "Refactor the codebase",
-        max_subtasks: 4,
         query_cass: false,
       },
       mockContext,
@@ -314,7 +295,6 @@ describe("swarm_plan_prompt", () => {
     const result = await swarm_plan_prompt.execute(
       {
         task: "Build new feature",
-        max_subtasks: 3,
         query_cass: false,
       },
       mockContext,
@@ -330,7 +310,6 @@ describe("swarm_plan_prompt", () => {
     const result = await swarm_plan_prompt.execute(
       {
         task: "Some task",
-        max_subtasks: 5,
         query_cass: false,
       },
       mockContext,
@@ -350,7 +329,6 @@ describe("swarm_plan_prompt", () => {
     const result = await swarm_plan_prompt.execute(
       {
         task: "Add feature",
-        max_subtasks: 3,
       },
       mockContext,
     );
@@ -375,7 +353,6 @@ describe("swarm_plan_prompt", () => {
     const result = await swarm_plan_prompt.execute(
       {
         task: "Add user profile",
-        max_subtasks: 3,
         context: "We use Next.js App Router with server components",
         query_cass: false,
       },
@@ -387,19 +364,6 @@ describe("swarm_plan_prompt", () => {
     expect(parsed.prompt).toContain("server components");
   });
 
-  it("includes max_subtasks in prompt", async () => {
-    const result = await swarm_plan_prompt.execute(
-      {
-        task: "Build something",
-        max_subtasks: 7,
-        query_cass: false,
-      },
-      mockContext,
-    );
-    const parsed = JSON.parse(result);
-
-    expect(parsed.prompt).toContain("as many as needed");
-  });
 });
 
 describe("swarm_validate_decomposition", () => {
@@ -920,7 +884,6 @@ describe("full swarm flow (integration)", () => {
         const decomposeResult = await swarm_decompose.execute(
           {
             task: "Add unit tests for auth module",
-            max_subtasks: 2,
           },
           ctx,
         );
@@ -1228,7 +1191,6 @@ describe("swarm_init", () => {
     const result = await swarm_decompose.execute(
       {
         task: "Add user authentication",
-        max_subtasks: 3,
         query_cass: true, // Request CASS but it may not be available
       },
       mockContext,
@@ -1249,7 +1211,6 @@ describe("swarm_init", () => {
     const result = await swarm_decompose.execute(
       {
         task: "Add user authentication",
-        max_subtasks: 3,
         query_cass: false, // Explicitly skip CASS
       },
       mockContext,
@@ -1264,7 +1225,6 @@ describe("swarm_init", () => {
     const result = await swarm_decompose.execute(
       {
         task: "Build feature X",
-        max_subtasks: 3,
       },
       mockContext,
     );