opencode-swarm-plugin 0.38.0 → 0.40.0

package/src/memory.ts

@@ -129,6 +129,39 @@ export interface OperationResult {
 	readonly message?: string;
 }
 
+/** Arguments for upsert operation */
+export interface UpsertArgs {
+	readonly information: string;
+	readonly collection?: string;
+	readonly tags?: string;
+	readonly metadata?: string;
+	readonly confidence?: number;
+	/** Auto-generate tags using LLM. Default true */
+	readonly autoTag?: boolean;
+	/** Auto-link to related memories. Default true */
+	readonly autoLink?: boolean;
+	/** Extract entities (people, places, technologies). Default false */
+	readonly extractEntities?: boolean;
+}
+
+/** Auto-generated tags result */
+export interface AutoTags {
+	readonly tags: string[];
+	readonly keywords: string[];
+	readonly category: string;
+}
+
+/** Result from upsert operation */
+export interface UpsertResult {
+	readonly operation: "ADD" | "UPDATE" | "DELETE" | "NOOP";
+	readonly reason: string;
+	readonly memoryId?: string;
+	readonly affectedMemoryIds?: string[];
+	readonly autoTags?: AutoTags;
+	readonly linksCreated?: number;
+	readonly entitiesExtracted?: number;
+}
+
 // ============================================================================
 // Auto-Migration Logic
 // ============================================================================
