opencode-swarm-plugin 0.42.9 → 0.44.0

package/evals/fixtures/cass-baseline.ts

@@ -0,0 +1,217 @@
+/**
+ * CASS Baseline Response Fixtures
+ * 
+ * These fixtures capture the ACTUAL behavior of the CASS binary tools.
+ * DO NOT modify to match desired behavior - these document what the binary DOES.
+ * 
+ * Purpose: Characterization tests for ADR-010 (CASS inhousing).
+ * These ensure our inhouse implementation matches the binary's behavior.
+ */
+
+/**
+ * cass stats --json
+ * Captured: 2025-12-25
+ */
+export const cassStatsBaseline = {
+  by_agent: [
+    {
+      agent: "claude_code",
+      count: 137,
+    },
+    {
+      agent: "cursor",
+      count: 23,
+    },
+    {
+      agent: "codex",
+      count: 2,
+    },
+  ],
+  conversations: 162,
+  date_range: {
+    newest: "2025-12-08T04:20:36.526+00:00",
+    oldest: "2025-07-14T01:14:44.997+00:00",
+  },
+  db_path:
+    "/Users/joel/Library/Application Support/com.coding-agent-search.coding-agent-search/agent_search.db",
+  messages: 4213,
+  top_workspaces: [
+    {
+      count: 28,
+      workspace:
+        "/Users/joel/Code/vercel/academy-vectr-workflow-course-content/external/workflow-builder-starter",
+    },
+    {
+      count: 22,
+      workspace: "/Users/joel/Code/vercel/slack-agents-course",
+    },
+  ],
+} as const;
+
+/**
+ * cass search "swarm" --limit 2 --json
+ * Captured: 2025-12-25
+ */
+export const cassSearchBaseline = {
+  count: 2,
+  cursor: null,
+  hits: [
+    {
+      agent: "claude_code",
+      content:
+        'Fixed. The `plugins` key is invalid - OpenCode auto-loads plugins from directories instead.\n\n**Changes:**\n1. ✅ Removed invalid `plugins` array from `opencode.jsonc`\n2. ✅ Created `~/.config/opencode/plugin/` directory\n3. ✅ Symlinked your swarm plugin → `~/.config/opencode/plugin/swarm.js`\n\nThe plugin will now auto-load on startup. Restart OpenCode to pick it up.\n\nSources:\n- [OpenCode Plugins Documentation](https://opencode.ai/docs/plugins/)\n- [OpenCode Config Documentation](https://opencode.ai/docs/config/)',
+      created_at: 1765161767083,
+      line_number: 9,
+      match_type: "exact",
+      score: 15.536974906921387,
+      snippet:
+        "Symlinked your swarm plugin → `~/.config/opencode/plugin/swarm.js`\n\nThe plugin will now auto-load on startup. Restart OpenCode to pick it up.\n\nSources:\n- [OpenC…",
+      source_path:
+        "/Users/joel/.claude/projects/-Users-joel--config-opencode/ccd64ac6-bca7-40e5-9150-cea58c3788ae.jsonl",
+      title:
+        "@opencode.jsonc has an invalid plugins key https://opencode.ai/docs/plugins/ https://opencode.ai/doc",
+      workspace: "/Users/joel/.config/opencode",
+    },
+    {
+      agent: "claude_code",
+      content:
+        "I'm ready to help you explore the codebase and design implementation plans. I'm in **READ-ONLY mode** - I can explore files, understand architecture, and create detailed plans, but I cannot and will not modify any files.\n\nI have access to the beads issue tracker (`bd` commands) and can see your current working directory is `/Users/joel/.config/opencode`.\n\n**Current git status shows:**\n- Modified: `.beads/issues.jsonl`, `AGENTS.md`, `command/swarm.md`, `opencode.jsonc`\n- Untracked: `command/swarm-collect.md`, `command/swarm-status.md`, `plugin/`\n\n**What would you like me to explore and plan?**\n\nCommon scenarios I can help with:\n- Designing new command implementations\n- Planning plugin architecture\n- Exploring existing patterns for feature additions\n- Creating implementation strategies for beads issues\n\nLet me know what you need, and I'll dive into the codebase, understand the current architecture, and provide a detailed implementation plan.",
+      created_at: 1765161814722,
+      line_number: 1,
+      match_type: "exact",
+      score: 14.522254943847656,
+      snippet:
+        ".md`, `command/swarm.md`, `opencode.jsonc`\n- Untracked: `command/swarm-collect.md`, `command/swarm-status.md`, `plugin/`\n\n**What would you like me to explore an…",
+      source_path:
+        "/Users/joel/.claude/projects/-Users-joel--config-opencode/agent-ee2a73ee.jsonl",
+      title: "opencode",
+      workspace: "/Users/joel/.config/opencode",
+    },
+  ],
+  hits_clamped: false,
+  limit: 2,
+  max_tokens: null,
+  offset: 0,
+  query: "swarm",
+  request_id: null,
+  total_matches: 2,
+} as const;
+
+/**
+ * cass health (human-readable output)
+ * Captured: 2025-12-25
+ */
+export const cassHealthHumanBaseline = `✓ Healthy (3ms)
+  Note: index stale (older than 300s)`;
+
+/**
+ * cass stats (human-readable output)
+ * Captured: 2025-12-25
+ */
+export const cassStatsHumanBaseline = `CASS Index Statistics
+=====================
+Database: /Users/joel/Library/Application Support/com.coding-agent-search.coding-agent-search/agent_search.db
+
+Totals:
+  Conversations: 162
+  Messages: 4213
+
+By Agent:
+  claude_code: 137
+  cursor: 23
+  codex: 2
+
+Top Workspaces:
+  /Users/joel/Code/vercel/academy-vectr-workflow-course-content/external/workflow-builder-starter: 28
+  /Users/joel/Code/vercel/slack-agents-course: 22
+  /Users/joel/Code/vercel/academy-vectr-workflow-course-content: 22
+  /Users/joel/Code/vercel/academy-content: 13
+  /Users/joel/Code/joelhooks/trt-buddy: 13
+  /Users/joel/Code/vercel/front: 11
+  /Users/joel/.config/opencode: 9
+  /Users/joel: 6
+  /Users/joel/Code/badass-courses/course-builder/apps/ai-hero: 5
+  /Users/joel/Code/vercel/front/apps/vercel-academy: 4
+
+Date Range: 2025-07-14 to 2025-12-08`;
+
+/**
+ * cass view <file> -n <line>
+ * Captured: 2025-12-25
+ * 
+ * Format: File path header, line indicator with context window, separator, content with line numbers
+ */
+export const cassViewBaseline = `File: /Users/joel/.config/swarm-tools/sessions/ses_19yz2iaMpHxY1ddvVq2voC.jsonl
+Line: 1 (context: 5)
+----------------------------------------
+>    1 | {"session_id":"ses_19yz2iaMpHxY1ddvVq2voC","epic_id":"cell-f2p61v-mjko4d89zdt","timestamp":"2025-12-24T23:51:52.896Z","event_type":"OUTCOME","outcome_type":"subtask_success","payload":{"bead_id":"cell-f2p61v-mjko4d89zdt","duration_ms":0,"files_touched":[],"verification_passed":false,"verification_skipped":true}}
+----------------------------------------`;
+
+/**
+ * Error responses (captured from actual failures)
+ */
+export const cassErrorBaseline = {
+  fileNotFound: {
+    error: {
+      code: 3,
+      hint: null,
+      kind: "file-not-found",
+      message:
+        "File not found: /Users/joel/.config/swarm-tools/sessions/ses_fRrFb7WrNr9K89JBCKd6GV.jsonl",
+      retryable: false,
+    },
+  },
+  invalidArgument: {
+    error: {
+      code: 2,
+      hint: {
+        common_mistakes: [
+          {
+            correct: "cass robot-docs",
+            wrong: "cass --robot-docs",
+          },
+          {
+            correct: "cass robot-docs commands",
+            wrong: "cass --robot-docs=commands",
+          },
+          {
+            correct: "cass robot-docs",
+            wrong: "cass robot-docs --robot",
+          },
+        ],
+        error:
+          "error: unexpected argument '--robot' found\\n\\nUsage: cass stats [OPTIONS]\\n\\nFor more information, try '--help'.\\n",
+        examples: [
+          "cass robot-docs commands",
+          "cass robot-docs schemas",
+          "cass robot-docs examples",
+          "cass --robot-help",
+        ],
+        flag_syntax: {
+          correct: ["--limit 5", "--robot", "--json"],
+          incorrect: ["-limit 5", "limit=5", "--Limit"],
+        },
+        hints: [
+          "For get robot-mode documentation, try: cass --robot-help",
+        ],
+        kind: "argument_parsing",
+        status: "error",
+      },
+      kind: "usage",
+      message: "Could not parse arguments",
+      retryable: false,
+    },
+  },
+} as const;
+
+/**
+ * Schema definitions extracted from actual responses
+ */
+export type CassStatsResponse = typeof cassStatsBaseline;
+export type CassSearchResponse = typeof cassSearchBaseline;
+export type CassSearchHit = CassSearchResponse["hits"][number];
+export type CassAgentStats = CassStatsResponse["by_agent"][number];
+export type CassWorkspaceStats = CassStatsResponse["top_workspaces"][number];
+export type CassError =
+  | typeof cassErrorBaseline.fileNotFound
+  | typeof cassErrorBaseline.invalidArgument;

