opencode-swarm-plugin 0.12.4 → 0.12.6

package/dist/plugin.js

@@ -21560,15 +21560,15 @@ var BeadDependencySchema = exports_external.object({
   type: exports_external.enum(["blocks", "blocked-by", "related", "discovered-from"])
 });
 var BeadSchema = exports_external.object({
-  id: exports_external.string().regex(/^[a-z0-9-]+-[a-z0-9]+(\.\d+)?$/, "Invalid bead ID format"),
+  id: exports_external.string().regex(/^[a-z0-9]+(-[a-z0-9]+)+(\.\d+)?$/, "Invalid bead ID format"),
   title: exports_external.string().min(1, "Title required"),
   description: exports_external.string().optional().default(""),
   status: BeadStatusSchema.default("open"),
   priority: exports_external.number().int().min(0).max(3).default(2),
   issue_type: BeadTypeSchema.default("task"),
-  created_at: exports_external.string(),
-  updated_at: exports_external.string().optional(),
-  closed_at: exports_external.string().optional(),
+  created_at: exports_external.string().datetime({ offset: true }),
+  updated_at: exports_external.string().datetime({ offset: true }).optional(),
+  closed_at: exports_external.string().datetime({ offset: true }).optional(),
   parent_id: exports_external.string().optional(),
   dependencies: exports_external.array(BeadDependencySchema).optional().default([]),
   metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
@@ -21641,7 +21641,7 @@ var EvaluationSchema = exports_external.object({
   criteria: exports_external.record(exports_external.string(), CriterionEvaluationSchema),
   overall_feedback: exports_external.string(),
   retry_suggestion: exports_external.string().nullable(),
-  timestamp: exports_external.string().optional()
+  timestamp: exports_external.string().datetime({ offset: true }).optional()
 });
 var DEFAULT_CRITERIA = [
   "type_safe",
@@ -21659,7 +21659,7 @@ var WeightedEvaluationSchema = exports_external.object({
   criteria: exports_external.record(exports_external.string(), WeightedCriterionEvaluationSchema),
   overall_feedback: exports_external.string(),
   retry_suggestion: exports_external.string().nullable(),
-  timestamp: exports_external.string().optional(),
+  timestamp: exports_external.string().datetime({ offset: true }).optional(),
   average_weight: exports_external.number().min(0).max(1).optional(),
   raw_score: exports_external.number().min(0).max(1).optional(),
   weighted_score: exports_external.number().min(0).max(1).optional()
@@ -21732,7 +21732,7 @@ var SwarmSpawnResultSchema = exports_external.object({
   coordinator_name: exports_external.string(),
   thread_id: exports_external.string(),
   agents: exports_external.array(SpawnedAgentSchema),
-  started_at: exports_external.string()
+  started_at: exports_external.string().datetime({ offset: true })
 });
 var AgentProgressSchema = exports_external.object({
   bead_id: exports_external.string(),
@@ -21742,7 +21742,7 @@ var AgentProgressSchema = exports_external.object({
   message: exports_external.string().optional(),
   files_touched: exports_external.array(exports_external.string()).optional(),
   blockers: exports_external.array(exports_external.string()).optional(),
-  timestamp: exports_external.string()
+  timestamp: exports_external.string().datetime({ offset: true })
 });
 var SwarmStatusSchema = exports_external.object({
   epic_id: exports_external.string(),
@@ -21752,7 +21752,7 @@ var SwarmStatusSchema = exports_external.object({
   failed: exports_external.number().int().min(0),
   blocked: exports_external.number().int().min(0),
   agents: exports_external.array(SpawnedAgentSchema),
-  last_update: exports_external.string()
+  last_update: exports_external.string().datetime({ offset: true })
 });
 // src/beads.ts
 class BeadError extends Error {
@@ -21890,18 +21890,32 @@ var beads_create_epic = tool({
       };
       return JSON.stringify(result, null, 2);
     } catch (error45) {
-      const rollbackHint = created.map((b) => `bd close ${b.id} --reason "Rollback partial epic"`).join(`
-`);
-      const result = {
-        success: false,
-        epic: created[0] || {},
-        subtasks: created.slice(1),
-        rollback_hint: rollbackHint
-      };
-      return JSON.stringify({
-        ...result,
-        error: error45 instanceof Error ? error45.message : String(error45)
-      }, null, 2);
+      const rollbackCommands = [];
+      for (const bead of created) {
+        try {
+          const closeCmd = [
+            "bd",
+            "close",
+            bead.id,
+            "--reason",
+            "Rollback partial epic",
+            "--json"
+          ];
+          await Bun.$`${closeCmd}`.quiet().nothrow();
+          rollbackCommands.push(`bd close ${bead.id} --reason "Rollback partial epic"`);
+        } catch (rollbackError) {
+          console.error(`Failed to rollback bead ${bead.id}:`, rollbackError);
+        }
+      }
+      const errorMsg = error45 instanceof Error ? error45.message : String(error45);
+      const rollbackInfo = rollbackCommands.length > 0 ? `
+
+Rolled back ${rollbackCommands.length} bead(s):
+${rollbackCommands.join(`
+`)}` : `
+
+No beads to rollback.`;
+      throw new BeadError(`Epic creation failed: ${errorMsg}${rollbackInfo}`, "beads_create_epic", 1);
     }
   }
 });
@@ -22028,17 +22042,22 @@ var beads_sync = tool({
   },
   async execute(args, ctx) {
     const autoPull = args.auto_pull ?? true;
+    const TIMEOUT_MS = 30000;
+    const withTimeout = async (promise2, timeoutMs, operation) => {
+      const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new BeadError(`Operation timed out after ${timeoutMs}ms`, operation)), timeoutMs));
+      return Promise.race([promise2, timeoutPromise]);
+    };
     if (autoPull) {
-      const pullResult = await Bun.$`git pull --rebase`.quiet().nothrow();
+      const pullResult = await withTimeout(Bun.$`git pull --rebase`.quiet().nothrow(), TIMEOUT_MS, "git pull --rebase");
       if (pullResult.exitCode !== 0) {
         throw new BeadError(`Failed to pull: ${pullResult.stderr.toString()}`, "git pull --rebase", pullResult.exitCode);
       }
     }
-    const syncResult = await Bun.$`bd sync`.quiet().nothrow();
+    const syncResult = await withTimeout(Bun.$`bd sync`.quiet().nothrow(), TIMEOUT_MS, "bd sync");
     if (syncResult.exitCode !== 0) {
       throw new BeadError(`Failed to sync beads: ${syncResult.stderr.toString()}`, "bd sync", syncResult.exitCode);
     }
-    const pushResult = await Bun.$`git push`.quiet().nothrow();
+    const pushResult = await withTimeout(Bun.$`git push`.quiet().nothrow(), TIMEOUT_MS, "git push");
     if (pushResult.exitCode !== 0) {
       throw new BeadError(`Failed to push: ${pushResult.stderr.toString()}`, "git push", pushResult.exitCode);
     }
@@ -22321,9 +22340,11 @@ function getLimitsForEndpoint(endpoint) {
   const upperEndpoint = endpoint.toUpperCase();
   const perMinuteEnv = process.env[`OPENCODE_RATE_LIMIT_${upperEndpoint}_PER_MIN`];
   const perHourEnv = process.env[`OPENCODE_RATE_LIMIT_${upperEndpoint}_PER_HOUR`];
+  const parsedPerMinute = perMinuteEnv ? parseInt(perMinuteEnv, 10) : NaN;
+  const parsedPerHour = perHourEnv ? parseInt(perHourEnv, 10) : NaN;
   return {
-    perMinute: perMinuteEnv ? parseInt(perMinuteEnv, 10) : defaults.perMinute,
-    perHour: perHourEnv ? parseInt(perHourEnv, 10) : defaults.perHour
+    perMinute: Number.isNaN(parsedPerMinute) ? defaults.perMinute : parsedPerMinute,
+    perHour: Number.isNaN(parsedPerHour) ? defaults.perHour : parsedPerHour
   };
 }
 
@@ -22362,6 +22383,7 @@ class RedisRateLimiter {
     const pipeline = this.redis.pipeline();
     pipeline.zremrangebyscore(key, 0, windowStart);
     pipeline.zcard(key);
+    pipeline.zrange(key, 0, 0, "WITHSCORES");
     const results = await pipeline.exec();
     if (!results) {
       return { allowed: true, remaining: limit, resetAt: now + windowDuration };
@@ -22371,7 +22393,7 @@ class RedisRateLimiter {
     const allowed = count < limit;
     let resetAt = now + windowDuration;
     if (!allowed) {
-      const oldest = await this.redis.zrange(key, 0, 0, "WITHSCORES");
+      const oldest = results[2]?.[1] || [];
       if (oldest.length >= 2) {
         const oldestTimestamp = parseInt(oldest[1], 10);
         resetAt = oldestTimestamp + windowDuration;
@@ -22612,8 +22634,11 @@ function saveSessionState(sessionID, state) {
     }
     const path = getSessionStatePath(sessionID);
     writeFileSync(path, JSON.stringify(state, null, 2));
+    return true;
   } catch (error45) {
-    console.warn(`[agent-mail] Could not save session state: ${error45}`);
+    console.error(`[agent-mail] CRITICAL: Could not save session state: ${error45}`);
+    console.error(`[agent-mail] Session state will not persist across CLI invocations!`);
+    return false;
   }
 }
 var sessionStates = new Map;
@@ -22893,6 +22918,7 @@ async function mcpCall(toolName, args) {
     } catch (error45) {
       lastError = error45 instanceof Error ? error45 : new Error(String(error45));
       consecutiveFailures++;
+      const retryable = isRetryableError(error45);
       if (consecutiveFailures >= RECOVERY_CONFIG.failureThreshold && RECOVERY_CONFIG.enabled) {
         console.warn(`[agent-mail] ${consecutiveFailures} consecutive failures, checking server health...`);
         const healthy = await isServerFunctional();
@@ -22901,12 +22927,14 @@ async function mcpCall(toolName, args) {
           const restarted = await restartServer();
           if (restarted) {
             agentMailAvailable = null;
-            attempt--;
-            continue;
+            if (retryable) {
+              attempt--;
+              continue;
+            }
           }
         }
       }
-      if (!isRetryableError(error45)) {
+      if (!retryable) {
         console.warn(`[agent-mail] Non-retryable error for ${toolName}: ${lastError.message}`);
         throw lastError;
       }
@@ -23039,12 +23067,12 @@ var agentmail_read_message = tool({
     const messages = await mcpCall("fetch_inbox", {
       project_key: state.projectKey,
       agent_name: state.agentName,
-      limit: 1,
+      limit: 50,
       include_bodies: true
     });
     const message = messages.find((m) => m.id === args.message_id);
     if (!message) {
-      return `Message ${args.message_id} not found`;
+      return `Message ${args.message_id} not found in recent 50 messages. Try using agentmail_search to locate it.`;
     }
     await recordRateLimitedRequest(state.agentName, "read_message");
     return JSON.stringify(message, null, 2);
@@ -24518,6 +24546,13 @@ var swarm_validate_decomposition = tool({
       for (let i = 0;i < validated.subtasks.length; i++) {
         const deps = validated.subtasks[i].dependencies;
         for (const dep of deps) {
+          if (dep < 0 || dep >= validated.subtasks.length) {
+            return JSON.stringify({
+              valid: false,
+              error: `Invalid dependency: subtask ${i} depends on ${dep}, but only ${validated.subtasks.length} subtasks exist (indices 0-${validated.subtasks.length - 1})`,
+              hint: "Dependency index is out of bounds"
+            }, null, 2);
+          }
           if (dep >= i) {
             return JSON.stringify({
               valid: false,

package/examples/commands/swarm.md

@@ -2,282 +2,117 @@
 description: Decompose task into parallel subtasks and coordinate agents
 ---
 
-You are a swarm coordinator. Take a complex task, break it into beads, and unleash parallel agents.
+You are a swarm coordinator. Decompose the task into beads and spawn parallel agents.
 
-## Usage
+## Task
 
-```
-/swarm <task description or bead-id>
-/swarm --to-main <task>  # Skip PR, push directly to main (use sparingly)
-/swarm --no-sync <task>  # Skip mid-task context sync (for simple independent tasks)
-```
-
-**Default behavior: Feature branch + PR with context sync.** All swarm work goes to a feature branch, agents share context mid-task, and creates a PR for review.
-
-## Step 1: Initialize Session
-
-Use the plugin's agent-mail tools to register:
-
-```
-agentmail_init with project_path=$PWD, task_description="Swarm coordinator: <task>"
-```
-
-This returns your agent name and session state. Remember it.
-
-## Step 2: Create Feature Branch
-
-**CRITICAL: Never push directly to main.**
-
-```bash
-# Create branch from bead ID or task name
-git checkout -b swarm/<bead-id>  # e.g., swarm/trt-buddy-d7d
-# Or for ad-hoc tasks:
-git checkout -b swarm/<short-description>  # e.g., swarm/contextual-checkins
-
-git push -u origin HEAD
-```
-
-## Step 3: Understand the Task
-
-If given a bead-id:
+$ARGUMENTS
 
-```
-beads_query with id=<bead-id>
-```
+## Flags (parse from task above)
 
-If given a description, analyze it to understand scope.
+- `--to-main` - Push directly to main, skip PR
+- `--no-sync` - Skip mid-task context sharing
 
-## Step 4: Select Strategy & Decompose
+**Default: Feature branch + PR with context sync.**
 
-### Option A: Use the Planner Agent (Recommended)
+## Workflow
 
-Spawn the `@swarm-planner` agent to handle decomposition:
+### 1. Initialize
 
 ```
-Task(
-  subagent_type="general",
-  description="Plan swarm decomposition",
-  prompt="You are @swarm-planner. Decompose this task: <task description>. Use swarm_select_strategy and swarm_plan_prompt to guide your decomposition. Return ONLY valid BeadTree JSON."
-)
+agentmail_init(project_path="$PWD", task_description="Swarm: <task summary>")
 ```
 
-### Option B: Manual Decomposition
-
-1. **Select strategy**:
+### 2. Create Feature Branch (unless --to-main)
 
-```
-swarm_select_strategy with task="<task description>"
-```
-
-2. **Get planning prompt**:
-
-```
-swarm_plan_prompt with task="<task description>", strategy="<selected or auto>"
+```bash
+git checkout -b swarm/<short-task-name>
+git push -u origin HEAD
 ```
 
-3. **Create decomposition** following the prompt guidelines
+### 3. Decompose Task
 
-4. **Validate**:
+Use strategy selection and planning:
 
 ```
-swarm_validate_decomposition with response="<your BeadTree JSON>"
+swarm_select_strategy(task="<the task>")
+swarm_plan_prompt(task="<the task>", strategy="<auto or selected>")
 ```
 
-### Create Beads
-
-Once you have a valid BeadTree:
+Follow the prompt to create a BeadTree, then validate:
 
 ```
-beads_create_epic with epic_title="<parent task>", subtasks=[{title, description, files, priority}...]
+swarm_validate_decomposition(response="<your BeadTree JSON>")
 ```
 
-**Decomposition rules:**
-
-- Each bead should be completable by one agent
-- Beads should be independent (parallelizable) where possible
-- If there are dependencies, order them in the subtasks array
-- Aim for 3-7 beads per swarm (too few = not parallel, too many = coordination overhead)
-
-## Step 5: Reserve Files
-
-For each subtask, reserve the files it will touch:
+### 4. Create Beads
 
 ```
-agentmail_reserve with paths=[<files>], reason="<bead-id>: <brief description>"
+beads_create_epic(epic_title="<task>", subtasks=[{title, files, priority}...])
 ```
 
-**Conflict prevention:**
-
-- No two agents should edit the same file
-- If overlap exists, merge beads or sequence them
-
-## Step 6: Spawn the Swarm
-
-**CRITICAL: Spawn ALL agents in a SINGLE message with multiple Task calls.**
-
-Use the prompt generator for each subtask:
+Rules:
 
-```
-swarm_spawn_subtask with bead_id="<bead-id>", epic_id="<epic-id>", subtask_title="<title>", subtask_description="<description>", files=[<files>], shared_context="Branch: swarm/<id>, sync_enabled: true"
-```
+- Each bead completable by one agent
+- Independent where possible (parallelizable)
+- 3-7 beads per swarm
 
-Then spawn agents with the generated prompts:
+### 5. Reserve Files
 
 ```
-Task(
-  subagent_type="general",
-  description="Swarm worker: <bead-title>",
-  prompt="<output from swarm_spawn_subtask>"
-)
+agentmail_reserve(paths=[<files>], reason="<bead-id>: <description>")
 ```
 
-Spawn ALL agents in parallel in a single response.
-
-## Step 7: Monitor Progress (unless --no-sync)
+No two agents should edit the same file.
 
-Check swarm status:
+### 6. Spawn Agents
 
-```
-swarm_status with epic_id="<parent-bead-id>"
-```
+**CRITICAL: Spawn ALL in a SINGLE message with multiple Task calls.**
 
-Monitor inbox for progress updates:
+For each subtask:
 
 ```
-agentmail_inbox
+swarm_spawn_subtask(bead_id="<id>", epic_id="<epic>", subtask_title="<title>", files=[...])
 ```
 
-**When you receive progress updates:**
-
-1. **Review decisions made** - Are agents making compatible choices?
-2. **Check for pattern conflicts** - Different approaches to the same problem?
-3. **Identify shared concerns** - Common blockers or discoveries?
-
-**If you spot incompatibilities, broadcast shared context:**
+Then spawn:
 
 ```
-agentmail_send with to=["*"], subject="Coordinator Update", body="<guidance>", thread_id="<epic-id>", importance="high"
+Task(subagent_type="swarm-worker", description="<bead-title>", prompt="<from swarm_spawn_subtask>")
 ```
 
-## Step 8: Collect Results
-
-When agents complete, they send completion messages. Summarize the thread:
+### 7. Monitor (unless --no-sync)
 
 ```
-agentmail_summarize_thread with thread_id="<epic-id>"
+swarm_status(epic_id="<epic-id>")
+agentmail_inbox()
 ```
 
-## Step 9: Complete Swarm
-
-Use the swarm completion tool:
+If incompatibilities spotted, broadcast:
 
 ```
-swarm_complete with project_key=$PWD, agent_name=<YOUR_NAME>, bead_id="<epic-id>", summary="<what was accomplished>", files_touched=[<all files>]
+agentmail_send(to=["*"], subject="Coordinator Update", body="<guidance>", importance="high")
 ```
 
-This:
-
-- Runs [UBS (Ultimate Bug Scanner)](https://github.com/Dicklesworthstone/ultimate_bug_scanner) on touched files to detect bugs before completion
-- Releases file reservations
-- Closes the bead
-- Records outcome for learning
-
-> **Note:** UBS is optional but recommended. If not installed, swarm completion proceeds with a warning that manual review is advised. Install via:
-> ```bash
-> curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh" | bash
-> ```
-> See the [UBS repo](https://github.com/Dicklesworthstone/ultimate_bug_scanner) for more options (Docker, Nix, etc.).
-
-Then sync beads:
+### 8. Complete
 
 ```
-beads_sync
+swarm_complete(project_key="$PWD", agent_name="<your-name>", bead_id="<epic-id>", summary="<done>", files_touched=[...])
+beads_sync()
 ```
 
-## Step 10: Create PR
+### 9. Create PR (unless --to-main)
 
 ```bash
-gh pr create --title "feat: <epic title>" --body "$(cat <<'EOF'
-## Summary
-<1-3 bullet points from swarm results>
-
-## Beads Completed
-- <bead-id>: <summary>
-- <bead-id>: <summary>
-
-## Files Changed
-<aggregate list>
-
-## Testing
-- [ ] Type check passes
-- [ ] Tests pass (if applicable)
-EOF
-)"
-```
-
-Report summary:
-
-```markdown
-## Swarm Complete: <task>
-
-### PR: #<number>
-
-### Agents Spawned: N
-
-### Beads Closed: N
-
-### Work Completed
-
-- [bead-id]: [summary]
-
-### Files Changed
-
-- [aggregate list]
+gh pr create --title "feat: <epic title>" --body "## Summary\n<bullets>\n\n## Beads\n<list>"
 ```
 
-## Failure Handling
-
-If an agent fails:
-
-- Check its messages: `agentmail_inbox`
-- The bead remains in-progress
-- Manually investigate or re-spawn
-
-If file conflicts occur:
-
-- Agent Mail reservations should prevent this
-- If it happens, one agent needs to wait
-
-## Direct-to-Main Mode (--to-main)
-
-Only use when explicitly requested. Skips branch/PR:
-
-- Trivial fixes across many files
-- Automated migrations with high confidence
-- User explicitly says "push to main"
-
-## No-Sync Mode (--no-sync)
-
-Skip mid-task context sharing when tasks are truly independent:
-
-- Simple mechanical changes (find/replace, formatting, lint fixes)
-- Tasks with zero integration points
-- Completely separate feature areas with no shared types
-
-In this mode:
-
-- Agents skip the mid-task progress message
-- Coordinator skips Step 7 (monitoring)
-- Faster execution, less coordination overhead
-
-**Default is sync ON** - prefer sharing context. Use `--no-sync` deliberately.
-
 ## Strategy Reference
 
-| Strategy          | Best For                    | Auto-Detected Keywords                         |
-| ----------------- | --------------------------- | ---------------------------------------------- |
-| **file-based**    | Refactoring, migrations     | refactor, migrate, rename, update all, convert |
-| **feature-based** | New features, functionality | add, implement, build, create, feature, new    |
-| **risk-based**    | Bug fixes, security         | fix, bug, security, critical, urgent, hotfix   |
+| Strategy      | Best For                | Keywords                              |
+| ------------- | ----------------------- | ------------------------------------- |
+| file-based    | Refactoring, migrations | refactor, migrate, rename, update all |
+| feature-based | New features            | add, implement, build, create, new    |
+| risk-based    | Bug fixes, security     | fix, bug, security, critical, urgent  |
 
-Use `swarm_select_strategy` to see which strategy is recommended and why.
+Begin decomposition now.

package/package.json

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

package/src/agent-mail.ts

@@ -107,8 +107,10 @@ function loadSessionState(sessionID: string): AgentMailState | null {
 
 /**
  * Save session state to disk
+ *
+ * @returns true if save succeeded, false if failed
  */
-function saveSessionState(sessionID: string, state: AgentMailState): void {
+function saveSessionState(sessionID: string, state: AgentMailState): boolean {
   try {
     // Ensure directory exists
     if (!existsSync(SESSION_STATE_DIR)) {
@@ -116,9 +118,16 @@ function saveSessionState(sessionID: string, state: AgentMailState): void {
     }
     const path = getSessionStatePath(sessionID);
     writeFileSync(path, JSON.stringify(state, null, 2));
+    return true;
   } catch (error) {
     // Non-fatal - state just won't persist
-    console.warn(`[agent-mail] Could not save session state: ${error}`);
+    console.error(
+      `[agent-mail] CRITICAL: Could not save session state: ${error}`,
+    );
+    console.error(
+      `[agent-mail] Session state will not persist across CLI invocations!`,
+    );
+    return false;
   }
 }
 
@@ -718,6 +727,9 @@ export async function mcpCall<T>(
       // Track consecutive failures
       consecutiveFailures++;
 
+      // Check if error is retryable FIRST
+      const retryable = isRetryableError(error);
+
       // Check if we should attempt server restart
       if (
         consecutiveFailures >= RECOVERY_CONFIG.failureThreshold &&
@@ -734,15 +746,18 @@ export async function mcpCall<T>(
           if (restarted) {
             // Reset availability cache since server restarted
             agentMailAvailable = null;
-            // Don't count this attempt against retries - try again
-            attempt--;
-            continue;
+            // Only retry if the error was retryable in the first place
+            if (retryable) {
+              // Don't count this attempt against retries - try again
+              attempt--;
+              continue;
+            }
           }
         }
       }
 
-      // Check if error is retryable
-      if (!isRetryableError(error)) {
+      // If error is not retryable, throw immediately
+      if (!retryable) {
         console.warn(
           `[agent-mail] Non-retryable error for ${toolName}: ${lastError.message}`,
         );
@@ -1006,18 +1021,18 @@ export const agentmail_read_message = tool({
       message_id: args.message_id,
     });
 
-    // Fetch with body - we need to use fetch_inbox with specific message
-    // Since there's no get_message, we'll use search
+    // Fetch with body - fetch more messages to find the requested one
+    // Since there's no get_message endpoint, we need to fetch a reasonable batch
     const messages = await mcpCall<MessageHeader[]>("fetch_inbox", {
       project_key: state.projectKey,
       agent_name: state.agentName,
-      limit: 1,
+      limit: 50, // Fetch more messages to increase chance of finding the target
       include_bodies: true, // Only for single message fetch
     });
 
     const message = messages.find((m) => m.id === args.message_id);
     if (!message) {
-      return `Message ${args.message_id} not found`;
+      return `Message ${args.message_id} not found in recent 50 messages. Try using agentmail_search to locate it.`;
     }
 
     // Record successful request