@@ -206,6 +239,7 @@ export interface MemoryAdapter {
 	readonly list: (args: ListArgs) => Promise<Memory[]>;
 	readonly stats: () => Promise<StatsResult>;
 	readonly checkHealth: () => Promise<HealthResult>;
+	readonly upsert: (args: UpsertArgs) => Promise<UpsertResult>;
 }
 
 /**

package/src/post-compaction-tracker.test.ts

@@ -0,0 +1,251 @@
+/**
+ * Post-Compaction Tool Call Tracker Tests
+ *
+ * TDD: RED → GREEN → REFACTOR
+ *
+ * Tests tracking of tool calls after compaction resumption.
+ * Emits resumption_started on first tool call, then tool_call_tracked for each call (max 20).
+ * Detects coordinator violations: Edit, Write, swarmmail_reserve are forbidden.
+ */
+import { describe, test, expect, beforeEach, mock } from "bun:test";
+import {
+  createPostCompactionTracker,
+  type PostCompactionTracker,
+  type ToolCallEvent,
+} from "./post-compaction-tracker";
+
+describe("PostCompactionTracker - TDD", () => {
+  let tracker: PostCompactionTracker;
+  let mockCapture: ReturnType<typeof mock>;
+
+  beforeEach(() => {
+    mockCapture = mock((event: any) => {});
+    tracker = createPostCompactionTracker({
+      sessionId: "test-session",
+      epicId: "mjkwehsqnbm",
+      onEvent: mockCapture,
+    });
+  });
+
+  // ============================================================================
+  // RED: Test resumption_started event
+  // ============================================================================
+
+  test("emits resumption_started on first tool call", () => {
+    const toolCall: ToolCallEvent = {
+      tool: "read",
+      args: { filePath: "/test/file.ts" },
+      timestamp: Date.now(),
+    };
+
+    tracker.trackToolCall(toolCall);
+
+    expect(mockCapture).toHaveBeenCalledTimes(2); // resumption_started + tool_call_tracked
+    const firstCall = mockCapture.mock.calls[0][0];
+    expect(firstCall.compaction_type).toBe("resumption_started");
+    expect(firstCall.payload.session_id).toBe("test-session");
+    expect(firstCall.payload.epic_id).toBe("mjkwehsqnbm");
+  });
+
+  test("resumption_started only emitted once", () => {
+    tracker.trackToolCall({
+      tool: "read",
+      args: {},
+      timestamp: Date.now(),
+    });
+    tracker.trackToolCall({
+      tool: "glob",
+      args: {},
+      timestamp: Date.now(),
+    });
+
+    // First call: resumption_started + tool_call_tracked
+    // Second call: tool_call_tracked only
+    expect(mockCapture).toHaveBeenCalledTimes(3);
+
+    const calls = mockCapture.mock.calls;
+    expect(calls[0][0].compaction_type).toBe("resumption_started");
+    expect(calls[1][0].compaction_type).toBe("tool_call_tracked");
+    expect(calls[2][0].compaction_type).toBe("tool_call_tracked");
+  });
+
+  // ============================================================================
+  // RED: Test tool_call_tracked event
+  // ============================================================================
+
+  test("emits tool_call_tracked for each of first 20 calls", () => {
+    for (let i = 0; i < 20; i++) {
+      tracker.trackToolCall({
+        tool: `tool-${i}`,
+        args: {},
+        timestamp: Date.now(),
+      });
+    }
+
+    // First call: resumption_started + tool_call_tracked = 2
+    // Next 19 calls: tool_call_tracked only = 19
+    // Total: 21 events (1 resumption_started + 20 tool_call_tracked)
+    expect(mockCapture).toHaveBeenCalledTimes(21);
+
+    const trackedEvents = mockCapture.mock.calls.filter(
+      (call: any) => call[0].compaction_type === "tool_call_tracked",
+    );
+    expect(trackedEvents).toHaveLength(20);
+  });
+
+  test("tool_call_tracked includes tool name and args", () => {
+    tracker.trackToolCall({
+      tool: "edit",
+      args: { filePath: "/test.ts", oldString: "foo", newString: "bar" },
+      timestamp: Date.now(),
+    });
+
+    const trackedEvent = mockCapture.mock.calls.find(
+      (call: any) => call[0].compaction_type === "tool_call_tracked",
+    )?.[0];
+
+    expect(trackedEvent).toBeDefined();
+    expect(trackedEvent.payload.tool).toBe("edit");
+    expect(trackedEvent.payload.args.filePath).toBe("/test.ts");
+    expect(trackedEvent.payload.call_number).toBe(1);
+  });
+
+  // ============================================================================
+  // RED: Test coordinator violation detection
+  // ============================================================================
+
+  test("detects Edit as coordinator violation", () => {
+    tracker.trackToolCall({
+      tool: "edit",
+      args: { filePath: "/test.ts", oldString: "a", newString: "b" },
+      timestamp: Date.now(),
+    });
+
+    const trackedEvent = mockCapture.mock.calls.find(
+      (call: any) => call[0].compaction_type === "tool_call_tracked",
+    )?.[0];
+
+    expect(trackedEvent.payload.is_coordinator_violation).toBe(true);
+    expect(trackedEvent.payload.violation_reason).toBe(
+      "Coordinators NEVER edit files - spawn worker instead",
+    );
+  });
+
+  test("detects Write as coordinator violation", () => {
+    tracker.trackToolCall({
+      tool: "write",
+      args: { filePath: "/new.ts", content: "export {}" },
+      timestamp: Date.now(),
+    });
+
+    const trackedEvent = mockCapture.mock.calls.find(
+      (call: any) => call[0].compaction_type === "tool_call_tracked",
+    )?.[0];
+
+    expect(trackedEvent.payload.is_coordinator_violation).toBe(true);
+    expect(trackedEvent.payload.violation_reason).toBe(
+      "Coordinators NEVER write files - spawn worker instead",
+    );
+  });
+
+  test("detects swarmmail_reserve as coordinator violation", () => {
+    tracker.trackToolCall({
+      tool: "swarmmail_reserve",
+      args: { paths: ["/src/**"], reason: "test" },
+      timestamp: Date.now(),
+    });
+
+    const trackedEvent = mockCapture.mock.calls.find(
+      (call: any) => call[0].compaction_type === "tool_call_tracked",
+    )?.[0];
+
+    expect(trackedEvent.payload.is_coordinator_violation).toBe(true);
+    expect(trackedEvent.payload.violation_reason).toBe(
+      "Coordinators NEVER reserve files - workers reserve files",
+    );
+  });
+
+  test("does not flag Read as violation", () => {
+    tracker.trackToolCall({
+      tool: "read",
+      args: { filePath: "/test.ts" },
+      timestamp: Date.now(),
+    });
+
+    const trackedEvent = mockCapture.mock.calls.find(
+      (call: any) => call[0].compaction_type === "tool_call_tracked",
+    )?.[0];
+
+    expect(trackedEvent.payload.is_coordinator_violation).toBe(false);
+    expect(trackedEvent.payload.violation_reason).toBeUndefined();
+  });
+
+  test("does not flag swarm_spawn_subtask as violation", () => {
+    tracker.trackToolCall({
+      tool: "swarm_spawn_subtask",
+      args: { bead_id: "bd-123", subtask_title: "Test" },
+      timestamp: Date.now(),
+    });
+
+    const trackedEvent = mockCapture.mock.calls.find(
+      (call: any) => call[0].compaction_type === "tool_call_tracked",
+    )?.[0];
+
+    expect(trackedEvent.payload.is_coordinator_violation).toBe(false);
+  });
+
+  // ============================================================================
+  // RED: Test tracking stops after 20 calls
+  // ============================================================================
+
+  test("stops tracking after 20 calls", () => {
+    for (let i = 0; i < 25; i++) {
+      tracker.trackToolCall({
+        tool: `tool-${i}`,
+        args: {},
+        timestamp: Date.now(),
+      });
+    }
+
+    // Should only track first 20: 1 resumption_started + 20 tool_call_tracked
+    expect(mockCapture).toHaveBeenCalledTimes(21);
+  });
+
+  test("returns tracking status", () => {
+    expect(tracker.isTracking()).toBe(true);
+
+    for (let i = 0; i < 20; i++) {
+      tracker.trackToolCall({
+        tool: `tool-${i}`,
+        args: {},
+        timestamp: Date.now(),
+      });
+    }
+
+    expect(tracker.isTracking()).toBe(false);
+  });
+
+  // ============================================================================
+  // RED: Test configurable limit
+  // ============================================================================
+
+  test("respects custom call limit", () => {
+    const customTracker = createPostCompactionTracker({
+      sessionId: "test",
+      epicId: "test",
+      onEvent: mockCapture,
+      maxCalls: 5,
+    });
+
+    for (let i = 0; i < 10; i++) {
+      customTracker.trackToolCall({
+        tool: `tool-${i}`,
+        args: {},
+        timestamp: Date.now(),
+      });
+    }
+
+    // 1 resumption_started + 5 tool_call_tracked
+    expect(mockCapture).toHaveBeenCalledTimes(6);
+  });
+});