package/examples/plugin-wrapper-template.ts

@@ -1028,6 +1028,88 @@ const swarm_get_pattern_insights = tool({
   execute: (args, ctx) => execTool("swarm_get_pattern_insights", args, ctx),
 });
 
+// =============================================================================
+// CASS Tools (Cross-Agent Session Search)
+// =============================================================================
+
+const cass_search = tool({
+  description: "Search across all AI coding agent histories (Claude, Codex, Cursor, Gemini, Aider, ChatGPT, Cline, OpenCode, Amp, Pi-Agent). Query BEFORE solving problems from scratch - another agent may have already solved it. Returns matching sessions ranked by relevance.",
+  args: {
+    query: tool.schema.string().describe("Search query (e.g., 'authentication error Next.js')"),
+    agent: tool.schema
+      .string()
+      .optional()
+      .describe("Filter by agent name (e.g., 'claude', 'cursor')"),
+    days: tool.schema
+      .number()
+      .optional()
+      .describe("Only search sessions from last N days"),
+    limit: tool.schema
+      .number()
+      .optional()
+      .describe("Max results to return (default: 5)"),
+    fields: tool.schema
+      .string()
+      .optional()
+      .describe("Field selection: 'minimal' for compact output (path, line, agent only)"),
+  },
+  execute: (args, ctx) => execTool("cass_search", args, ctx),
+});
+
+const cass_view = tool({
+  description: "View a specific conversation/session from search results. Use source_path from cass_search output.",
+  args: {
+    path: tool.schema
+      .string()
+      .describe("Path to session file (from cass_search results)"),
+    line: tool.schema
+      .number()
+      .optional()
+      .describe("Jump to specific line number"),
+  },
+  execute: (args, ctx) => execTool("cass_view", args, ctx),
+});
+
+const cass_expand = tool({
+  description: "Expand context around a specific line in a session. Shows messages before/after.",
+  args: {
+    path: tool.schema
+      .string()
+      .describe("Path to session file"),
+    line: tool.schema
+      .number()
+      .describe("Line number to expand around"),
+    context: tool.schema
+      .number()
+      .optional()
+      .describe("Number of lines before/after to show (default: 5)"),
+  },
+  execute: (args, ctx) => execTool("cass_expand", args, ctx),
+});
+
+const cass_health = tool({
+  description: "Check if cass index is healthy. Exit 0 = ready, Exit 1 = needs indexing. Run this before searching.",
+  args: {},
+  execute: (args, ctx) => execTool("cass_health", args, ctx),
+});
+
+const cass_index = tool({
+  description: "Build or rebuild the search index. Run this if health check fails or to pick up new sessions.",
+  args: {
+    full: tool.schema
+      .boolean()
+      .optional()
+      .describe("Force full rebuild (default: incremental)"),
+  },
+  execute: (args, ctx) => execTool("cass_index", args, ctx),
+});
+
+const cass_stats = tool({
+  description: "Show index statistics - how many sessions, messages, agents indexed.",
+  args: {},
+  execute: (args, ctx) => execTool("cass_stats", args, ctx),
+});
+
 // =============================================================================
 // Plugin Export
 // =============================================================================
