opencode-swarm-plugin 0.21.0 → 0.23.0

package/dist/storage.d.ts

@@ -0,0 +1,260 @@
+/**
+ * Storage Module - Pluggable persistence for learning data
+ *
+ * Provides a unified storage interface with multiple backends:
+ * - semantic-memory (default) - Persistent with semantic search
+ * - in-memory - For testing and ephemeral sessions
+ *
+ * The semantic-memory backend uses collections:
+ * - `swarm-feedback` - Criterion feedback events
+ * - `swarm-patterns` - Decomposition patterns and anti-patterns
+ * - `swarm-maturity` - Pattern maturity tracking
+ *
+ * @example
+ * ```typescript
+ * // Use default semantic-memory storage
+ * const storage = createStorage();
+ *
+ * // Or configure explicitly
+ * const storage = createStorage({
+ *   backend: "semantic-memory",
+ *   collections: {
+ *     feedback: "my-feedback",
+ *     patterns: "my-patterns",
+ *     maturity: "my-maturity",
+ *   },
+ * });
+ *
+ * // Or use in-memory for testing
+ * const storage = createStorage({ backend: "memory" });
+ * ```
+ */
+import type { FeedbackEvent } from "./learning";
+import type { DecompositionPattern } from "./anti-patterns";
+import type { PatternMaturity, MaturityFeedback } from "./pattern-maturity";
+/**
+ * Reset the cached command (for testing)
+ */
+export declare function resetCommandCache(): void;
+/**
+ * Storage backend type
+ */
+export type StorageBackend = "semantic-memory" | "memory";
+/**
+ * Collection names for semantic-memory
+ */
+export interface StorageCollections {
+    feedback: string;
+    patterns: string;
+    maturity: string;
+}
+/**
+ * Storage configuration
+ */
+export interface StorageConfig {
+    /** Backend to use (default: "semantic-memory") */
+    backend: StorageBackend;
+    /** Collection names for semantic-memory backend */
+    collections: StorageCollections;
+    /** Whether to use semantic search for queries (default: true) */
+    useSemanticSearch: boolean;
+}
+/**
+ * Generate unique test collection name
+ *
+ * Creates a timestamp-based suffix for test collections to ensure complete isolation.
+ * Each test run gets its own collections that don't pollute production semantic-memory.
+ *
+ * @returns Unique suffix like "test-1734567890123"
+ *
+ * @example
+ * ```typescript
+ * // In test setup:
+ * process.env.TEST_SEMANTIC_MEMORY_COLLECTION = getTestCollectionName();
+ * // Results in collections like: swarm-feedback-test-1734567890123
+ * ```
+ */
+export declare function getTestCollectionName(): string;
+/**
+ * Get default storage configuration
+ *
+ * Returns a fresh config object on each call to ensure env vars (like
+ * TEST_SEMANTIC_MEMORY_COLLECTION) are read at runtime, not module load time.
+ *
+ * @returns Default storage configuration
+ */
+export declare function getDefaultStorageConfig(): StorageConfig;
+/**
+ * @deprecated Use getDefaultStorageConfig() instead. This static export
+ * captures collections at module load time, breaking test isolation.
+ */
+export declare const DEFAULT_STORAGE_CONFIG: StorageConfig;
+/**
+ * Unified storage interface for all learning data
+ */
+export interface LearningStorage {
+    storeFeedback(event: FeedbackEvent): Promise<void>;
+    getFeedbackByCriterion(criterion: string): Promise<FeedbackEvent[]>;
+    getFeedbackByBead(beadId: string): Promise<FeedbackEvent[]>;
+    getAllFeedback(): Promise<FeedbackEvent[]>;
+    findSimilarFeedback(query: string, limit?: number): Promise<FeedbackEvent[]>;
+    storePattern(pattern: DecompositionPattern): Promise<void>;
+    getPattern(id: string): Promise<DecompositionPattern | null>;
+    getAllPatterns(): Promise<DecompositionPattern[]>;
+    getAntiPatterns(): Promise<DecompositionPattern[]>;
+    getPatternsByTag(tag: string): Promise<DecompositionPattern[]>;
+    findSimilarPatterns(query: string, limit?: number): Promise<DecompositionPattern[]>;
+    storeMaturity(maturity: PatternMaturity): Promise<void>;
+    getMaturity(patternId: string): Promise<PatternMaturity | null>;
+    getAllMaturity(): Promise<PatternMaturity[]>;
+    getMaturityByState(state: string): Promise<PatternMaturity[]>;
+    storeMaturityFeedback(feedback: MaturityFeedback): Promise<void>;
+    getMaturityFeedback(patternId: string): Promise<MaturityFeedback[]>;
+    close(): Promise<void>;
+}
+interface SessionStats {
+    storesCount: number;
+    queriesCount: number;
+    sessionStart: number;
+    lastAlertCheck: number;
+}
+/**
+ * Reset session stats (for testing)
+ */
+export declare function resetSessionStats(): void;
+/**
+ * Get current session stats
+ */
+export declare function getSessionStats(): Readonly<SessionStats>;
+/**
+ * Semantic-memory backed storage
+ *
+ * Uses the semantic-memory CLI for persistence with semantic search.
+ * Data survives across sessions and can be searched by meaning.
+ */
+export declare class SemanticMemoryStorage implements LearningStorage {
+    private config;
+    constructor(config?: Partial<StorageConfig>);
+    /**
+     * Check if low usage alert should be sent
+     *
+     * Sends alert via agentmail if:
+     * - More than 10 minutes have elapsed since session start
+     * - Less than 1 store operation has occurred
+     * - Alert hasn't been sent in the last 10 minutes
+     */
+    private checkLowUsageAlert;
+    private store;
+    private find;
+    private list;
+    storeFeedback(event: FeedbackEvent): Promise<void>;
+    getFeedbackByCriterion(criterion: string): Promise<FeedbackEvent[]>;
+    getFeedbackByBead(beadId: string): Promise<FeedbackEvent[]>;
+    getAllFeedback(): Promise<FeedbackEvent[]>;
+    findSimilarFeedback(query: string, limit?: number): Promise<FeedbackEvent[]>;
+    storePattern(pattern: DecompositionPattern): Promise<void>;
+    getPattern(id: string): Promise<DecompositionPattern | null>;
+    getAllPatterns(): Promise<DecompositionPattern[]>;
+    getAntiPatterns(): Promise<DecompositionPattern[]>;
+    getPatternsByTag(tag: string): Promise<DecompositionPattern[]>;
+    findSimilarPatterns(query: string, limit?: number): Promise<DecompositionPattern[]>;
+    storeMaturity(maturity: PatternMaturity): Promise<void>;
+    getMaturity(patternId: string): Promise<PatternMaturity | null>;
+    getAllMaturity(): Promise<PatternMaturity[]>;
+    getMaturityByState(state: string): Promise<PatternMaturity[]>;
+    storeMaturityFeedback(feedback: MaturityFeedback): Promise<void>;
+    getMaturityFeedback(patternId: string): Promise<MaturityFeedback[]>;
+    close(): Promise<void>;
+}
+/**
+ * In-memory storage adapter
+ *
+ * Wraps the existing in-memory implementations into the unified interface.
+ * Useful for testing and ephemeral sessions.
+ */
+export declare class InMemoryStorage implements LearningStorage {
+    private feedback;
+    private patterns;
+    private maturity;
+    constructor();
+    storeFeedback(event: FeedbackEvent): Promise<void>;
+    getFeedbackByCriterion(criterion: string): Promise<FeedbackEvent[]>;
+    getFeedbackByBead(beadId: string): Promise<FeedbackEvent[]>;
+    getAllFeedback(): Promise<FeedbackEvent[]>;
+    findSimilarFeedback(query: string, limit?: number): Promise<FeedbackEvent[]>;
+    storePattern(pattern: DecompositionPattern): Promise<void>;
+    getPattern(id: string): Promise<DecompositionPattern | null>;
+    getAllPatterns(): Promise<DecompositionPattern[]>;
+    getAntiPatterns(): Promise<DecompositionPattern[]>;
+    getPatternsByTag(tag: string): Promise<DecompositionPattern[]>;
+    findSimilarPatterns(query: string, limit?: number): Promise<DecompositionPattern[]>;
+    storeMaturity(maturity: PatternMaturity): Promise<void>;
+    getMaturity(patternId: string): Promise<PatternMaturity | null>;
+    getAllMaturity(): Promise<PatternMaturity[]>;
+    getMaturityByState(state: string): Promise<PatternMaturity[]>;
+    storeMaturityFeedback(feedback: MaturityFeedback): Promise<void>;
+    getMaturityFeedback(patternId: string): Promise<MaturityFeedback[]>;
+    close(): Promise<void>;
+}
+/**
+ * Create a storage instance
+ *
+ * @param config - Storage configuration (default: semantic-memory)
+ * @returns Configured storage instance
+ *
+ * @example
+ * ```typescript
+ * // Default semantic-memory storage
+ * const storage = createStorage();
+ *
+ * // In-memory for testing
+ * const storage = createStorage({ backend: "memory" });
+ *
+ * // Custom collections
+ * const storage = createStorage({
+ *   backend: "semantic-memory",
+ *   collections: {
+ *     feedback: "my-project-feedback",
+ *     patterns: "my-project-patterns",
+ *     maturity: "my-project-maturity",
+ *   },
+ * });
+ * ```
+ */
+export declare function createStorage(config?: Partial<StorageConfig>): LearningStorage;
+/**
+ * Check if semantic-memory is available (native or via bunx)
+ */
+export declare function isSemanticMemoryAvailable(): Promise<boolean>;
+/**
+ * Get the resolved semantic-memory command (for debugging/logging)
+ */
+export declare function getResolvedCommand(): Promise<string[]>;
+/**
+ * Create storage with automatic fallback
+ *
+ * Uses semantic-memory if available, otherwise falls back to in-memory.
+ *
+ * @param config - Storage configuration
+ * @returns Storage instance
+ */
+export declare function createStorageWithFallback(config?: Partial<StorageConfig>): Promise<LearningStorage>;
+/**
+ * Get or create the global storage instance
+ *
+ * Uses semantic-memory by default, with automatic fallback to in-memory.
+ * Prevents race conditions by storing the initialization promise.
+ */
+export declare function getStorage(): Promise<LearningStorage>;
+/**
+ * Set the global storage instance
+ *
+ * Useful for testing or custom configurations.
+ */
+export declare function setStorage(storage: LearningStorage): void;
+/**
+ * Reset the global storage instance
+ */
+export declare function resetStorage(): Promise<void>;
+export {};
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"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"}