package/src/post-compaction-tracker.ts

@@ -0,0 +1,237 @@
+/**
+ * Post-Compaction Tool Call Tracker
+ *
+ * Tracks tool calls after compaction resumption to detect coordinator violations
+ * and provide learning signals for eval-driven development.
+ *
+ * ## Purpose
+ *
+ * When context is compacted, the continuation agent needs observation to learn
+ * if it's following coordinator discipline. This tracker:
+ *
+ * 1. Emits resumption_started on first tool call (marks compaction exit)
+ * 2. Tracks up to N tool calls (default 20) with violation detection
+ * 3. Stops tracking after limit to avoid noise in long sessions
+ *
+ * ## Coordinator Violations Detected
+ *
+ * - **Edit/Write**: Coordinators NEVER edit files - spawn worker instead
+ * - **swarmmail_reserve/agentmail_reserve**: Workers reserve, not coordinators
+ *
+ * ## Integration
+ *
+ * Used by compaction hook to wire tool.call events → eval capture.
+ *
+ * @example
+ * ```typescript
+ * const tracker = createPostCompactionTracker({
+ *   sessionId: "session-123",
+ *   epicId: "bd-epic-456",
+ *   onEvent: captureCompactionEvent,
+ * });
+ *
+ * // Wire to OpenCode hook
+ * hooks["tool.call"] = (input) => {
+ *   tracker.trackToolCall({
+ *     tool: input.tool,
+ *     args: input.args,
+ *     timestamp: Date.now(),
+ *   });
+ * };
+ * ```
+ */
+
+/**
+ * Tool call event structure
+ */
+export interface ToolCallEvent {
+  tool: string;
+  args: Record<string, unknown>;
+  timestamp: number;
+}
+
+/**
+ * Compaction event payload (matches eval-capture.ts structure)
+ */
+export interface CompactionEvent {
+  session_id: string;
+  epic_id: string;
+  compaction_type:
+    | "detection_complete"
+    | "prompt_generated"
+    | "context_injected"
+    | "resumption_started"
+    | "tool_call_tracked";
+  payload: {
+    session_id?: string;
+    epic_id?: string;
+    tool?: string;
+    args?: Record<string, unknown>;
+    call_number?: number;
+    is_coordinator_violation?: boolean;
+    violation_reason?: string;
+    timestamp?: number;
+  };
+}
+
+/**
+ * Tracker configuration
+ */
+export interface PostCompactionTrackerConfig {
+  sessionId: string;
+  epicId: string;
+  onEvent: (event: CompactionEvent) => void;
+  maxCalls?: number;
+}
+
+/**
+ * Post-compaction tracker instance
+ */
+export interface PostCompactionTracker {
+  trackToolCall(event: ToolCallEvent): void;
+  isTracking(): boolean;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/**
+ * Default maximum number of tool calls to track
+ *
+ * Chosen to balance:
+ * - Enough data for pattern detection (20 calls is ~2-3 minutes of coordinator work)
+ * - Avoiding noise pollution in long sessions
+ */
+export const DEFAULT_MAX_TRACKED_CALLS = 20;
+
+// ============================================================================
+// Coordinator Violation Detection
+// ============================================================================
+
+/**
+ * Tools that coordinators are NEVER allowed to use
+ *
+ * Key insight from semantic memory: coordinators lose identity after compaction
+ * and start doing implementation work. These violations are observable signals
+ * that the coordinator mandate wasn't preserved in continuation prompt.
+ */
+const FORBIDDEN_COORDINATOR_TOOLS: Record<string, string> = {
+  edit: "Coordinators NEVER edit files - spawn worker instead",
+  write: "Coordinators NEVER write files - spawn worker instead",
+  swarmmail_reserve: "Coordinators NEVER reserve files - workers reserve files",
+  agentmail_reserve: "Coordinators NEVER reserve files - workers reserve files",
+};
+
+/**
+ * Check if tool call is a coordinator violation
+ *
+ * @param tool - Tool name from OpenCode tool.call hook
+ * @returns Violation status with reason if forbidden
+ *
+ * @example
+ * ```typescript
+ * const result = isCoordinatorViolation("edit");
+ * // { isViolation: true, reason: "Coordinators NEVER edit..." }
+ *
+ * const result = isCoordinatorViolation("read");
+ * // { isViolation: false }
+ * ```
+ */
+export function isCoordinatorViolation(tool: string): {
+  isViolation: boolean;
+  reason?: string;
+} {
+  const reason = FORBIDDEN_COORDINATOR_TOOLS[tool];
+  return {
+    isViolation: !!reason,
+    reason,
+  };
+}
+
+// ============================================================================
+// Tracker Factory
+// ============================================================================
+
+/**
+ * Create a post-compaction tool call tracker
+ *
+ * @example
+ * ```typescript
+ * const tracker = createPostCompactionTracker({
+ *   sessionId: "session-123",
+ *   epicId: "bd-epic-456",
+ *   onEvent: (event) => captureCompactionEvent(event),
+ *   maxCalls: 20
+ * });
+ *
+ * // Track tool calls
+ * tracker.trackToolCall({
+ *   tool: "read",
+ *   args: { filePath: "/test.ts" },
+ *   timestamp: Date.now()
+ * });
+ * ```
+ */
+export function createPostCompactionTracker(
+  config: PostCompactionTrackerConfig,
+): PostCompactionTracker {
+  const {
+    sessionId,
+    epicId,
+    onEvent,
+    maxCalls = DEFAULT_MAX_TRACKED_CALLS,
+  } = config;
+
+  let callCount = 0;
+  let resumptionEmitted = false;
+
+  return {
+    trackToolCall(event: ToolCallEvent): void {
+      // Stop tracking after max calls reached
+      if (callCount >= maxCalls) {
+        return;
+      }
+
+      // Emit resumption_started on first call
+      if (!resumptionEmitted) {
+        onEvent({
+          session_id: sessionId,
+          epic_id: epicId,
+          compaction_type: "resumption_started",
+          payload: {
+            session_id: sessionId,
+            epic_id: epicId,
+            timestamp: event.timestamp,
+          },
+        });
+        resumptionEmitted = true;
+      }
+
+      // Increment before emitting so call_number is 1-based
+      callCount++;
+
+      // Check for coordinator violations
+      const violation = isCoordinatorViolation(event.tool);
+
+      // Emit tool_call_tracked event
+      onEvent({
+        session_id: sessionId,
+        epic_id: epicId,
+        compaction_type: "tool_call_tracked",
+        payload: {
+          tool: event.tool,
+          args: event.args,
+          call_number: callCount,
+          is_coordinator_violation: violation.isViolation,
+          violation_reason: violation.reason,
+          timestamp: event.timestamp,
+        },
+      });
+    },
+
+    isTracking(): boolean {
+      return callCount < maxCalls;
+    },
+  };
+}

package/src/swarm-decompose.ts

@@ -753,7 +753,7 @@ export const swarm_delegate_planning = tool({
       .default(true)
       .describe("Query CASS for similar past tasks (default: true)"),
   },
-  async execute(args) {
+  async execute(args, _ctx) {
     // Import needed modules
     const { selectStrategy, formatStrategyGuidelines } =
       await import("./swarm-strategies");
@@ -777,7 +777,7 @@ export const swarm_delegate_planning = tool({
     // Capture strategy selection decision
     try {
       captureCoordinatorEvent({
-        session_id: process.env.OPENCODE_SESSION_ID || "unknown",
+        session_id: _ctx.sessionID || "unknown",
         epic_id: "planning", // No epic ID yet - this is pre-decomposition
         timestamp: new Date().toISOString(),
         event_type: "DECISION",

package/src/swarm-orchestrate.ts

@@ -1740,7 +1740,7 @@ Files touched: ${args.files_touched?.join(", ") || "none recorded"}`,
       try {
         const durationMs = args.start_time ? Date.now() - args.start_time : 0;
         captureCoordinatorEvent({
-          session_id: process.env.OPENCODE_SESSION_ID || "unknown",
+          session_id: _ctx.sessionID || "unknown",
           epic_id: epicId,
           timestamp: new Date().toISOString(),
           event_type: "OUTCOME",
@@ -1849,7 +1849,7 @@ Files touched: ${args.files_touched?.join(", ") || "none recorded"}`,
       try {
         const durationMs = args.start_time ? Date.now() - args.start_time : 0;
         captureCoordinatorEvent({
-          session_id: process.env.OPENCODE_SESSION_ID || "unknown",
+          session_id: _ctx.sessionID || "unknown",
           epic_id: epicId,
           timestamp: new Date().toISOString(),
           event_type: "OUTCOME",

package/src/swarm-prompts.ts

@@ -1358,7 +1358,7 @@ export const swarm_spawn_subtask = tool({
       .optional()
       .describe("Optional explicit model override (auto-selected if not provided)"),
   },
-  async execute(args) {
+  async execute(args, _ctx) {
     const prompt = formatSubtaskPromptV2({
       bead_id: args.bead_id,
       epic_id: args.epic_id,
@@ -1404,7 +1404,7 @@ export const swarm_spawn_subtask = tool({
     // Capture worker spawn decision
     try {
       captureCoordinatorEvent({
-        session_id: process.env.OPENCODE_SESSION_ID || "unknown",
+        session_id: _ctx.sessionID || "unknown",
         epic_id: args.epic_id,
         timestamp: new Date().toISOString(),
         event_type: "DECISION",

package/src/swarm-review.ts

@@ -470,7 +470,7 @@ export const swarm_review_feedback = tool({
       .optional()
       .describe("JSON array of ReviewIssue objects (for needs_changes)"),
   },
-  async execute(args): Promise<string> {
+  async execute(args, _ctx): Promise<string> {
     // Parse issues if provided
     let parsedIssues: ReviewIssue[] = [];
     if (args.issues) {
@@ -512,7 +512,7 @@ export const swarm_review_feedback = tool({
       // Capture review approval decision
       try {
         captureCoordinatorEvent({
-          session_id: process.env.OPENCODE_SESSION_ID || "unknown",
+          session_id: _ctx.sessionID || "unknown",
           epic_id: epicId,
           timestamp: new Date().toISOString(),
           event_type: "DECISION",
@@ -562,7 +562,7 @@ You may now complete the task with \`swarm_complete\`.`,
     // Capture review rejection decision
     try {
       captureCoordinatorEvent({
-        session_id: process.env.OPENCODE_SESSION_ID || "unknown",
+        session_id: _ctx.sessionID || "unknown",
         epic_id: epicId,
         timestamp: new Date().toISOString(),
         event_type: "DECISION",