@@ -2064,6 +2146,13 @@ const SwarmPlugin: Plugin = async (
       swarm_get_strategy_insights,
       swarm_get_file_insights,
       swarm_get_pattern_insights,
+      // CASS (Cross-Agent Session Search)
+      cass_search,
+      cass_view,
+      cass_expand,
+      cass_health,
+      cass_index,
+      cass_stats,
     },
 
     // Swarm-aware compaction hook with LLM-powered continuation prompts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-swarm-plugin",
-  "version": "0.42.9",
+  "version": "0.44.0",
   "description": "Multi-agent swarm coordination for OpenCode with learning capabilities, beads integration, and Agent Mail",
   "type": "module",
   "main": "./dist/index.js",

package/src/contributor-tools.test.ts

@@ -0,0 +1,133 @@
+/**
+ * Contributor Tools Integration Tests
+ *
+ * Tests for contributor_lookup tool that fetches GitHub profiles
+ * and generates changeset credits.
+ */
+
+import { afterAll, describe, expect, test } from "bun:test";
+import { closeAllSwarmMail } from "swarm-mail";
+import { contributorTools, resetContributorCache } from "./contributor-tools";
+import { resetMemoryCache } from "./memory-tools";
+
+interface ToolContext {
+	sessionID: string;
+}
+
+describe("contributor tools integration", () => {
+	afterAll(async () => {
+		resetContributorCache();
+		resetMemoryCache();
+		await closeAllSwarmMail();
+	});
+
+	test("contributor_lookup tool is registered", () => {
+		expect(contributorTools).toHaveProperty("contributor_lookup");
+		expect(typeof contributorTools.contributor_lookup.execute).toBe("function");
+	});
+
+	describe("contributor_lookup", () => {
+		test("returns formatted credit with name + twitter", async () => {
+			const tool = contributorTools.contributor_lookup;
+			const result = await tool.execute(
+				{
+					login: "kentcdodds",
+					issue: 42,
+				},
+				{ sessionID: "test-session" } as ToolContext,
+			);
+
+			expect(typeof result).toBe("string");
+			const parsed = JSON.parse(result);
+			
+			expect(parsed.login).toBe("kentcdodds");
+			expect(parsed.name).toBeDefined();
+			expect(parsed.twitter).toBeDefined();
+			expect(parsed.credit_line).toContain("Thanks to");
+			expect(parsed.credit_line).toContain("reporting #42");
+			expect(parsed.credit_line).toContain("@kentcdodds");
+			expect(parsed.credit_line).toContain("https://x.com/");
+			expect(parsed.memory_stored).toBe(true);
+		});
+
+		test("handles missing twitter gracefully", async () => {
+			const tool = contributorTools.contributor_lookup;
+			
+			// Use a user that likely has name but no twitter
+			// (we'll test the format logic mainly)
+			const result = await tool.execute(
+				{
+					login: "torvalds", // Linus Torvalds - has name, might not have twitter
+					issue: 123,
+				},
+				{ sessionID: "test-session" } as ToolContext,
+			);
+
+			const parsed = JSON.parse(result);
+			
+			expect(parsed.login).toBe("torvalds");
+			expect(parsed.name).toBeDefined();
+			expect(parsed.credit_line).toContain("Thanks to");
+			expect(parsed.credit_line).toContain("reporting #123");
+			// Should have GitHub mention if no Twitter
+			if (!parsed.twitter) {
+				expect(parsed.credit_line).toContain("on GitHub");
+			}
+		});
+
+		test("works without issue number", async () => {
+			const tool = contributorTools.contributor_lookup;
+			const result = await tool.execute(
+				{
+					login: "kentcdodds",
+				},
+				{ sessionID: "test-session" } as ToolContext,
+			);
+
+			const parsed = JSON.parse(result);
+			
+			expect(parsed.login).toBe("kentcdodds");
+			expect(parsed.credit_line).toContain("Thanks to");
+			// Should NOT contain "reporting #"
+			expect(parsed.credit_line).not.toContain("reporting #");
+		});
+
+		test("stores contributor info in semantic-memory", async () => {
+			const tool = contributorTools.contributor_lookup;
+			const result = await tool.execute(
+				{
+					login: "gaearon", // Dan Abramov
+					issue: 99,
+				},
+				{ sessionID: "test-session" } as ToolContext,
+			);
+
+			const parsed = JSON.parse(result);
+			
+			// Just verify memory_stored flag - embedding search may be async
+			expect(parsed.memory_stored).toBe(true);
+		});
+
+		test("returns all expected fields", async () => {
+			const tool = contributorTools.contributor_lookup;
+			const result = await tool.execute(
+				{
+					login: "kentcdodds",
+				},
+				{ sessionID: "test-session" } as ToolContext,
+			);
+
+			const parsed = JSON.parse(result);
+			
+			// Required fields
+			expect(parsed).toHaveProperty("login");
+			expect(parsed).toHaveProperty("credit_line");
+			expect(parsed).toHaveProperty("memory_stored");
+			
+			// Optional fields (may be null but should be present)
+			expect(parsed).toHaveProperty("name");
+			expect(parsed).toHaveProperty("twitter");
+			expect(parsed).toHaveProperty("bio");
+		});
+	});
+});

