opencode-swarm 4.4.0 → 5.0.0

package/dist/config/plan-schema.d.ts

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+export declare const TaskStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    in_progress: "in_progress";
+    completed: "completed";
+    blocked: "blocked";
+}>;
+export type TaskStatus = z.infer<typeof TaskStatusSchema>;
+export declare const TaskSizeSchema: z.ZodEnum<{
+    small: "small";
+    medium: "medium";
+    large: "large";
+}>;
+export type TaskSize = z.infer<typeof TaskSizeSchema>;
+export declare const PhaseStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    in_progress: "in_progress";
+    blocked: "blocked";
+    complete: "complete";
+}>;
+export type PhaseStatus = z.infer<typeof PhaseStatusSchema>;
+export declare const MigrationStatusSchema: z.ZodEnum<{
+    native: "native";
+    migrated: "migrated";
+    migration_failed: "migration_failed";
+}>;
+export type MigrationStatus = z.infer<typeof MigrationStatusSchema>;
+export declare const TaskSchema: z.ZodObject<{
+    id: z.ZodString;
+    phase: z.ZodNumber;
+    status: z.ZodDefault<z.ZodEnum<{
+        pending: "pending";
+        in_progress: "in_progress";
+        completed: "completed";
+        blocked: "blocked";
+    }>>;
+    size: z.ZodDefault<z.ZodEnum<{
+        small: "small";
+        medium: "medium";
+        large: "large";
+    }>>;
+    description: z.ZodString;
+    depends: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    acceptance: z.ZodOptional<z.ZodString>;
+    files_touched: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    evidence_path: z.ZodOptional<z.ZodString>;
+    blocked_reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type Task = z.infer<typeof TaskSchema>;
+export declare const PhaseSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    name: z.ZodString;
+    status: z.ZodDefault<z.ZodEnum<{
+        pending: "pending";
+        in_progress: "in_progress";
+        blocked: "blocked";
+        complete: "complete";
+    }>>;
+    tasks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        phase: z.ZodNumber;
+        status: z.ZodDefault<z.ZodEnum<{
+            pending: "pending";
+            in_progress: "in_progress";
+            completed: "completed";
+            blocked: "blocked";
+        }>>;
+        size: z.ZodDefault<z.ZodEnum<{
+            small: "small";
+            medium: "medium";
+            large: "large";
+        }>>;
+        description: z.ZodString;
+        depends: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        acceptance: z.ZodOptional<z.ZodString>;
+        files_touched: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        evidence_path: z.ZodOptional<z.ZodString>;
+        blocked_reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type Phase = z.infer<typeof PhaseSchema>;
+export declare const PlanSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<"1.0.0">;
+    title: z.ZodString;
+    swarm: z.ZodString;
+    current_phase: z.ZodNumber;
+    phases: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        name: z.ZodString;
+        status: z.ZodDefault<z.ZodEnum<{
+            pending: "pending";
+            in_progress: "in_progress";
+            blocked: "blocked";
+            complete: "complete";
+        }>>;
+        tasks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            phase: z.ZodNumber;
+            status: z.ZodDefault<z.ZodEnum<{
+                pending: "pending";
+                in_progress: "in_progress";
+                completed: "completed";
+                blocked: "blocked";
+            }>>;
+            size: z.ZodDefault<z.ZodEnum<{
+                small: "small";
+                medium: "medium";
+                large: "large";
+            }>>;
+            description: z.ZodString;
+            depends: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            acceptance: z.ZodOptional<z.ZodString>;
+            files_touched: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            evidence_path: z.ZodOptional<z.ZodString>;
+            blocked_reason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    migration_status: z.ZodOptional<z.ZodEnum<{
+        native: "native";
+        migrated: "migrated";
+        migration_failed: "migration_failed";
+    }>>;
+}, z.core.$strip>;
+export type Plan = z.infer<typeof PlanSchema>;

package/dist/config/schema.d.ts

