opencode-swarm-plugin 0.56.1 → 0.57.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (194) hide show
  1. package/README.md +21 -0
  2. package/claude-plugin/agents/background-worker.md +1 -0
  3. package/claude-plugin/agents/coordinator.md +2 -0
  4. package/claude-plugin/agents/worker.md +1 -0
  5. package/claude-plugin/bin/swarm-mcp-server.ts +53 -8
  6. package/claude-plugin/dist/agent-mail.d.ts +480 -0
  7. package/claude-plugin/dist/agent-mail.d.ts.map +1 -0
  8. package/claude-plugin/dist/anti-patterns.d.ts +257 -0
  9. package/claude-plugin/dist/anti-patterns.d.ts.map +1 -0
  10. package/claude-plugin/dist/bin/swarm.js +373132 -0
  11. package/claude-plugin/dist/build/mcp-bundle.d.ts +16 -0
  12. package/claude-plugin/dist/build/mcp-bundle.d.ts.map +1 -0
  13. package/claude-plugin/dist/cache/claude-plugin-cache.d.ts +41 -0
  14. package/claude-plugin/dist/cache/claude-plugin-cache.d.ts.map +1 -0
  15. package/claude-plugin/dist/cass-tools.d.ts +74 -0
  16. package/claude-plugin/dist/cass-tools.d.ts.map +1 -0
  17. package/claude-plugin/dist/claude-plugin/claude-plugin-assets.d.ts +10 -0
  18. package/claude-plugin/dist/claude-plugin/claude-plugin-assets.d.ts.map +1 -0
  19. package/claude-plugin/dist/compaction-hook.d.ts +178 -0
  20. package/claude-plugin/dist/compaction-hook.d.ts.map +1 -0
  21. package/claude-plugin/dist/compaction-observability.d.ts +173 -0
  22. package/claude-plugin/dist/compaction-observability.d.ts.map +1 -0
  23. package/claude-plugin/dist/compaction-prompt-scoring.d.ts +125 -0
  24. package/claude-plugin/dist/compaction-prompt-scoring.d.ts.map +1 -0
  25. package/claude-plugin/dist/compaction-prompt-scoring.js +139 -0
  26. package/claude-plugin/dist/contributor-tools.d.ts +42 -0
  27. package/claude-plugin/dist/contributor-tools.d.ts.map +1 -0
  28. package/claude-plugin/dist/coordinator-guard.d.ts +79 -0
  29. package/claude-plugin/dist/coordinator-guard.d.ts.map +1 -0
  30. package/claude-plugin/dist/dashboard.d.ts +82 -0
  31. package/claude-plugin/dist/dashboard.d.ts.map +1 -0
  32. package/claude-plugin/dist/decision-trace-integration.d.ts +204 -0
  33. package/claude-plugin/dist/decision-trace-integration.d.ts.map +1 -0
  34. package/claude-plugin/dist/error-enrichment.d.ts +49 -0
  35. package/claude-plugin/dist/error-enrichment.d.ts.map +1 -0
  36. package/claude-plugin/dist/eval-capture.d.ts +494 -0
  37. package/claude-plugin/dist/eval-capture.d.ts.map +1 -0
  38. package/claude-plugin/dist/eval-capture.js +12844 -0
  39. package/claude-plugin/dist/eval-gates.d.ts +84 -0
  40. package/claude-plugin/dist/eval-gates.d.ts.map +1 -0
  41. package/claude-plugin/dist/eval-history.d.ts +117 -0
  42. package/claude-plugin/dist/eval-history.d.ts.map +1 -0
  43. package/claude-plugin/dist/eval-learning.d.ts +216 -0
  44. package/claude-plugin/dist/eval-learning.d.ts.map +1 -0
  45. package/claude-plugin/dist/eval-runner.d.ts +134 -0
  46. package/claude-plugin/dist/eval-runner.d.ts.map +1 -0
  47. package/claude-plugin/dist/examples/plugin-wrapper-template.ts +3341 -0
  48. package/claude-plugin/dist/export-tools.d.ts +76 -0
  49. package/claude-plugin/dist/export-tools.d.ts.map +1 -0
  50. package/claude-plugin/dist/hive.d.ts +949 -0
  51. package/claude-plugin/dist/hive.d.ts.map +1 -0
  52. package/claude-plugin/dist/hive.js +15009 -0
  53. package/claude-plugin/dist/hivemind-tools.d.ts +479 -0
  54. package/claude-plugin/dist/hivemind-tools.d.ts.map +1 -0
  55. package/claude-plugin/dist/hooks/atomic-write.d.ts +21 -0
  56. package/claude-plugin/dist/hooks/atomic-write.d.ts.map +1 -0
  57. package/claude-plugin/dist/hooks/constants.d.ts +28 -0
  58. package/claude-plugin/dist/hooks/constants.d.ts.map +1 -0
  59. package/claude-plugin/dist/hooks/index.d.ts +16 -0
  60. package/claude-plugin/dist/hooks/index.d.ts.map +1 -0
  61. package/claude-plugin/dist/hooks/session-start.d.ts +30 -0
  62. package/claude-plugin/dist/hooks/session-start.d.ts.map +1 -0
  63. package/claude-plugin/dist/hooks/tool-complete.d.ts +54 -0
  64. package/claude-plugin/dist/hooks/tool-complete.d.ts.map +1 -0
  65. package/claude-plugin/dist/index.d.ts +2017 -0
  66. package/claude-plugin/dist/index.d.ts.map +1 -0
  67. package/claude-plugin/dist/index.js +73454 -0
  68. package/claude-plugin/dist/learning.d.ts +700 -0
  69. package/claude-plugin/dist/learning.d.ts.map +1 -0
  70. package/claude-plugin/dist/logger.d.ts +38 -0
  71. package/claude-plugin/dist/logger.d.ts.map +1 -0
  72. package/claude-plugin/dist/mandate-promotion.d.ts +93 -0
  73. package/claude-plugin/dist/mandate-promotion.d.ts.map +1 -0
  74. package/claude-plugin/dist/mandate-storage.d.ts +209 -0
  75. package/claude-plugin/dist/mandate-storage.d.ts.map +1 -0
  76. package/claude-plugin/dist/mandates.d.ts +230 -0
  77. package/claude-plugin/dist/mandates.d.ts.map +1 -0
  78. package/claude-plugin/dist/mcp/swarm-mcp-server.js +19675 -0
  79. package/claude-plugin/dist/memory-tools.d.ts +281 -0
  80. package/claude-plugin/dist/memory-tools.d.ts.map +1 -0
  81. package/claude-plugin/dist/memory.d.ts +164 -0
  82. package/claude-plugin/dist/memory.d.ts.map +1 -0
  83. package/claude-plugin/dist/model-selection.d.ts +37 -0
  84. package/claude-plugin/dist/model-selection.d.ts.map +1 -0
  85. package/claude-plugin/dist/observability-health.d.ts +87 -0
  86. package/claude-plugin/dist/observability-health.d.ts.map +1 -0
  87. package/claude-plugin/dist/observability-tools.d.ts +184 -0
  88. package/claude-plugin/dist/observability-tools.d.ts.map +1 -0
  89. package/claude-plugin/dist/output-guardrails.d.ts +125 -0
  90. package/claude-plugin/dist/output-guardrails.d.ts.map +1 -0
  91. package/claude-plugin/dist/pattern-maturity.d.ts +246 -0
  92. package/claude-plugin/dist/pattern-maturity.d.ts.map +1 -0
  93. package/claude-plugin/dist/planning-guardrails.d.ts +183 -0
  94. package/claude-plugin/dist/planning-guardrails.d.ts.map +1 -0
  95. package/claude-plugin/dist/plugin.d.ts +22 -0
  96. package/claude-plugin/dist/plugin.d.ts.map +1 -0
  97. package/claude-plugin/dist/plugin.js +72296 -0
  98. package/claude-plugin/dist/post-compaction-tracker.d.ts +133 -0
  99. package/claude-plugin/dist/post-compaction-tracker.d.ts.map +1 -0
  100. package/claude-plugin/dist/query-tools.d.ts +90 -0
  101. package/claude-plugin/dist/query-tools.d.ts.map +1 -0
  102. package/claude-plugin/dist/rate-limiter.d.ts +218 -0
  103. package/claude-plugin/dist/rate-limiter.d.ts.map +1 -0
  104. package/claude-plugin/dist/regression-detection.d.ts +58 -0
  105. package/claude-plugin/dist/regression-detection.d.ts.map +1 -0
  106. package/claude-plugin/dist/replay-tools.d.ts +28 -0
  107. package/claude-plugin/dist/replay-tools.d.ts.map +1 -0
  108. package/claude-plugin/dist/repo-crawl.d.ts +146 -0
  109. package/claude-plugin/dist/repo-crawl.d.ts.map +1 -0
  110. package/claude-plugin/dist/schemas/cell-events.d.ts +1352 -0
  111. package/claude-plugin/dist/schemas/cell-events.d.ts.map +1 -0
  112. package/claude-plugin/dist/schemas/cell.d.ts +413 -0
  113. package/claude-plugin/dist/schemas/cell.d.ts.map +1 -0
  114. package/claude-plugin/dist/schemas/evaluation.d.ts +161 -0
  115. package/claude-plugin/dist/schemas/evaluation.d.ts.map +1 -0
  116. package/claude-plugin/dist/schemas/index.d.ts +46 -0
  117. package/claude-plugin/dist/schemas/index.d.ts.map +1 -0
  118. package/claude-plugin/dist/schemas/mandate.d.ts +336 -0
  119. package/claude-plugin/dist/schemas/mandate.d.ts.map +1 -0
  120. package/claude-plugin/dist/schemas/swarm-context.d.ts +131 -0
  121. package/claude-plugin/dist/schemas/swarm-context.d.ts.map +1 -0
  122. package/claude-plugin/dist/schemas/task.d.ts +189 -0
  123. package/claude-plugin/dist/schemas/task.d.ts.map +1 -0
  124. package/claude-plugin/dist/schemas/worker-handoff.d.ts +78 -0
  125. package/claude-plugin/dist/schemas/worker-handoff.d.ts.map +1 -0
  126. package/claude-plugin/dist/sessions/agent-discovery.d.ts +59 -0
  127. package/claude-plugin/dist/sessions/agent-discovery.d.ts.map +1 -0
  128. package/claude-plugin/dist/sessions/index.d.ts +10 -0
  129. package/claude-plugin/dist/sessions/index.d.ts.map +1 -0
  130. package/claude-plugin/dist/skills.d.ts +490 -0
  131. package/claude-plugin/dist/skills.d.ts.map +1 -0
  132. package/claude-plugin/dist/storage.d.ts +260 -0
  133. package/claude-plugin/dist/storage.d.ts.map +1 -0
  134. package/claude-plugin/dist/structured.d.ts +206 -0
  135. package/claude-plugin/dist/structured.d.ts.map +1 -0
  136. package/claude-plugin/dist/swarm-adversarial-review.d.ts +104 -0
  137. package/claude-plugin/dist/swarm-adversarial-review.d.ts.map +1 -0
  138. package/claude-plugin/dist/swarm-decompose.d.ts +297 -0
  139. package/claude-plugin/dist/swarm-decompose.d.ts.map +1 -0
  140. package/claude-plugin/dist/swarm-insights.d.ts +390 -0
  141. package/claude-plugin/dist/swarm-insights.d.ts.map +1 -0
  142. package/claude-plugin/dist/swarm-mail.d.ts +274 -0
  143. package/claude-plugin/dist/swarm-mail.d.ts.map +1 -0
  144. package/claude-plugin/dist/swarm-orchestrate.d.ts +924 -0
  145. package/claude-plugin/dist/swarm-orchestrate.d.ts.map +1 -0
  146. package/claude-plugin/dist/swarm-prompts.d.ts +467 -0
  147. package/claude-plugin/dist/swarm-prompts.d.ts.map +1 -0
  148. package/claude-plugin/dist/swarm-prompts.js +45286 -0
  149. package/claude-plugin/dist/swarm-research.d.ts +125 -0
  150. package/claude-plugin/dist/swarm-research.d.ts.map +1 -0
  151. package/claude-plugin/dist/swarm-review.d.ts +214 -0
  152. package/claude-plugin/dist/swarm-review.d.ts.map +1 -0
  153. package/claude-plugin/dist/swarm-signature.d.ts +106 -0
  154. package/claude-plugin/dist/swarm-signature.d.ts.map +1 -0
  155. package/claude-plugin/dist/swarm-strategies.d.ts +113 -0
  156. package/claude-plugin/dist/swarm-strategies.d.ts.map +1 -0
  157. package/claude-plugin/dist/swarm-validation.d.ts +127 -0
  158. package/claude-plugin/dist/swarm-validation.d.ts.map +1 -0
  159. package/claude-plugin/dist/swarm-worktree.d.ts +185 -0
  160. package/claude-plugin/dist/swarm-worktree.d.ts.map +1 -0
  161. package/claude-plugin/dist/swarm.d.ts +590 -0
  162. package/claude-plugin/dist/swarm.d.ts.map +1 -0
  163. package/claude-plugin/dist/tool-availability.d.ts +91 -0
  164. package/claude-plugin/dist/tool-availability.d.ts.map +1 -0
  165. package/claude-plugin/dist/utils/tree-renderer.d.ts +61 -0
  166. package/claude-plugin/dist/utils/tree-renderer.d.ts.map +1 -0
  167. package/claude-plugin/dist/validators/index.d.ts +7 -0
  168. package/claude-plugin/dist/validators/index.d.ts.map +1 -0
  169. package/claude-plugin/dist/validators/schema-validator.d.ts +58 -0
  170. package/claude-plugin/dist/validators/schema-validator.d.ts.map +1 -0
  171. package/claude-plugin/scripts/copyClaudePluginRuntimeAssets.ts +84 -0
  172. package/claude-plugin/skills/always-on-guidance/SKILL.md +45 -0
  173. package/claude-plugin/tests/mcp-runtime.test.ts +187 -0
  174. package/dist/agent-mail.d.ts +4 -4
  175. package/dist/agent-mail.d.ts.map +1 -1
  176. package/dist/bin/swarm.js +479 -20
  177. package/dist/build/mcp-bundle.d.ts +16 -0
  178. package/dist/build/mcp-bundle.d.ts.map +1 -0
  179. package/dist/cache/claude-plugin-cache.d.ts +41 -0
  180. package/dist/cache/claude-plugin-cache.d.ts.map +1 -0
  181. package/dist/claude-plugin/claude-plugin-assets.d.ts +10 -0
  182. package/dist/claude-plugin/claude-plugin-assets.d.ts.map +1 -0
  183. package/dist/compaction-hook.d.ts +1 -1
  184. package/dist/compaction-hook.d.ts.map +1 -1
  185. package/dist/index.js +371 -260
  186. package/dist/mcp/swarm-mcp-server.js +19675 -0
  187. package/dist/plugin.js +370 -259
  188. package/dist/skills.d.ts +15 -0
  189. package/dist/skills.d.ts.map +1 -1
  190. package/dist/swarm-mail.d.ts.map +1 -1
  191. package/dist/swarm-prompts.d.ts +3 -1
  192. package/dist/swarm-prompts.d.ts.map +1 -1
  193. package/dist/swarm-prompts.js +88 -8
  194. package/package.json +4 -1