package/dist/structured.d.ts

@@ -0,0 +1,196 @@
+import { z, type ZodSchema } from "zod";
+/**
+ * Structured validation error with formatted feedback
+ *
+ * Contains both raw Zod errors for programmatic access and
+ * pre-formatted error bullets suitable for retry prompts.
+ */
+export declare class StructuredValidationError extends Error {
+    readonly zodError: z.ZodError | null;
+    readonly rawInput: string;
+    readonly extractionMethod?: string | undefined;
+    readonly errorBullets: string[];
+    constructor(message: string, zodError: z.ZodError | null, rawInput: string, extractionMethod?: string | undefined);
+    /**
+     * Format errors as bullet list for retry prompts
+     */
+    toFeedback(): string;
+}
+/**
+ * Error when JSON cannot be extracted from text
+ */
+export declare class JsonExtractionError extends Error {
+    readonly rawInput: string;
+    readonly attemptedStrategies: string[];
+    constructor(message: string, rawInput: string, attemptedStrategies: string[]);
+}
+/**
+ * Format Zod validation errors as readable bullet points
+ *
+ * @param error - Zod error from schema validation
+ * @returns Array of error messages suitable for feedback
+ */
+declare function formatZodErrors(error: z.ZodError): string[];
+/**
+ * Get schema by name from registry
+ */
+declare function getSchemaByName(name: string): ZodSchema;
+/**
+ * Extract JSON from text using multiple strategies.
+ *
+ * Strategies tried in priority order:
+ * 1. Direct parse - fastest, works for clean JSON
+ * 2. JSON code block - common in markdown responses
+ * 3. Generic code block - fallback for unlabeled blocks
+ * 4. First brace match - finds outermost {...}
+ * 5. Last brace match - handles trailing content
+ * 6. Repair attempt - fixes common issues (quotes, trailing commas)
+ *
+ * @param text Raw text potentially containing JSON
+ * @returns Parsed JSON object or null if all strategies fail
+ */
+declare function extractJsonFromText(text: string): [unknown, string];
+/**
+ * Extract JSON from markdown/text response
+ *
+ * Tries multiple extraction strategies in order:
+ * 1. Direct JSON parse
+ * 2. ```json code blocks
+ * 3. Any code blocks
+ * 4. Brace matching for objects
+ * 5. Bracket matching for arrays
+ * 6. JSON repair attempts
+ */
+export declare const structured_extract_json: {
+    description: string;
+    args: {
+        text: z.ZodString;
+    };
+    execute(args: {
+        text: string;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+};
+/**
+ * Validate agent response against a named schema
+ *
+ * Extracts JSON from the response using multiple strategies,
+ * then validates against the specified schema.
+ */
+export declare const structured_validate: {
+    description: string;
+    args: {
+        response: z.ZodString;
+        schema_name: z.ZodEnum<{
+            evaluation: "evaluation";
+            task_decomposition: "task_decomposition";
+            bead_tree: "bead_tree";
+        }>;
+        max_retries: z.ZodOptional<z.ZodNumber>;
+    };
+    execute(args: {
+        response: string;
+        schema_name: "evaluation" | "task_decomposition" | "bead_tree";
+        max_retries?: number | undefined;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+};
+/**
+ * Parse and validate evaluation response from an agent
+ *
+ * Specialized tool for parsing self-evaluations. Returns
+ * the validated Evaluation or structured errors.
+ */
+export declare const structured_parse_evaluation: {
+    description: string;
+    args: {
+        response: z.ZodString;
+    };
+    execute(args: {
+        response: string;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+};
+/**
+ * Parse and validate task decomposition response
+ *
+ * Specialized tool for parsing decomposition results.
+ * Validates the structure and returns file lists for reservations.
+ */
+export declare const structured_parse_decomposition: {
+    description: string;
+    args: {
+        response: z.ZodString;
+    };
+    execute(args: {
+        response: string;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+};
+/**
+ * Parse and validate a bead tree (epic with subtasks)
+ *
+ * Validates the structure before creating beads.
+ */
+export declare const structured_parse_bead_tree: {
+    description: string;
+    args: {
+        response: z.ZodString;
+    };
+    execute(args: {
+        response: string;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+};
+export { extractJsonFromText, formatZodErrors, getSchemaByName };
+export declare const structuredTools: {
+    structured_extract_json: {
+        description: string;
+        args: {
+            text: z.ZodString;
+        };
+        execute(args: {
+            text: string;
+        }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+    };
+    structured_validate: {
+        description: string;
+        args: {
+            response: z.ZodString;
+            schema_name: z.ZodEnum<{
+                evaluation: "evaluation";
+                task_decomposition: "task_decomposition";
+                bead_tree: "bead_tree";
+            }>;
+            max_retries: z.ZodOptional<z.ZodNumber>;
+        };
+        execute(args: {
+            response: string;
+            schema_name: "evaluation" | "task_decomposition" | "bead_tree";
+            max_retries?: number | undefined;
+        }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+    };
+    structured_parse_evaluation: {
+        description: string;
+        args: {
+            response: z.ZodString;
+        };
+        execute(args: {
+            response: string;
+        }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+    };
+    structured_parse_decomposition: {
+        description: string;
+        args: {
+            response: z.ZodString;
+        };
+        execute(args: {
+            response: string;
+        }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+    };
+    structured_parse_bead_tree: {
+        description: string;
+        args: {
+            response: z.ZodString;
+        };
+        execute(args: {
+            response: string;
+        }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+    };
+};
+//# sourceMappingURL=structured.d.ts.map

package/dist/structured.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured.d.ts","sourceRoot":"","sources":["../src/structured.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,CAAC,EAAE,KAAK,SAAS,EAAE,MAAM,KAAK,CAAC;AAiBxC;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;aAKhC,QAAQ,EAAE,CAAC,CAAC,QAAQ,GAAG,IAAI;aAC3B,QAAQ,EAAE,MAAM;aAChB,gBAAgB,CAAC,EAAE,MAAM;IAN3C,SAAgB,YAAY,EAAE,MAAM,EAAE,CAAC;gBAGrC,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,CAAC,CAAC,QAAQ,GAAG,IAAI,EAC3B,QAAQ,EAAE,MAAM,EAChB,gBAAgB,CAAC,EAAE,MAAM,YAAA;IAO3C;;OAEG;IACH,UAAU,IAAI,MAAM;CAGrB;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aAG1B,QAAQ,EAAE,MAAM;aAChB,mBAAmB,EAAE,MAAM,EAAE;gBAF7C,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,MAAM,EAChB,mBAAmB,EAAE,MAAM,EAAE;CAKhD;AAMD;;;;;GAKG;AACH,iBAAS,eAAe,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,MAAM,EAAE,CAKpD;AAWD;;GAEG;AACH,iBAAS,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAQhD;AAED;;;;;;;;;;;;;GAaG;AACH,iBAAS,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAwE5D;AAwHD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;CAkClC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;CAkF9B,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;CA4EtC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B;;;;;;;;CAoGzC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;CAkFrC,CAAC;AAMH,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,eAAe,EAAE,CAAC;AAMjE,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAM3B,CAAC"}

package/dist/swarm-decompose.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Swarm Decompose Module - Task decomposition and validation
+ *
+ * Handles breaking tasks into parallelizable subtasks with file assignments,
+ * validates decomposition structure, and detects conflicts.
+ *
+ * Key responsibilities:
+ * - Decomposition prompt generation
+ * - BeadTree validation
+ * - File conflict detection
+ * - Instruction conflict detection
+ * - Delegation to planner subagents
+ */
+import { z } from "zod";
+/**
+ * A detected conflict between subtask instructions
+ */
+export interface InstructionConflict {
+    subtask_a: number;
+    subtask_b: number;
+    directive_a: string;
+    directive_b: string;
+    conflict_type: "positive_negative" | "contradictory";
+    description: string;
+}
+/**
+ * Detect conflicts between subtask instructions
+ *
+ * Looks for cases where one subtask says "always use X" and another says "avoid X".
+ *
+ * @param subtasks - Array of subtask descriptions
+ * @returns Array of detected conflicts
+ *
+ * @see https://github.com/Dicklesworthstone/cass_memory_system/blob/main/src/curate.ts#L36-L89
+ */
+export declare function detectInstructionConflicts(subtasks: Array<{
+    title: string;
+    description?: string;
+}>): InstructionConflict[];
+/**
+ * Detect file conflicts in a bead tree
+ *
+ * @param subtasks - Array of subtasks with file assignments
+ * @returns Array of files that appear in multiple subtasks
+ */
+export declare function detectFileConflicts(subtasks: Array<{
+    files: string[];
+}>): string[];
+/**
+ * Decompose a task into a bead tree
+ *
+ * This is a PROMPT tool - it returns a prompt for the agent to respond to.
+ * The agent's response (JSON) should be validated with BeadTreeSchema.
+ *
+ * Optionally queries CASS for similar past tasks to inform decomposition.
+ */
+export declare const swarm_decompose: {
+    description: string;
+    args: {
+        task: z.ZodString;
+        max_subtasks: z.ZodDefault<z.ZodNumber>;
+        context: z.ZodOptional<z.ZodString>;
+        query_cass: z.ZodOptional<z.ZodBoolean>;
+        cass_limit: z.ZodOptional<z.ZodNumber>;
+    };
+    execute(args: {
+        task: string;
+        max_subtasks: number;
+        context?: string | undefined;
+        query_cass?: boolean | undefined;
+        cass_limit?: number | undefined;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+};
+/**
+ * Validate a decomposition response from an agent
+ *
+ * Use this after the agent responds to swarm:decompose to validate the structure.
+ */
+export declare const swarm_validate_decomposition: {
+    description: string;
+    args: {
+        response: z.ZodString;
+    };
+    execute(args: {
+        response: string;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+};
+/**
+ * Delegate task decomposition to a swarm/planner subagent
+ *
+ * Returns a prompt for spawning a planner agent that will handle all decomposition
+ * reasoning. This keeps the coordinator context lean by offloading:
+ * - Strategy selection
+ * - CASS queries
+ * - Skills discovery
+ * - File analysis
+ * - BeadTree generation
+ *
+ * The planner returns ONLY structured BeadTree JSON, which the coordinator
+ * validates and uses to create beads.
+ *
+ * @example
+ * ```typescript
+ * // Coordinator workflow:
+ * const delegateResult = await swarm_delegate_planning({
+ *   task: "Add user authentication",
+ *   context: "Next.js 14 app",
+ * });
+ *
+ * // Parse the result
+ * const { prompt, subagent_type } = JSON.parse(delegateResult);
+ *
+ * // Spawn subagent using Task tool
+ * const plannerResponse = await Task(prompt, subagent_type);
+ *
+ * // Validate the response
+ * await swarm_validate_decomposition({ response: plannerResponse });
+ * ```
+ */
+export declare const swarm_delegate_planning: {
+    description: string;
+    args: {
+        task: z.ZodString;
+        context: z.ZodOptional<z.ZodString>;
+        max_subtasks: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        strategy: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+            "file-based": "file-based";
+            "feature-based": "feature-based";
+            "risk-based": "risk-based";
+            auto: "auto";
+        }>>>;
+        query_cass: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    };
+    execute(args: {
+        task: string;
+        max_subtasks: number;
+        strategy: "file-based" | "feature-based" | "risk-based" | "auto";
+        query_cass: boolean;
+        context?: string | undefined;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+};
+export declare class SwarmError extends Error {
+    readonly operation: string;
+    readonly details?: unknown | undefined;
+    constructor(message: string, operation: string, details?: unknown | undefined);
+}
+export declare class DecompositionError extends SwarmError {
+    readonly zodError?: z.ZodError | undefined;
+    constructor(message: string, zodError?: z.ZodError | undefined);
+}
+export declare const decomposeTools: {
+    swarm_decompose: {
+        description: string;
+        args: {
+            task: z.ZodString;
+            max_subtasks: z.ZodDefault<z.ZodNumber>;
+            context: z.ZodOptional<z.ZodString>;
+            query_cass: z.ZodOptional<z.ZodBoolean>;
+            cass_limit: z.ZodOptional<z.ZodNumber>;
+        };
+        execute(args: {
+            task: string;
+            max_subtasks: number;
+            context?: string | undefined;
+            query_cass?: boolean | undefined;
+            cass_limit?: number | undefined;
+        }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+    };
+    swarm_validate_decomposition: {
+        description: string;
+        args: {
+            response: z.ZodString;
+        };
+        execute(args: {
+            response: string;
+        }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+    };
+    swarm_delegate_planning: {
+        description: string;
+        args: {
+            task: z.ZodString;
+            context: z.ZodOptional<z.ZodString>;
+            max_subtasks: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+            strategy: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+                "file-based": "file-based";
+                "feature-based": "feature-based";
+                "risk-based": "risk-based";
+                auto: "auto";
+            }>>>;
+            query_cass: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        };
+        execute(args: {
+            task: string;
+            max_subtasks: number;
+            strategy: "file-based" | "feature-based" | "risk-based" | "auto";
+            query_cass: boolean;
+            context?: string | undefined;
+        }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+    };
+};
+//# sourceMappingURL=swarm-decompose.d.ts.map

package/dist/swarm-decompose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swarm-decompose.d.ts","sourceRoot":"","sources":["../src/swarm-decompose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAwJxB;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,mBAAmB,GAAG,eAAe,CAAC;IACrD,WAAW,EAAE,MAAM,CAAC;CACrB;AA8CD;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GACvD,mBAAmB,EAAE,CAmDvB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,GACnC,MAAM,EAAE,CAgBV;AA+GD;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;CA0G1B,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;CAkHvC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;CA6LlC,CAAC;AAMH,qBAAa,UAAW,SAAQ,KAAK;aAGjB,SAAS,EAAE,MAAM;aACjB,OAAO,CAAC,EAAE,OAAO;gBAFjC,OAAO,EAAE,MAAM,EACC,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,OAAO,YAAA;CAKpC;AAED,qBAAa,kBAAmB,SAAQ,UAAU;aAG9B,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ;gBADrC,OAAO,EAAE,MAAM,EACC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,YAAA;CAIxC;AAED,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAI1B,CAAC"}