@@ -27,8 +27,49 @@ export declare const ContextBudgetConfigSchema: z.ZodObject<{
     warn_threshold: z.ZodDefault<z.ZodNumber>;
     critical_threshold: z.ZodDefault<z.ZodNumber>;
     model_limits: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    max_injection_tokens: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 export type ContextBudgetConfig = z.infer<typeof ContextBudgetConfigSchema>;
+export declare const EvidenceConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    max_age_days: z.ZodDefault<z.ZodNumber>;
+    max_bundles: z.ZodDefault<z.ZodNumber>;
+    auto_archive: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type EvidenceConfig = z.infer<typeof EvidenceConfigSchema>;
+export declare const GuardrailsProfileSchema: z.ZodObject<{
+    max_tool_calls: z.ZodOptional<z.ZodNumber>;
+    max_duration_minutes: z.ZodOptional<z.ZodNumber>;
+    max_repetitions: z.ZodOptional<z.ZodNumber>;
+    max_consecutive_errors: z.ZodOptional<z.ZodNumber>;
+    warning_threshold: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type GuardrailsProfile = z.infer<typeof GuardrailsProfileSchema>;
+export declare const GuardrailsConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    max_tool_calls: z.ZodDefault<z.ZodNumber>;
+    max_duration_minutes: z.ZodDefault<z.ZodNumber>;
+    max_repetitions: z.ZodDefault<z.ZodNumber>;
+    max_consecutive_errors: z.ZodDefault<z.ZodNumber>;
+    warning_threshold: z.ZodDefault<z.ZodNumber>;
+    profiles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        max_tool_calls: z.ZodOptional<z.ZodNumber>;
+        max_duration_minutes: z.ZodOptional<z.ZodNumber>;
+        max_repetitions: z.ZodOptional<z.ZodNumber>;
+        max_consecutive_errors: z.ZodOptional<z.ZodNumber>;
+        warning_threshold: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type GuardrailsConfig = z.infer<typeof GuardrailsConfigSchema>;
+/**
+ * Resolve guardrails configuration for a specific agent.
+ * Merges the base config with any per-agent profile overrides.
+ *
+ * @param base - The base guardrails configuration
+ * @param agentName - Optional agent name to look up profile overrides
+ * @returns The effective guardrails configuration for the agent
+ */
+export declare function resolveGuardrailsConfig(base: GuardrailsConfig, agentName?: string): GuardrailsConfig;
 export declare const PluginConfigSchema: z.ZodObject<{
     agents: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         model: z.ZodOptional<z.ZodString>;
@@ -58,6 +99,28 @@ export declare const PluginConfigSchema: z.ZodObject<{
         warn_threshold: z.ZodDefault<z.ZodNumber>;
         critical_threshold: z.ZodDefault<z.ZodNumber>;
         model_limits: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        max_injection_tokens: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    guardrails: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        max_tool_calls: z.ZodDefault<z.ZodNumber>;
+        max_duration_minutes: z.ZodDefault<z.ZodNumber>;
+        max_repetitions: z.ZodDefault<z.ZodNumber>;
+        max_consecutive_errors: z.ZodDefault<z.ZodNumber>;
+        warning_threshold: z.ZodDefault<z.ZodNumber>;
+        profiles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            max_tool_calls: z.ZodOptional<z.ZodNumber>;
+            max_duration_minutes: z.ZodOptional<z.ZodNumber>;
+            max_repetitions: z.ZodOptional<z.ZodNumber>;
+            max_consecutive_errors: z.ZodOptional<z.ZodNumber>;
+            warning_threshold: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    evidence: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        max_age_days: z.ZodDefault<z.ZodNumber>;
+        max_bundles: z.ZodDefault<z.ZodNumber>;
+        auto_archive: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type PluginConfig = z.infer<typeof PluginConfigSchema>;

package/dist/evidence/index.d.ts

@@ -0,0 +1 @@
+export { archiveEvidence, deleteEvidence, listEvidenceTaskIds, loadEvidence, sanitizeTaskId, saveEvidence, } from './manager';

package/dist/evidence/manager.d.ts

@@ -0,0 +1,38 @@
+import { type Evidence, type EvidenceBundle } from '../config/evidence-schema';
+/**
+ * Validate and sanitize task ID.
+ * Must match regex ^[\w-]+(\.[\w-]+)*$
+ * Rejects: .., ../, null bytes, control characters, empty string
+ * @throws Error with descriptive message on failure
+ */
+export declare function sanitizeTaskId(taskId: string): string;
+/**
+ * Save evidence to a task's evidence bundle.
+ * Creates new bundle if doesn't exist, appends to existing.
+ * Performs atomic write via temp file + rename.
+ * @throws Error if task ID is invalid or size limit would be exceeded
+ */
+export declare function saveEvidence(directory: string, taskId: string, evidence: Evidence): Promise<EvidenceBundle>;
+/**
+ * Load evidence bundle for a task.
+ * Returns null if file doesn't exist or validation fails.
+ */
+export declare function loadEvidence(directory: string, taskId: string): Promise<EvidenceBundle | null>;
+/**
+ * List all task IDs that have evidence bundles.
+ * Returns sorted array of valid task IDs.
+ * Returns empty array if evidence directory doesn't exist.
+ */
+export declare function listEvidenceTaskIds(directory: string): Promise<string[]>;
+/**
+ * Delete evidence bundle for a task.
+ * Returns true if deleted, false if didn't exist or deletion failed.
+ */
+export declare function deleteEvidence(directory: string, taskId: string): Promise<boolean>;
+/**
+ * Archive old evidence bundles based on retention policy.
+ * Removes evidence older than maxAgeDays.
+ * If maxBundles is provided, enforces a maximum bundle count by deleting oldest first.
+ * Returns array of archived (deleted) task IDs.
+ */
+export declare function archiveEvidence(directory: string, maxAgeDays: number, maxBundles?: number): Promise<string[]>;

package/dist/guardrails.js

@@ -0,0 +1,178 @@
+// src/state.ts
+var swarmState = {
+  activeToolCalls: new Map,
+  toolAggregates: new Map,
+  activeAgent: new Map,
+  delegationChains: new Map,
+  pendingEvents: 0,
+  agentSessions: new Map
+};
+function startAgentSession(sessionId, agentName, staleDurationMs = 3600000) {
+  const now = Date.now();
+  for (const [id, session] of swarmState.agentSessions) {
+    if (now - session.startTime > staleDurationMs) {
+      swarmState.agentSessions.delete(id);
+    }
+  }
+  const sessionState = {
+    agentName,
+    startTime: now,
+    toolCallCount: 0,
+    consecutiveErrors: 0,
+    recentToolCalls: [],
+    warningIssued: false,
+    hardLimitHit: false
+  };
+  swarmState.agentSessions.set(sessionId, sessionState);
+}
+function getAgentSession(sessionId) {
+  return swarmState.agentSessions.get(sessionId);
+}
+// src/utils/logger.ts
+var DEBUG = process.env.OPENCODE_SWARM_DEBUG === "1";
+function warn(message, data) {
+  const timestamp = new Date().toISOString();
+  if (data !== undefined) {
+    console.warn(`[opencode-swarm ${timestamp}] WARN: ${message}`, data);
+  } else {
+    console.warn(`[opencode-swarm ${timestamp}] WARN: ${message}`);
+  }
+}
+// src/hooks/guardrails.ts
+function createGuardrailsHooks(config) {
+  if (config.enabled === false) {
+    return {
+      toolBefore: async () => {},
+      toolAfter: async () => {},
+      messagesTransform: async () => {}
+    };
+  }
+  return {
+    toolBefore: async (input, output) => {
+      let session = getAgentSession(input.sessionID);
+      if (!session) {
+        startAgentSession(input.sessionID, "unknown");
+        session = getAgentSession(input.sessionID);
+        if (!session) {
+          warn(`Failed to create session for ${input.sessionID}`);
+          return;
+        }
+      }
+      if (session.hardLimitHit) {
+        throw new Error("\uD83D\uDED1 CIRCUIT BREAKER: Agent blocked. Hard limit was previously triggered. Stop making tool calls and return your progress summary.");
+      }
+      session.toolCallCount++;
+      const hash = hashArgs(output.args);
+      session.recentToolCalls.push({
+        tool: input.tool,
+        argsHash: hash,
+        timestamp: Date.now()
+      });
+      if (session.recentToolCalls.length > 20) {
+        session.recentToolCalls.shift();
+      }
+      let repetitionCount = 0;
+      if (session.recentToolCalls.length > 0) {
+        const lastEntry = session.recentToolCalls[session.recentToolCalls.length - 1];
+        for (let i = session.recentToolCalls.length - 1;i >= 0; i--) {
+          const entry = session.recentToolCalls[i];
+          if (entry.tool === lastEntry.tool && entry.argsHash === lastEntry.argsHash) {
+            repetitionCount++;
+          } else {
+            break;
+          }
+        }
+      }
+      const elapsedMinutes = (Date.now() - session.startTime) / 60000;
+      if (session.toolCallCount >= config.max_tool_calls) {
+        session.hardLimitHit = true;
+        throw new Error(`\uD83D\uDED1 CIRCUIT BREAKER: Tool call limit reached (${session.toolCallCount}/${config.max_tool_calls}). Stop making tool calls and return your progress summary.`);
+      }
+      if (elapsedMinutes >= config.max_duration_minutes) {
+        session.hardLimitHit = true;
+        throw new Error(`\uD83D\uDED1 CIRCUIT BREAKER: Duration limit reached (${Math.floor(elapsedMinutes)} min). Stop making tool calls and return your progress summary.`);
+      }
+      if (repetitionCount >= config.max_repetitions) {
+        session.hardLimitHit = true;
+        throw new Error(`\uD83D\uDED1 CIRCUIT BREAKER: Repetition detected (same call ${repetitionCount} times). Stop making tool calls and return your progress summary.`);
+      }
+      if (session.consecutiveErrors >= config.max_consecutive_errors) {
+        session.hardLimitHit = true;
+        throw new Error(`\uD83D\uDED1 CIRCUIT BREAKER: Too many consecutive errors (${session.consecutiveErrors}). Stop making tool calls and return your progress summary.`);
+      }
+      if (!session.warningIssued) {
+        const toolWarning = session.toolCallCount >= config.max_tool_calls * config.warning_threshold;
+        const durationWarning = elapsedMinutes >= config.max_duration_minutes * config.warning_threshold;
+        const repetitionWarning = repetitionCount >= config.max_repetitions * config.warning_threshold;
+        const errorWarning = session.consecutiveErrors >= config.max_consecutive_errors * config.warning_threshold;
+        if (toolWarning || durationWarning || repetitionWarning || errorWarning) {
+          session.warningIssued = true;
+        }
+      }
+    },
+    toolAfter: async (input, output) => {
+      const session = getAgentSession(input.sessionID);
+      if (!session) {
+        return;
+      }
+      const outputStr = String(output.output ?? "");
+      const hasError = output.output === null || output.output === undefined || outputStr === "" || outputStr.toLowerCase().includes("error");
+      if (hasError) {
+        session.consecutiveErrors++;
+      } else {
+        session.consecutiveErrors = 0;
+      }
+    },
+    messagesTransform: async (input, output) => {
+      const messages = output.messages;
+      if (!messages || messages.length === 0) {
+        return;
+      }
+      const lastMessage = messages[messages.length - 1];
+      let sessionId = lastMessage.info?.sessionID;
+      if (!sessionId) {
+        for (const [id, session2] of swarmState.agentSessions) {
+          if (session2.warningIssued || session2.hardLimitHit) {
+            sessionId = id;
+            break;
+          }
+        }
+      }
+      if (!sessionId) {
+        return;
+      }
+      const session = getAgentSession(sessionId);
+      if (!session || !session.warningIssued && !session.hardLimitHit) {
+        return;
+      }
+      const textPart = lastMessage.parts.find((part) => part.type === "text" && typeof part.text === "string");
+      if (!textPart) {
+        return;
+      }
+      if (session.hardLimitHit) {
+        textPart.text = `[\uD83D\uDED1 CIRCUIT BREAKER ACTIVE: You have exceeded your resource limits. Do NOT make any more tool calls. Immediately return a summary of your progress so far. Any further tool calls will be blocked.]
+
+` + textPart.text;
+      } else if (session.warningIssued) {
+        textPart.text = `[⚠️ GUARDRAIL WARNING: You are approaching resource limits. Please wrap up your current task efficiently. Avoid unnecessary tool calls and prepare to return your results soon.]
+
+` + textPart.text;
+      }
+    }
+  };
+}
+function hashArgs(args) {
+  try {
+    if (typeof args !== "object" || args === null) {
+      return 0;
+    }
+    const sortedKeys = Object.keys(args).sort();
+    return Number(Bun.hash(JSON.stringify(args, sortedKeys)));
+  } catch {
+    return 0;
+  }
+}
+export {
+  hashArgs,
+  createGuardrailsHooks
+};

package/dist/hooks/extractors.d.ts

@@ -1,3 +1,4 @@
+import type { Plan } from '../config/plan-schema';
 /**
  * Swarm File Extractors
  *
@@ -24,3 +25,15 @@ export declare function extractIncompleteTasks(planContent: string, maxChars?: n
  * Extracts patterns section from context content.
  */
 export declare function extractPatterns(contextContent: string, maxChars?: number): string | null;
+/**
+ * Extracts current phase info from a Plan object.
+ */
+export declare function extractCurrentPhaseFromPlan(plan: Plan): string | null;
+/**
+ * Extracts the first incomplete task from the current phase of a Plan object.
+ */
+export declare function extractCurrentTaskFromPlan(plan: Plan): string | null;
+/**
+ * Extracts incomplete tasks from the current phase of a Plan object.
+ */
+export declare function extractIncompleteTasksFromPlan(plan: Plan, maxChars?: number): string | null;

package/dist/hooks/guardrails.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Guardrails Hook Module
+ *
+ * Circuit breaker for runaway LLM agents. Monitors tool usage via OpenCode Plugin API hooks
+ * and implements two-layer protection:
+ * - Layer 1 (Soft Warning @ warning_threshold): Sets warning flag for messagesTransform to inject warning
+ * - Layer 2 (Hard Block @ 100%): Throws error in toolBefore to block further calls, injects STOP message
+ */
+import { type GuardrailsConfig } from '../config/schema';
+/**
+ * Creates guardrails hooks for circuit breaker protection
+ * @param config Guardrails configuration
+ * @returns Tool before/after hooks and messages transform hook
+ */
+export declare function createGuardrailsHooks(config: GuardrailsConfig): {
+    toolBefore: (input: {
+        tool: string;
+        sessionID: string;
+        callID: string;
+    }, output: {
+        args: unknown;
+    }) => Promise<void>;
+    toolAfter: (input: {
+        tool: string;
+        sessionID: string;
+        callID: string;
+    }, output: {
+        title: string;
+        output: string;
+        metadata: unknown;
+    }) => Promise<void>;
+    messagesTransform: (input: Record<string, never>, output: {
+        messages?: Array<{
+            info: {
+                role: string;
+                agent?: string;
+                sessionID?: string;
+            };
+            parts: Array<{
+                type: string;
+                text?: string;
+                [key: string]: unknown;
+            }>;
+        }>;
+    }) => Promise<void>;
+};
+/**
+ * Hashes tool arguments for repetition detection
+ * @param args Tool arguments to hash
+ * @returns Numeric hash (0 if hashing fails)
+ */
+export declare function hashArgs(args: unknown): number;

package/dist/hooks/index.d.ts

@@ -2,7 +2,8 @@ export { createAgentActivityHooks } from './agent-activity';
 export { createCompactionCustomizerHook } from './compaction-customizer';
 export { createContextBudgetHandler } from './context-budget';
 export { createDelegationTrackerHook } from './delegation-tracker';
-export { extractCurrentPhase, extractCurrentTask, extractDecisions, extractIncompleteTasks, extractPatterns, } from './extractors';
+export { extractCurrentPhase, extractCurrentPhaseFromPlan, extractCurrentTask, extractCurrentTaskFromPlan, extractDecisions, extractIncompleteTasks, extractIncompleteTasksFromPlan, extractPatterns, } from './extractors';
+export { createGuardrailsHooks } from './guardrails';
 export { createPipelineTrackerHook } from './pipeline-tracker';
 export { createSystemEnhancerHook } from './system-enhancer';
 export { composeHandlers, estimateTokens, readSwarmFileAsync, safeHook, validateSwarmPath, } from './utils';