package/README.md CHANGED
@@ -33,6 +33,13 @@ swarm setup
33
33
 
34
34
  Choose **Marketplace → opencode-swarm-plugin → Install**.
35
35
 
36
+ **GitHub marketplace (this repo):**
37
+
38
+ ```text
39
+ /plugin marketplace add joelhooks/swarm-tools
40
+ /plugin install swarm@swarm-tools
41
+ ```
42
+
36
43
  **Global install (npm):**
37
44
 
38
45
  ```bash
@@ -48,6 +55,18 @@ swarm claude init
48
55
 
49
56
  **MCP auto-launch:** Claude Code starts MCP servers declared in the plugin `mcpServers` config automatically. You only need `swarm mcp-serve` when debugging outside Claude Code.
50
57
 
58
+ ### MCP Troubleshooting (Marketplace Install)
59
+
60
+ If Claude Code reports an MCP failure or no swarm tools appear, build artifacts are missing.
61
+
62
+ 1. From the repo root, build the plugin:
63
+ ```bash
64
+ bun install
65
+ bun turbo build --filter=opencode-swarm-plugin
66
+ ```
67
+ 2. Confirm `packages/opencode-swarm-plugin/dist/` exists.
68
+ 3. Reinstall the plugin from `/plugin` and restart OpenCode.
69
+
51
70
  ### 2. Initialize in Your Project
52
71
 
53
72
  ```bash