package/src/contributor-tools.ts

@@ -0,0 +1,201 @@
+/**
+ * Contributor Tools - GitHub profile extraction for changeset credits
+ *
+ * Provides contributor_lookup tool for fetching GitHub profiles and
+ * generating formatted changeset credit lines. Automatically stores
+ * contributor info in semantic-memory for future reference.
+ *
+ * Based on patterns from gh-issue-triage skill.
+ */
+
+import { tool } from "@opencode-ai/plugin";
+import { z } from "zod";
+import { getMemoryAdapter } from "./memory-tools";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+const GitHubUserSchema = z.object({
+	login: z.string(),
+	name: z.string().nullable(),
+	twitter_username: z.string().nullable(),
+	blog: z.string().nullable(),
+	bio: z.string().nullable(),
+	avatar_url: z.string(),
+	html_url: z.string(),
+	public_repos: z.number().optional(),
+	followers: z.number().optional(),
+});
+
+type GitHubUser = z.infer<typeof GitHubUserSchema>;
+
+interface ContributorResult {
+	login: string;
+	name: string | null;
+	twitter: string | null;
+	bio: string | null;
+	credit_line: string;
+	memory_stored: boolean;
+}
+
+interface ToolContext {
+	sessionID: string;
+}
+
+// ============================================================================
+// Core Functions
+// ============================================================================
+
+/**
+ * Fetch GitHub user profile via gh CLI
+ */
+async function fetchGitHubUser(login: string): Promise<GitHubUser> {
+	const result = await Bun.$`gh api users/${login}`.json();
+	return GitHubUserSchema.parse(result);
+}
+
+/**
+ * Format changeset credit line based on available data
+ *
+ * Hierarchy:
+ * 1. Name + Twitter: "Thanks to {Name} ([@twitter](...)) for reporting #{issue}!"
+ * 2. Name only: "Thanks to {Name} (@{login} on GitHub) for reporting #{issue}!"
+ * 3. Twitter only: "Thanks to [@twitter](...) for reporting #{issue}!"
+ * 4. Fallback: "Thanks to @{login} for reporting #{issue}!"
+ */
+function formatCreditLine(user: GitHubUser, issueNumber?: number): string {
+	const issueText = issueNumber ? `reporting #${issueNumber}` : "the report";
+
+	// PREFERRED: Full name + Twitter (best for engagement)
+	if (user.name && user.twitter_username) {
+		return `Thanks to ${user.name} ([@${user.twitter_username}](https://x.com/${user.twitter_username})) for ${issueText}!`;
+	}
+
+	// Twitter only (no name available)
+	if (user.twitter_username) {
+		return `Thanks to [@${user.twitter_username}](https://x.com/${user.twitter_username}) for ${issueText}!`;
+	}
+
+	// Name only (no Twitter)
+	if (user.name) {
+		return `Thanks to ${user.name} (@${user.login} on GitHub) for ${issueText}!`;
+	}
+
+	// Fallback: GitHub username only
+	return `Thanks to @${user.login} for ${issueText}!`;
+}
+
+/**
+ * Store contributor info in semantic-memory
+ */
+async function storeContributorMemory(
+	user: GitHubUser,
+	issueNumber?: number,
+): Promise<boolean> {
+	try {
+		const adapter = await getMemoryAdapter();
+
+		const twitterPart = user.twitter_username
+			? ` (@${user.twitter_username} on Twitter)`
+			: "";
+		const issuePart = issueNumber ? `. Filed issue #${issueNumber}` : "";
+		const bioPart = user.bio ? `. Bio: '${user.bio}'` : "";
+
+		const tags = [
+			"contributor",
+			user.login,
+			issueNumber ? `issue-${issueNumber}` : null,
+		]
+			.filter(Boolean)
+			.join(",");
+
+		const information = `Contributor @${user.login}: ${user.name || user.login}${twitterPart}${issuePart}${bioPart}`;
+
+		await adapter.store({
+			information,
+			tags,
+		});
+
+		return true;
+	} catch (error) {
+		console.error("Failed to store contributor memory:", error);
+		return false;
+	}
+}
+
+// ============================================================================
+// Cache Management
+// ============================================================================
+
+/**
+ * Reset cache for testing
+ */
+export function resetContributorCache(): void {
+	// Currently no cache, but keeping this for consistency with other tools
+}
+
+// ============================================================================
+// Plugin Tools
+// ============================================================================
+
+/**
+ * Look up GitHub contributor and generate changeset credit
+ */
+export const contributor_lookup = tool({
+	description:
+		"Fetch GitHub contributor profile and generate formatted changeset credit. Automatically stores contributor info in semantic-memory. Returns login, name, twitter, bio, and ready-to-paste credit_line.",
+	args: {
+		login: tool.schema.string().describe("GitHub username (required)"),
+		issue: tool.schema
+			.number()
+			.optional()
+			.describe("Issue number for context (optional)"),
+	},
+	async execute(
+		args: { login: string; issue?: number },
+		_ctx: ToolContext,
+	): Promise<string> {
+		try {
+			// Fetch GitHub profile
+			const user = await fetchGitHubUser(args.login);
+
+			// Format credit line
+			const creditLine = formatCreditLine(user, args.issue);
+
+			// Store in semantic-memory
+			const memoryStored = await storeContributorMemory(user, args.issue);
+
+			// Build result
+			const result: ContributorResult = {
+				login: user.login,
+				name: user.name,
+				twitter: user.twitter_username,
+				bio: user.bio,
+				credit_line: creditLine,
+				memory_stored: memoryStored,
+			};
+
+			return JSON.stringify(result, null, 2);
+		} catch (error) {
+			if (error instanceof Error) {
+				return JSON.stringify({
+					error: error.message,
+					login: args.login,
+				});
+			}
+			return JSON.stringify({
+				error: "Unknown error fetching contributor",
+				login: args.login,
+			});
+		}
+	},
+});
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export const contributorTools = {
+	contributor_lookup,
+} as const;