opencode-swarm-plugin 0.32.0 → 0.33.0

package/dist/index.js

@@ -26558,7 +26558,7 @@ var init_skills = __esm(() => {
     "skills"
   ];
   skills_list = tool({
-    description: `List all available skills in the project.
+    description: `[DEPRECATED] List all available skills in the project.
 
 Skills are specialized instructions that help with specific domains or tasks.
 Use this tool to discover what skills are available, then use skills_use to
@@ -26569,6 +26569,7 @@ Returns skill names, descriptions, and whether they have executable scripts.`,
       tag: tool.schema.string().optional().describe("Optional tag to filter skills by")
     },
     async execute(args) {
+      console.warn("[DEPRECATED] skills_list is deprecated. OpenCode now provides native skills support. This tool will be removed in a future version.");
       const skills = await discoverSkills();
       let refs = Array.from(skills.values());
       if (args.tag) {
@@ -26591,7 +26592,7 @@ ${formatted}`;
     }
   });
   skills_use = tool({
-    description: `Activate a skill by loading its full instructions.
+    description: `[DEPRECATED] Activate a skill by loading its full instructions.
 
 After calling this tool, follow the skill's instructions for the current task.
 Skills provide domain-specific guidance and best practices.
@@ -26602,6 +26603,7 @@ If the skill has scripts, you can run them with skills_execute.`,
       include_scripts: tool.schema.boolean().optional().describe("Also list available scripts (default: true)")
     },
     async execute(args) {
+      console.warn("[DEPRECATED] skills_use is deprecated. OpenCode now provides native skills support. This tool will be removed in a future version.");
       const skill = await getSkill(args.name);
       if (!skill) {
         const available = await listSkills();
@@ -26634,7 +26636,7 @@ Run scripts with skills_execute tool.`;
     }
   });
   skills_execute = tool({
-    description: `Execute a script from a skill's scripts/ directory.
+    description: `[DEPRECATED] Execute a script from a skill's scripts/ directory.
 
 Some skills include helper scripts for common operations.
 Use skills_use first to see available scripts, then execute them here.
@@ -26646,6 +26648,7 @@ Scripts run in the skill's directory with the project directory as an argument.`
       args: tool.schema.array(tool.schema.string()).optional().describe("Additional arguments to pass to the script")
     },
     async execute(args, ctx) {
+      console.warn("[DEPRECATED] skills_execute is deprecated. OpenCode now provides native skills support. This tool will be removed in a future version.");
       const skill = await getSkill(args.skill);
       if (!skill) {
         return `Skill '${args.skill}' not found.`;
@@ -26691,7 +26694,7 @@ ${output}`;
     }
   });
   skills_read = tool({
-    description: `Read a resource file from a skill's directory.
+    description: `[DEPRECATED] Read a resource file from a skill's directory.
 
 Skills may include additional files like:
 - examples.md - Example usage
@@ -26704,6 +26707,7 @@ Use this to access supplementary skill resources.`,
       file: tool.schema.string().describe("Relative path to the file within the skill directory")
     },
     async execute(args) {
+      console.warn("[DEPRECATED] skills_read is deprecated. OpenCode now provides native skills support. This tool will be removed in a future version.");
       const skill = await getSkill(args.skill);
       if (!skill) {
         return `Skill '${args.skill}' not found.`;
@@ -35545,6 +35549,115 @@ Other cell operations:
 **Memory is the swarm's collective intelligence. Query it. Feed it.**
 
 Begin now.`;
+var RESEARCHER_PROMPT = `You are a swarm researcher gathering documentation for: **{research_id}**
+
+## [IDENTITY]
+Agent: (assigned at spawn)
+Research Task: {research_id}
+Epic: {epic_id}
+
+## [MISSION]
+Gather comprehensive documentation for the specified technologies to inform task decomposition.
+
+**COORDINATOR PROVIDED THESE TECHNOLOGIES TO RESEARCH:**
+{tech_stack}
+
+You do NOT discover what to research - the coordinator already decided that.
+You DO discover what TOOLS are available to fetch documentation.
+
+## [OUTPUT MODE]
+{check_upgrades}
+
+## [WORKFLOW]
+
+### Step 1: Initialize (MANDATORY FIRST)
+\`\`\`
+swarmmail_init(project_path="{project_path}", task_description="{research_id}: Documentation research")
+\`\`\`
+
+### Step 2: Discover Available Documentation Tools
+Check what's available for fetching docs:
+- **next-devtools**: \`nextjs_docs\` for Next.js documentation
+- **context7**: Library documentation lookup (\`use context7\` in prompts)
+- **fetch**: General web fetching for official docs sites
+- **pdf-brain**: Internal knowledge base search
+
+**Don't assume** - check which tools exist in your environment.
+
+### Step 3: Read Installed Versions
+For each technology in the tech stack:
+1. Check package.json (or equivalent) for installed version
+2. Record exact version numbers
+3. Note any version constraints (^, ~, etc.)
+
+### Step 4: Fetch Documentation
+For EACH technology in the list:
+- Use the most appropriate tool (Next.js → nextjs_docs, libraries → context7, others → fetch)
+- Fetch documentation for the INSTALLED version (not latest, unless --check-upgrades)
+- Focus on: API changes, breaking changes, migration guides, best practices
+- Extract key patterns, gotchas, and compatibility notes
+
+**If --check-upgrades mode:**
+- ALSO fetch docs for the LATEST version
+- Compare installed vs latest
+- Note breaking changes, new features, migration complexity
+
+### Step 5: Store Detailed Findings
+For EACH technology, store in semantic-memory:
+\`\`\`
+semantic-memory_store(
+  information="<technology-name> <version>: <key patterns, gotchas, API changes, compatibility notes>",
+  tags="research, <tech-name>, documentation, {epic_id}"
+)
+\`\`\`
+
+**Why store individually?** Future agents can search by technology name.
+
+### Step 6: Broadcast Summary
+Send condensed findings to coordinator:
+\`\`\`
+swarmmail_send(
+  to=["coordinator"],
+  subject="Research Complete: {research_id}",
+  body="<brief summary - see semantic-memory for details>",
+  thread_id="{epic_id}"
+)
+\`\`\`
+
+### Step 7: Return Structured Output
+Output JSON with:
+\`\`\`json
+{
+  "technologies": [
+    {
+      "name": "string",
+      "installed_version": "string",
+      "latest_version": "string | null",  // Only if --check-upgrades
+      "key_patterns": ["string"],
+      "gotchas": ["string"],
+      "breaking_changes": ["string"],  // Only if --check-upgrades
+      "memory_id": "string"  // ID of semantic-memory entry
+    }
+  ],
+  "summary": "string"  // Condensed summary for shared_context
+}
+\`\`\`
+
+## [CRITICAL REQUIREMENTS]
+
+**NON-NEGOTIABLE:**
+1. Step 1 (swarmmail_init) MUST be first
+2. Research ONLY the technologies the coordinator specified
+3. Fetch docs for INSTALLED versions (unless --check-upgrades)
+4. Store detailed findings in semantic-memory (one per technology)
+5. Return condensed summary for coordinator (full details in memory)
+6. Use appropriate doc tools (nextjs_docs for Next.js, context7 for libraries, etc.)
+
+**Output goes TWO places:**
+- **semantic-memory**: Detailed findings (searchable by future agents)
+- **Return JSON**: Condensed summary (for coordinator's shared_context)
+
+Begin research now.`;
 var COORDINATOR_POST_WORKER_CHECKLIST = `
 ## ⚠️ MANDATORY: Post-Worker Review (DO THIS IMMEDIATELY)
 
@@ -35633,6 +35746,12 @@ For each criterion, assess passed/failed and provide brief feedback:
 
 If any criterion fails, the overall evaluation fails and retry_suggestion 
 should describe what needs to be fixed.`;
+function formatResearcherPrompt(params) {
+  const techList = params.tech_stack.map((t) => `- ${t}`).join(`
+`);
+  const upgradesMode = params.check_upgrades ? "**UPGRADE COMPARISON MODE**: Fetch docs for BOTH installed AND latest versions. Compare and note breaking changes." : "**DEFAULT MODE**: Fetch docs for INSTALLED versions only (from lockfiles).";
+  return RESEARCHER_PROMPT.replace(/{research_id}/g, params.research_id).replace(/{epic_id}/g, params.epic_id).replace("{tech_stack}", techList).replace("{project_path}", params.project_path).replace("{check_upgrades}", upgradesMode);
+}
 function formatSubtaskPromptV2(params) {
   const fileList = params.files.length > 0 ? params.files.map((f) => `- \`${f}\``).join(`
 `) : "(no specific files - use judgment)";
@@ -35782,6 +35901,48 @@ var swarm_spawn_subtask = tool({
     }, null, 2);
   }
 });
+var swarm_spawn_researcher = tool({
+  description: "Prepare a research task for spawning. Returns prompt for gathering technology documentation. Researcher fetches docs and stores findings in semantic-memory.",
+  args: {
+    research_id: tool.schema.string().describe("Unique ID for this research task"),
+    epic_id: tool.schema.string().describe("Parent epic ID"),
+    tech_stack: tool.schema.array(tool.schema.string()).describe("Explicit list of technologies to research (from coordinator)"),
+    project_path: tool.schema.string().describe("Absolute project path for swarmmail_init"),
+    check_upgrades: tool.schema.boolean().optional().describe("If true, compare installed vs latest versions (default: false)")
+  },
+  async execute(args) {
+    const prompt = formatResearcherPrompt({
+      research_id: args.research_id,
+      epic_id: args.epic_id,
+      tech_stack: args.tech_stack,
+      project_path: args.project_path,
+      check_upgrades: args.check_upgrades ?? false
+    });
+    return JSON.stringify({
+      prompt,
+      research_id: args.research_id,
+      epic_id: args.epic_id,
+      tech_stack: args.tech_stack,
+      project_path: args.project_path,
+      check_upgrades: args.check_upgrades ?? false,
+      subagent_type: "swarm/researcher",
+      expected_output: {
+        technologies: [
+          {
+            name: "string",
+            installed_version: "string",
+            latest_version: "string | null",
+            key_patterns: ["string"],
+            gotchas: ["string"],
+            breaking_changes: ["string"],
+            memory_id: "string"
+          }
+        ],
+        summary: "string"
+      }
+    }, null, 2);
+  }
+});
 var swarm_evaluation_prompt = tool({
   description: "Generate self-evaluation prompt for a completed subtask",
   args: {
@@ -35893,6 +36054,7 @@ ${args.context}` : `## Additional Context
 var promptTools = {
   swarm_subtask_prompt,
   swarm_spawn_subtask,
+  swarm_spawn_researcher,
   swarm_evaluation_prompt,
   swarm_plan_prompt
 };
@@ -50706,6 +50868,368 @@ var memoryTools = {
   "semantic-memory_check": semantic_memory_check
 };
 
+// src/observability-tools.ts
+init_dist();
+import {
+  agentActivity,
+  checkpointFrequency,
+  failedDecompositions,
+  getSwarmMailLibSQL as getSwarmMailLibSQL4,
+  humanFeedback,
+  lockContention,
+  messageLatency,
+  recoverySuccess,
+  scopeViolations,
+  strategySuccessRates,
+  taskDuration
+} from "swarm-mail";
+function parseSince(since) {
+  const now = Date.now();
+  const match11 = since.match(/^(\d+)([dhm])$/);
+  if (!match11) {
+    throw new Error(`Invalid since format: ${since}. Use "7d", "24h", or "1h"`);
+  }
+  const [, value, unit] = match11;
+  const num = Number.parseInt(value, 10);
+  switch (unit) {
+    case "d":
+      return now - num * 24 * 60 * 60 * 1000;
+    case "h":
+      return now - num * 60 * 60 * 1000;
+    case "m":
+      return now - num * 60 * 1000;
+    default:
+      throw new Error(`Unknown unit: ${unit}`);
+  }
+}
+async function executeQuery(swarmMail, query) {
+  const db = await swarmMail.getDatabase();
+  const result = await db.query(query.sql, Object.values(query.parameters || {}));
+  return result.rows;
+}
+function formatSummary(queryType, results) {
+  if (results.length === 0) {
+    return `No ${queryType} data found.`;
+  }
+  const count = results.length;
+  const preview = results.slice(0, 3);
+  return `${queryType}: ${count} result(s). Top 3: ${JSON.stringify(preview, null, 2).slice(0, 400)}`;
+}
+function capResults(results) {
+  return results.slice(0, 50);
+}
+var swarm_analytics = tool({
+  description: "Query pre-built analytics for swarm coordination. Returns structured data about failed decompositions, strategy success rates, lock contention, agent activity, message latency, scope violations, task duration, checkpoint frequency, recovery success, and human feedback.",
+  args: {
+    query: tool.schema.enum([
+      "failed-decompositions",
+      "strategy-success-rates",
+      "lock-contention",
+      "agent-activity",
+      "message-latency",
+      "scope-violations",
+      "task-duration",
+      "checkpoint-frequency",
+      "recovery-success",
+      "human-feedback"
+    ]).describe("Type of analytics query to run"),
+    since: tool.schema.string().optional().describe("Time filter: '7d', '24h', '1h' (optional)"),
+    format: tool.schema.enum(["json", "summary"]).optional().describe("Output format: 'json' (default) or 'summary' (context-efficient)")
+  },
+  async execute(args2) {
+    try {
+      const projectPath = process.cwd();
+      const db = await getSwarmMailLibSQL4(projectPath);
+      const filters = {
+        project_key: projectPath
+      };
+      if (args2.since) {
+        filters.since = parseSince(args2.since);
+      }
+      let query;
+      switch (args2.query) {
+        case "failed-decompositions":
+          query = failedDecompositions(filters);
+          break;
+        case "strategy-success-rates":
+          query = strategySuccessRates(filters);
+          break;
+        case "lock-contention":
+          query = lockContention(filters);
+          break;
+        case "agent-activity":
+          query = agentActivity(filters);
+          break;
+        case "message-latency":
+          query = messageLatency(filters);
+          break;
+        case "scope-violations":
+          query = scopeViolations.buildQuery ? scopeViolations.buildQuery(filters) : scopeViolations;
+          break;
+        case "task-duration":
+          query = taskDuration.buildQuery ? taskDuration.buildQuery(filters) : taskDuration;
+          break;
+        case "checkpoint-frequency":
+          query = checkpointFrequency.buildQuery ? checkpointFrequency.buildQuery(filters) : checkpointFrequency;
+          break;
+        case "recovery-success":
+          query = recoverySuccess.buildQuery ? recoverySuccess.buildQuery(filters) : recoverySuccess;
+          break;
+        case "human-feedback":
+          query = humanFeedback.buildQuery ? humanFeedback.buildQuery(filters) : humanFeedback;
+          break;
+        default:
+          return JSON.stringify({
+            error: `Unknown query type: ${args2.query}`
+          });
+      }
+      const results = await executeQuery(db, query);
+      if (args2.format === "summary") {
+        return formatSummary(args2.query, results);
+      }
+      return JSON.stringify({
+        query: args2.query,
+        filters,
+        count: results.length,
+        results
+      }, null, 2);
+    } catch (error45) {
+      return JSON.stringify({
+        error: error45 instanceof Error ? error45.message : String(error45)
+      });
+    }
+  }
+});
+var swarm_query = tool({
+  description: "Execute raw SQL queries against the swarm event store. Context-safe: results capped at 50 rows. Useful for custom analytics and debugging.",
+  args: {
+    sql: tool.schema.string().describe("SQL query to execute (SELECT only for safety)"),
+    format: tool.schema.enum(["json", "table"]).optional().describe("Output format: 'json' (default) or 'table' (visual)")
+  },
+  async execute(args2) {
+    try {
+      const projectPath = process.cwd();
+      const swarmMail = await getSwarmMailLibSQL4(projectPath);
+      const db = await swarmMail.getDatabase();
+      if (!args2.sql.trim().toLowerCase().startsWith("select")) {
+        return JSON.stringify({
+          error: "Only SELECT queries are allowed for safety"
+        });
+      }
+      const result = await db.query(args2.sql, []);
+      const rows = result.rows;
+      const cappedRows = capResults(rows);
+      if (args2.format === "table") {
+        if (cappedRows.length === 0) {
+          return "No results";
+        }
+        const headers = Object.keys(cappedRows[0]);
+        const headerRow = headers.join(" | ");
+        const separator = headers.map(() => "---").join(" | ");
+        const dataRows = cappedRows.map((row) => headers.map((h) => row[h]).join(" | "));
+        return [headerRow, separator, ...dataRows].join(`
+`);
+      }
+      return JSON.stringify({
+        count: cappedRows.length,
+        total: rows.length,
+        capped: rows.length > 50,
+        results: cappedRows
+      }, null, 2);
+    } catch (error45) {
+      return JSON.stringify({
+        error: error45 instanceof Error ? error45.message : String(error45)
+      });
+    }
+  }
+});
+var swarm_diagnose = tool({
+  description: "Auto-diagnose issues for a specific epic or task. Returns structured diagnosis with blockers, conflicts, slow tasks, errors, and timeline.",
+  args: {
+    epic_id: tool.schema.string().optional().describe("Epic ID to diagnose"),
+    bead_id: tool.schema.string().optional().describe("Task ID to diagnose"),
+    include: tool.schema.array(tool.schema.enum([
+      "blockers",
+      "conflicts",
+      "slow_tasks",
+      "errors",
+      "timeline"
+    ])).optional().describe("What to include in diagnosis (default: all)")
+  },
+  async execute(args2) {
+    try {
+      const projectPath = process.cwd();
+      const swarmMail = await getSwarmMailLibSQL4(projectPath);
+      const db = await swarmMail.getDatabase();
+      const diagnosis = [];
+      const include = args2.include || [
+        "blockers",
+        "conflicts",
+        "slow_tasks",
+        "errors",
+        "timeline"
+      ];
+      if (include.includes("blockers")) {
+        const blockerQuery = `
+					SELECT json_extract(data, '$.agent_name') as agent,
+					       json_extract(data, '$.bead_id') as bead_id,
+					       timestamp
+					FROM events
+					WHERE type = 'task_blocked'
+					${args2.epic_id ? "AND json_extract(data, '$.epic_id') = ?" : ""}
+					${args2.bead_id ? "AND json_extract(data, '$.bead_id') = ?" : ""}
+					ORDER BY timestamp DESC
+					LIMIT 10
+				`;
+        const params = [];
+        if (args2.epic_id)
+          params.push(args2.epic_id);
+        if (args2.bead_id)
+          params.push(args2.bead_id);
+        const blockers = await db.query(blockerQuery, params);
+        if (blockers.rows.length > 0) {
+          diagnosis.push({
+            type: "blockers",
+            message: `Found ${blockers.rows.length} blocked task(s)`,
+            severity: "high"
+          });
+        }
+      }
+      if (include.includes("errors")) {
+        const errorQuery = `
+					SELECT type, json_extract(data, '$.error_count') as error_count
+					FROM events
+					WHERE type = 'subtask_outcome'
+					AND json_extract(data, '$.success') = 'false'
+					${args2.epic_id ? "AND json_extract(data, '$.epic_id') = ?" : ""}
+					${args2.bead_id ? "AND json_extract(data, '$.bead_id') = ?" : ""}
+					LIMIT 10
+				`;
+        const params = [];
+        if (args2.epic_id)
+          params.push(args2.epic_id);
+        if (args2.bead_id)
+          params.push(args2.bead_id);
+        const errors3 = await db.query(errorQuery, params);
+        if (errors3.rows.length > 0) {
+          diagnosis.push({
+            type: "errors",
+            message: `Found ${errors3.rows.length} failed task(s)`,
+            severity: "high"
+          });
+        }
+      }
+      let timeline = [];
+      if (include.includes("timeline")) {
+        const timelineQuery = `
+					SELECT timestamp, type, json_extract(data, '$.agent_name') as agent
+					FROM events
+					${args2.epic_id ? "WHERE json_extract(data, '$.epic_id') = ?" : ""}
+					${args2.bead_id ? (args2.epic_id ? "AND" : "WHERE") + " json_extract(data, '$.bead_id') = ?" : ""}
+					ORDER BY timestamp DESC
+					LIMIT 20
+				`;
+        const params = [];
+        if (args2.epic_id)
+          params.push(args2.epic_id);
+        if (args2.bead_id)
+          params.push(args2.bead_id);
+        const events = await db.query(timelineQuery, params);
+        timeline = events.rows;
+      }
+      return JSON.stringify({
+        epic_id: args2.epic_id,
+        bead_id: args2.bead_id,
+        diagnosis,
+        timeline: include.includes("timeline") ? timeline : undefined
+      }, null, 2);
+    } catch (error45) {
+      return JSON.stringify({
+        error: error45 instanceof Error ? error45.message : String(error45)
+      });
+    }
+  }
+});
+var swarm_insights = tool({
+  description: "Generate learning insights from swarm coordination metrics. Analyzes success rates, duration, conflicts, and retries to provide actionable recommendations.",
+  args: {
+    scope: tool.schema.enum(["epic", "project", "recent"]).describe("Scope of analysis: 'epic', 'project', or 'recent'"),
+    epic_id: tool.schema.string().optional().describe("Epic ID (required if scope='epic')"),
+    metrics: tool.schema.array(tool.schema.enum([
+      "success_rate",
+      "avg_duration",
+      "conflict_rate",
+      "retry_rate"
+    ])).describe("Metrics to analyze")
+  },
+  async execute(args2) {
+    try {
+      if (args2.scope === "epic" && !args2.epic_id) {
+        return JSON.stringify({
+          error: "epic_id is required when scope='epic'"
+        });
+      }
+      const projectPath = process.cwd();
+      const swarmMail = await getSwarmMailLibSQL4(projectPath);
+      const db = await swarmMail.getDatabase();
+      const insights = [];
+      if (args2.metrics.includes("success_rate")) {
+        const query = `
+					SELECT
+						SUM(CASE WHEN json_extract(data, '$.success') = 'true' THEN 1 ELSE 0 END) as successes,
+						COUNT(*) as total
+					FROM events
+					WHERE type = 'subtask_outcome'
+					${args2.epic_id ? "AND json_extract(data, '$.epic_id') = ?" : ""}
+				`;
+        const result = await db.query(query, args2.epic_id ? [args2.epic_id] : []);
+        const row = result.rows[0];
+        if (row && row.total > 0) {
+          const rate = row.successes / row.total * 100;
+          insights.push({
+            metric: "success_rate",
+            value: `${rate.toFixed(1)}%`,
+            insight: rate < 50 ? "Low success rate - review decomposition strategy" : rate < 80 ? "Moderate success rate - monitor for patterns" : "Good success rate - maintain current approach"
+          });
+        }
+      }
+      if (args2.metrics.includes("avg_duration")) {
+        const query = `
+					SELECT AVG(CAST(json_extract(data, '$.duration_ms') AS REAL)) as avg_duration
+					FROM events
+					WHERE type = 'subtask_outcome'
+					${args2.epic_id ? "AND json_extract(data, '$.epic_id') = ?" : ""}
+				`;
+        const result = await db.query(query, args2.epic_id ? [args2.epic_id] : []);
+        const row = result.rows[0];
+        if (row?.avg_duration) {
+          const avgMinutes = (row.avg_duration / 60000).toFixed(1);
+          insights.push({
+            metric: "avg_duration",
+            value: `${avgMinutes} min`,
+            insight: row.avg_duration > 600000 ? "Tasks taking >10min - consider smaller decomposition" : "Task duration is reasonable"
+          });
+        }
+      }
+      return JSON.stringify({
+        scope: args2.scope,
+        epic_id: args2.epic_id,
+        insights
+      }, null, 2);
+    } catch (error45) {
+      return JSON.stringify({
+        error: error45 instanceof Error ? error45.message : String(error45)
+      });
+    }
+  }
+});
+var observabilityTools = {
+  swarm_analytics,
+  swarm_query,
+  swarm_diagnose,
+  swarm_insights
+};
+
 // src/output-guardrails.ts
 var DEFAULT_GUARDRAIL_CONFIG = {
   defaultMaxChars: 32000,
@@ -51647,7 +52171,8 @@ var SwarmPlugin = async (input) => {
       ...repoCrawlTools,
       ...skillsTools,
       ...mandateTools,
-      ...memoryTools
+      ...memoryTools,
+      ...observabilityTools
     },
     event: async ({ event }) => {
       if (event.type === "session.idle") {