@@ -277,6 +296,8 @@ Auto-saves progress at milestones. Survives context death or crashes. Data store
277
296
 
278
297
  ## Tools Reference
279
298
 
299
+ **Always-on guidance:** Coordinator and worker prompts (plus compaction resumes) include an always-on guidance skill. It sets instruction priority and tool order: swarm plugin tools → Read/Edit → search → Bash. Model defaults differ: GPT-5.2-code prefers strict checklists and minimal output; Opus 4.5 allows brief rationale.
300
+
280
301
  ### Hive (Work Item Tracking)
281
302
 
282
303
  | Tool | Purpose |
@@ -3,6 +3,7 @@ name: background-worker
3
3
  description: Runs background-only tasks without MCP tool access.
4
4
  model: haiku
5
5
  skills:
6
+ - always-on-guidance
6
7
  - swarm-coordination
7
8
  - testing-patterns
8
9
  tools:
@@ -3,6 +3,7 @@ name: coordinator
3
3
  description: Orchestrates swarm coordination and supervises worker agents.
4
4
  model: opus
5
5
  skills:
6
+ - always-on-guidance
6
7
  - swarm-coordination
7
8
  - system-design
8
9
  - testing-patterns
@@ -21,6 +22,7 @@ Orchestrates swarm work: decomposes tasks, spawns workers, monitors progress, an
21
22
  - **Never reserve files** as the coordinator. Workers reserve their own files.
22
23
  - **Decompose with intent** using `swarm_plan_prompt` + `swarm_validate_decomposition`.
23
24
  - **Review every worker completion** via `swarm_review` + `swarm_review_feedback`.
25
+ - **After every `swarm_spawn_subtask`, immediately call `Task(subagent_type="swarm-worker", prompt="<prompt returned by swarm_spawn_subtask>")`.**
24
26
  - **Record outcomes** with `swarm_complete` for learning signals.
25
27
 
26
28
  ## Tool Access
@@ -3,6 +3,7 @@ name: worker
3
3
  description: Executes a single subtask with file reservations and progress reporting.
4
4
  model: sonnet
5
5
  skills:
6
+ - always-on-guidance
6
7
  - swarm-coordination
7
8
  - testing-patterns
8
9
  - system-design
@@ -1,7 +1,9 @@
1
1
  #!/usr/bin/env bun
2
2
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
3
3
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
4
- import { allTools } from "../../dist/index.js";
4
+ import { existsSync } from "fs";
5
+ import { dirname, resolve } from "path";
6
+ import { fileURLToPath, pathToFileURL } from "url";
5
7
 
6
8
  type ToolContext = {
7
9
  sessionID: string;
@@ -16,6 +18,47 @@ type ToolDefinition = {
16
18
  execute: (args: Record<string, unknown>, context: ToolContext) => Promise<unknown> | unknown;
17
19
  };
18
20
 
21
+ /**
22
+ * Resolve the tool registry entrypoint for the MCP server.
23
+ */
24
+ export function resolveToolRegistryPath({
25
+ currentDir = dirname(fileURLToPath(import.meta.url)),
26
+ }: {
27
+ currentDir?: string;
28
+ } = {}): string {
29
+ const pluginDistPath = resolve(currentDir, "../dist/index.js");
30
+
31
+ if (existsSync(pluginDistPath)) {
32
+ return pluginDistPath;
33
+ }
34
+
35
+ const sourcePath = resolve(currentDir, "../../src/index.ts");
36
+ if (existsSync(sourcePath)) {
37
+ return sourcePath;
38
+ }
39
+
40
+ throw new Error(
41
+ `[swarm-mcp] Missing Claude plugin runtime bundle. Expected ${pluginDistPath}. ` +
42
+ "Rebuild the package so claude-plugin/dist is populated.",
43
+ );
44
+ }
45
+
46
+ /**
47
+ * Load the swarm tool registry for MCP execution.
48
+ */
49
+ export async function loadToolRegistry(): Promise<Record<string, ToolDefinition>> {
50
+ const registryPath = resolveToolRegistryPath();
51
+ const moduleUrl = pathToFileURL(registryPath).href;
52
+ const toolsModule = await import(moduleUrl);
53
+ const tools = toolsModule.allTools ?? toolsModule.default?.allTools;
54
+
55
+ if (!tools) {
56
+ throw new Error(`[swarm-mcp] Tool registry missing at ${registryPath}`);
57
+ }
58
+
59
+ return tools as Record<string, ToolDefinition>;
60
+ }
61
+
19
62
  /**
20
63
  * Build a tool execution context for MCP tool calls.
21
64
  */
@@ -57,8 +100,8 @@ function formatToolOutput(result: unknown): string {
57
100
  /**
58
101
  * Register all swarm tools with the MCP server.
59
102
  */
60
- function registerTools(server: McpServer): void {
61
- const tools = allTools as Record<string, ToolDefinition>;
103
+ async function registerTools(server: McpServer): Promise<void> {
104
+ const tools = await loadToolRegistry();
62
105
 
63
106
  for (const [toolName, toolDef] of Object.entries(tools)) {
64
107
  server.registerTool(
@@ -90,14 +133,16 @@ async function main(): Promise<void> {
90
133
  version: process.env.SWARM_VERSION || "dev",
91
134
  });
92
135
 
93
- registerTools(server);
136
+ await registerTools(server);
94
137
 
95
138
  const transport = new StdioServerTransport();
96
139
  await server.connect(transport);
97
140
  console.error("[swarm-mcp] Server started");
98
141
  }
99
142
 
100
- main().catch((error) => {
101
- console.error("[swarm-mcp] Server failed", error);
102
- process.exit(1);
103
- });
143
+ if (import.meta.main) {
144
+ main().catch((error) => {
145
+ console.error("[swarm-mcp] Server failed", error);
146
+ process.exit(1);
147
+ });
148
+ }
@@ -0,0 +1,480 @@
1
+ import { z } from "zod";
2
+ import type { MailSessionState } from "swarm-mail";
3
+ declare const AGENT_MAIL_URL = "http://127.0.0.1:8765";
4
+ declare const MAX_INBOX_LIMIT = 5;
5
+ /**
6
+ * Set the default project directory for Agent Mail operations
7
+ *
8
+ * Called during plugin initialization with the actual project directory.
9
+ * This ensures agentmail_init uses the correct project path by default.
10
+ */
11
+ export declare function setAgentMailProjectDirectory(directory: string): void;
12
+ /**
13
+ * Get the default project directory
14
+ *
15
+ * Returns the configured directory, or falls back to cwd if not set.
16
+ */
17
+ export declare function getAgentMailProjectDirectory(): string;
18
+ declare const RETRY_CONFIG: {
19
+ maxRetries: number;
20
+ baseDelayMs: number;
21
+ maxDelayMs: number;
22
+ timeoutMs: number;
23
+ jitterPercent: number;
24
+ };
25
+ declare const RECOVERY_CONFIG: {
26
+ /** Max consecutive failures before attempting restart (1 = restart on first "unexpected error") */
27
+ failureThreshold: number;
28
+ /** Cooldown between restart attempts (ms) - 10 seconds */
29
+ restartCooldownMs: number;
30
+ /** Whether auto-restart is enabled */
31
+ enabled: boolean;
32
+ };
33
+ /**
34
+ * Agent Mail session state
35
+ * @deprecated Use MailSessionState from streams/events.ts instead
36
+ * This is kept for backward compatibility and re-exported as an alias
37
+ */
38
+ export type AgentMailState = MailSessionState;
39
+ /**
40
+ * State storage keyed by sessionID.
41
+ * In-memory cache that also persists to disk for CLI usage.
42
+ */
43
+ declare const sessionStates: Map<string, MailSessionState>;
44
+ /**
45
+ * AgentMailError - Custom error for Agent Mail operations
46
+ *
47
+ * Note: Using a factory pattern to avoid "Cannot call a class constructor without |new|"
48
+ * errors in some bundled environments (OpenCode's plugin runtime).
49
+ */
50
+ export declare class AgentMailError extends Error {
51
+ readonly tool: string;
52
+ readonly code?: number;
53
+ readonly data?: unknown;
54
+ constructor(message: string, tool: string, code?: number, data?: unknown);
55
+ }
56
+ /**
57
+ * Factory function to create AgentMailError
58
+ * Use this instead of `new AgentMailError()` for compatibility
59
+ */
60
+ export declare function createAgentMailError(message: string, tool: string, code?: number, data?: unknown): AgentMailError;
61
+ export declare class AgentMailNotInitializedError extends Error {
62
+ constructor();
63
+ }
64
+ export declare class FileReservationConflictError extends Error {
65
+ readonly conflicts: Array<{
66
+ path: string;
67
+ holders: string[];
68
+ }>;
69
+ constructor(message: string, conflicts: Array<{
70
+ path: string;
71
+ holders: string[];
72
+ }>);
73
+ }
74
+ export declare class RateLimitExceededError extends Error {
75
+ readonly endpoint: string;
76
+ readonly remaining: number;
77
+ readonly resetAt: number;
78
+ constructor(endpoint: string, remaining: number, resetAt: number);
79
+ }
80
+ /**
81
+ * Check if the server is responding to health checks
82
+ */
83
+ declare function isServerHealthy(): Promise<boolean>;
84
+ /**
85
+ * Test if the server can handle a basic MCP call
86
+ * This catches cases where health is OK but MCP is broken
87
+ */
88
+ declare function isServerFunctional(): Promise<boolean>;
89
+ /**
90
+ * Attempt to restart the Agent Mail server
91
+ *
92
+ * Finds the running process, kills it, and starts a new one.
93
+ * Returns true if restart was successful.
94
+ */
95
+ declare function restartServer(): Promise<boolean>;
96
+ /**
97
+ * Reset recovery state (for testing)
98
+ */
99
+ export declare function resetRecoveryState(): void;
100
+ /**
101
+ * Check if an error indicates the project was not found
102
+ *
103
+ * This happens when Agent Mail server restarts and loses project registrations.
104
+ * The fix is to re-register the project and retry the operation.
105
+ */
106
+ export declare function isProjectNotFoundError(error: unknown): boolean;
107
+ /**
108
+ * Check if an error indicates the agent was not found
109
+ *
110
+ * Similar to project not found - server restart loses agent registrations.
111
+ */
112
+ export declare function isAgentNotFoundError(error: unknown): boolean;
113
+ /**
114
+ * Reset availability cache (for testing)
115
+ */
116
+ export declare function resetAgentMailCache(): void;
117
+ /**
118
+ * Reset rate limiter (for testing)
119
+ */
120
+ export declare function resetRateLimiterCache(): Promise<void>;
121
+ /**
122
+ * Call an Agent Mail MCP tool with retry and auto-restart
123
+ *
124
+ * Features:
125
+ * - Exponential backoff with jitter on retryable errors
126
+ * - Auto-restart server after consecutive failures
127
+ * - Timeout handling per request
128
+ *
129
+ * Handles both direct results (mock server) and wrapped results (real server).
130
+ * Real Agent Mail returns: { content: [...], structuredContent: {...} }
131
+ */
132
+ export declare function mcpCall<T>(toolName: string, args: Record<string, unknown>): Promise<T>;
133
+ /**
134
+ * MCP call with automatic project/agent re-registration on "not found" errors
135
+ *
136
+ * This is the self-healing wrapper that handles Agent Mail server restarts.
137
+ * When the server restarts, it loses all project and agent registrations.
138
+ * This wrapper detects those errors and automatically re-registers before retrying.
139
+ *
140
+ * Use this instead of raw mcpCall when you have project_key and agent_name context.
141
+ *
142
+ * @param toolName - The MCP tool to call
143
+ * @param args - Arguments including project_key and optionally agent_name
144
+ * @param options - Optional configuration for re-registration
145
+ * @returns The result of the MCP call
146
+ */
147
+ export declare function mcpCallWithAutoInit<T>(toolName: string, args: Record<string, unknown> & {
148
+ project_key: string;
149
+ agent_name?: string;
150
+ }, options?: {
151
+ /** Task description for agent re-registration */
152
+ taskDescription?: string;
153
+ /** Max re-registration attempts (default: 1) */
154
+ maxReregistrationAttempts?: number;
155
+ }): Promise<T>;
156
+ /**
157
+ * Get Agent Mail state for a session, or throw if not initialized
158
+ *
159
+ * Checks in-memory cache first, then falls back to disk storage.
160
+ * This allows CLI invocations to share state across calls.
161
+ */
162
+ declare function requireState(sessionID: string): AgentMailState;
163
+ /**
164
+ * Store Agent Mail state for a session
165
+ *
166
+ * Saves to both in-memory cache and disk for CLI persistence.
167
+ */
168
+ declare function setState(sessionID: string, state: AgentMailState): void;
169
+ /**
170
+ * Get state if exists (for cleanup hooks)
171
+ *
172
+ * Checks in-memory cache first, then falls back to disk storage.
173
+ */
174
+ declare function getState(sessionID: string): AgentMailState | undefined;
175
+ /**
176
+ * Clear state for a session
177
+ *
178
+ * Removes from both in-memory cache and disk.
179
+ */
180
+ declare function clearState(sessionID: string): void;
181
+ /**
182
+ * Initialize Agent Mail session
183
+ */
184
+ export declare const agentmail_init: {
185
+ description: string;
186
+ args: {
187
+ project_path: z.ZodOptional<z.ZodString>;
188
+ agent_name: z.ZodOptional<z.ZodString>;
189
+ task_description: z.ZodOptional<z.ZodString>;
190
+ };
191
+ execute(args: {
192
+ project_path?: string | undefined;
193
+ agent_name?: string | undefined;
194
+ task_description?: string | undefined;
195
+ }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
196
+ };
197
+ /**
198
+ * Send a message to other agents
199
+ */
200
+ export declare const agentmail_send: {
201
+ description: string;
202
+ args: {
203
+ to: z.ZodArray<z.ZodString>;
204
+ subject: z.ZodString;
205
+ body: z.ZodString;
206
+ thread_id: z.ZodOptional<z.ZodString>;
207
+ importance: z.ZodOptional<z.ZodEnum<{
208
+ low: "low";
209
+ normal: "normal";
210
+ high: "high";
211
+ urgent: "urgent";
212
+ }>>;
213
+ ack_required: z.ZodOptional<z.ZodBoolean>;
214
+ };
215
+ execute(args: {
216
+ to: string[];
217
+ subject: string;
218
+ body: string;
219
+ thread_id?: string | undefined;
220
+ importance?: "low" | "normal" | "high" | "urgent" | undefined;
221
+ ack_required?: boolean | undefined;
222
+ }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
223
+ };
224
+ /**
225
+ * Fetch inbox (CONTEXT-SAFE: bodies excluded, limit 5)
226
+ */
227
+ export declare const agentmail_inbox: {
228
+ description: string;
229
+ args: {
230
+ limit: z.ZodOptional<z.ZodNumber>;
231
+ urgent_only: z.ZodOptional<z.ZodBoolean>;
232
+ since_ts: z.ZodOptional<z.ZodString>;
233
+ };
234
+ execute(args: {
235
+ limit?: number | undefined;
236
+ urgent_only?: boolean | undefined;
237
+ since_ts?: string | undefined;
238
+ }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
239
+ };
240
+ /**
241
+ * Read a single message body by ID
242
+ */
243
+ export declare const agentmail_read_message: {
244
+ description: string;
245
+ args: {
246
+ message_id: z.ZodNumber;
247
+ };
248
+ execute(args: {
249
+ message_id: number;
250
+ }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
251
+ };
252
+ /**
253
+ * Summarize a thread (PREFERRED over fetching all messages)
254
+ */
255
+ export declare const agentmail_summarize_thread: {
256
+ description: string;
257
+ args: {
258
+ thread_id: z.ZodString;
259
+ include_examples: z.ZodOptional<z.ZodBoolean>;
260
+ };
261
+ execute(args: {
262
+ thread_id: string;
263
+ include_examples?: boolean | undefined;
264
+ }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
265
+ };
266
+ /**
267
+ * Reserve file paths for exclusive editing
268
+ */
269
+ export declare const agentmail_reserve: {
270
+ description: string;
271
+ args: {
272
+ paths: z.ZodArray<z.ZodString>;
273
+ ttl_seconds: z.ZodNumber;
274
+ exclusive: z.ZodOptional<z.ZodBoolean>;
275
+ reason: z.ZodOptional<z.ZodString>;
276
+ };
277
+ execute(args: {
278
+ paths: string[];
279
+ ttl_seconds: number;
280
+ exclusive?: boolean | undefined;
281
+ reason?: string | undefined;
282
+ }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
283
+ };
284
+ /**
285
+ * Release file reservations
286
+ */
287
+ export declare const agentmail_release: {
288
+ description: string;
289
+ args: {
290
+ paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
291
+ reservation_ids: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
292
+ };
293
+ execute(args: {
294
+ paths?: string[] | undefined;
295
+ reservation_ids?: number[] | undefined;
296
+ }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
297
+ };
298
+ /**
299
+ * Acknowledge a message
300
+ */
301
+ export declare const agentmail_ack: {
302
+ description: string;
303
+ args: {
304
+ message_id: z.ZodNumber;
305
+ };
306
+ execute(args: {
307
+ message_id: number;
308
+ }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
309
+ };
310
+ /**
311
+ * Search messages
312
+ */
313
+ export declare const agentmail_search: {
314
+ description: string;
315
+ args: {
316
+ query: z.ZodString;
317
+ limit: z.ZodOptional<z.ZodNumber>;
318
+ };
319
+ execute(args: {
320
+ query: string;
321
+ limit?: number | undefined;
322
+ }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
323
+ };
324
+ /**
325
+ * Check Agent Mail health
326
+ */
327
+ export declare const agentmail_health: {
328
+ description: string;
329
+ args: {};
330
+ execute(args: Record<string, never>, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
331
+ };
332
+ /**
333
+ * Manually restart Agent Mail server
334
+ *
335
+ * Use when server is in bad state (health OK but MCP failing).
336
+ * This kills the existing process and starts a fresh one.
337
+ */
338
+ export declare const agentmail_restart: {
339
+ description: string;
340
+ args: {
341
+ force: z.ZodOptional<z.ZodBoolean>;
342
+ };
343
+ execute(args: {
344
+ force?: boolean | undefined;
345
+ }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
346
+ };
347
+ export declare const agentMailTools: {
348
+ agentmail_init: {
349
+ description: string;
350
+ args: {
351
+ project_path: z.ZodOptional<z.ZodString>;
352
+ agent_name: z.ZodOptional<z.ZodString>;
353
+ task_description: z.ZodOptional<z.ZodString>;
354
+ };
355
+ execute(args: {
356
+ project_path?: string | undefined;
357
+ agent_name?: string | undefined;
358
+ task_description?: string | undefined;
359
+ }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
360
+ };
361
+ agentmail_send: {
362
+ description: string;
363
+ args: {
364
+ to: z.ZodArray<z.ZodString>;
365
+ subject: z.ZodString;
366
+ body: z.ZodString;
367
+ thread_id: z.ZodOptional<z.ZodString>;
368
+ importance: z.ZodOptional<z.ZodEnum<{
369
+ low: "low";
370
+ normal: "normal";
371
+ high: "high";
372
+ urgent: "urgent";
373
+ }>>;
374
+ ack_required: z.ZodOptional<z.ZodBoolean>;
375
+ };
376
+ execute(args: {
377
+ to: string[];
378
+ subject: string;
379
+ body: string;
380
+ thread_id?: string | undefined;
381
+ importance?: "low" | "normal" | "high" | "urgent" | undefined;
382
+ ack_required?: boolean | undefined;
383
+ }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
384
+ };
385
+ agentmail_inbox: {
386
+ description: string;
387
+ args: {
388
+ limit: z.ZodOptional<z.ZodNumber>;
389
+ urgent_only: z.ZodOptional<z.ZodBoolean>;
390
+ since_ts: z.ZodOptional<z.ZodString>;
391
+ };
392
+ execute(args: {
393
+ limit?: number | undefined;
394
+ urgent_only?: boolean | undefined;
395
+ since_ts?: string | undefined;
396
+ }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
397
+ };
398
+ agentmail_read_message: {
399
+ description: string;
400
+ args: {
401
+ message_id: z.ZodNumber;
402
+ };
403
+ execute(args: {
404
+ message_id: number;
405
+ }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
406
+ };
407
+ agentmail_summarize_thread: {
408
+ description: string;
409
+ args: {
410
+ thread_id: z.ZodString;
411
+ include_examples: z.ZodOptional<z.ZodBoolean>;
412
+ };
413
+ execute(args: {
414
+ thread_id: string;
415
+ include_examples?: boolean | undefined;
416
+ }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
417
+ };
418
+ agentmail_reserve: {
419
+ description: string;
420
+ args: {
421
+ paths: z.ZodArray<z.ZodString>;
422
+ ttl_seconds: z.ZodNumber;
423
+ exclusive: z.ZodOptional<z.ZodBoolean>;
424
+ reason: z.ZodOptional<z.ZodString>;
425
+ };
426
+ execute(args: {
427
+ paths: string[];
428
+ ttl_seconds: number;
429
+ exclusive?: boolean | undefined;
430
+ reason?: string | undefined;
431
+ }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
432
+ };
433
+ agentmail_release: {
434
+ description: string;
435
+ args: {
436
+ paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
437
+ reservation_ids: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
438
+ };
439
+ execute(args: {
440
+ paths?: string[] | undefined;
441
+ reservation_ids?: number[] | undefined;
442
+ }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
443
+ };
444
+ agentmail_ack: {
445
+ description: string;
446
+ args: {
447
+ message_id: z.ZodNumber;
448
+ };
449
+ execute(args: {
450
+ message_id: number;
451
+ }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
452
+ };
453
+ agentmail_search: {
454
+ description: string;
455
+ args: {
456
+ query: z.ZodString;
457
+ limit: z.ZodOptional<z.ZodNumber>;
458
+ };
459
+ execute(args: {
460
+ query: string;
461
+ limit?: number | undefined;
462
+ }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
463
+ };
464
+ agentmail_health: {
465
+ description: string;
466
+ args: {};
467
+ execute(args: Record<string, never>, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
468
+ };
469
+ agentmail_restart: {
470
+ description: string;
471
+ args: {
472
+ force: z.ZodOptional<z.ZodBoolean>;
473
+ };
474
+ execute(args: {
475
+ force?: boolean | undefined;
476
+ }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
477
+ };
478
+ };
479
+ export { requireState, setState, getState, clearState, sessionStates, AGENT_MAIL_URL, MAX_INBOX_LIMIT, isServerHealthy, isServerFunctional, restartServer, RETRY_CONFIG, RECOVERY_CONFIG, };
480
+ //# sourceMappingURL=agent-mail.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agent-mail.d.ts","sourceRoot":"","sources":["../src/agent-mail.ts"],"names":[],"mappings":"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"}