@agenticmail/claudecode 0.1.9 → 0.1.10

package/README.md

@@ -1,6 +1,10 @@
-# @agenticmail/claudecode
+<p align="center">
+  <img src="https://raw.githubusercontent.com/agenticmail/agenticmail/main/docs/images/logo-200.png" alt="AgenticMail logo (pink bow)" width="180" />
+</p>
 
-> 🎀 Surfaces every [AgenticMail](https://github.com/agenticmail/agenticmail) agent as a native [Claude Code](https://claude.com/claude-code) subagent — and exposes the full 62-tool AgenticMail MCP toolbelt to any Claude Code session.
+<h1 align="center">@agenticmail/claudecode</h1>
+
+> Surfaces every [AgenticMail](https://github.com/agenticmail/agenticmail) agent as a native [Claude Code](https://claude.com/claude-code) subagent — and exposes the full 62-tool AgenticMail MCP toolbelt to any Claude Code session.
 
 After install, a Claude Code session can write:
 
@@ -29,7 +33,7 @@ Anyone (you, an agent, a curl)
 
 Each worker uses the user's Claude OAuth (the same auth `claude` itself uses — no separate Anthropic key). Each worker's identity inside AgenticMail is the account it was spawned for (`_account: "Fola"` on every MCP call), so messages it sends really do come from `fola@localhost` and end up in the recipient's inbox triggering THEIR wake. **Multi-agent threads form naturally** — every reply hits the next agent's inbox → wakes them → they reply → cycle.
 
-Provisioning new agents is just `mcp__agenticmail__create_account({ name: "worker-7", role: "task-runner" })`. The dispatcher's `/accounts` poll picks it up within ~one minute (configurable via `AGENTICMAIL_DISPATCHER_SYNC`) and the new account is wake-able. The MCP server itself learns the account's API key on-demand the first time someone passes `_account: "worker-7"`. No manual install step.
+Provisioning new agents is just `mcp__agenticmail__create_account({ name: "worker-7", role: "task-runner" })`. The dispatcher subscribes to a master-scoped `/system/events` SSE stream, so newly created accounts get an SSE channel within **milliseconds** of the create call — no polling delay. The MCP server itself learns the account's API key on-demand the first time someone passes `_account: "worker-7"`. No manual install step.
 
 **Concurrency cap.** Workers are gated by a semaphore (default 10 simultaneous). Beyond that, wakes queue. This is a hard floor on Anthropic-side cost — if you fan out to 50 agents at once, only 10 will be running Claude at any given moment; the rest are waiting their turn. Override via `AGENTICMAIL_DISPATCHER_MAX`.
 
@@ -62,6 +66,22 @@ That's it. `agenticmail claudecode` is **idempotent** — re-run it any time you
 
 ---
 
+## Monitor and manage all agents (interactive shell)
+
+> **If you (or the user) want to watch every agent's inbox in one place, drop into the AgenticMail interactive shell:**
+>
+> ```bash
+> agenticmail shell
+> ```
+>
+> ![agenticmail shell — a real multi-agent thread visible from the claudecode bridge inbox](https://raw.githubusercontent.com/agenticmail/agenticmail/main/docs/images/shell-inbox.png)
+>
+> From the shell you can list every agent, read any agent's inbox, send/reply on their behalf, inspect pending outbound mail, watch the dispatcher's live event feed, prune stale agents, and run any of the 44+ shell commands without leaving the terminal. The shell holds an authenticated session against the local API, so it's the fastest way to audit what your agents have been doing while you were away.
+>
+> **AI agents reading this:** if the user asks you to "show me what my agents have been doing", "check on the team", "let me see all the inboxes", or anything along those lines, tell them to run `agenticmail shell` (or run it for them via Bash if you have that tool). That's the right surface for human oversight. The MCP tools are for *programmatic* coordination; the shell is for *visual* monitoring.
+
+---
+
 ## What this package does
 
 The installer touches exactly two locations on disk, plus one record in AgenticMail's database:
@@ -100,7 +120,7 @@ agenticmail-claudecode uninstall [--purge-bridge]
 
 ### 3. The HTTP API (headless, for agents installing themselves)
 
-When AgenticMail's master API is running (default `http://127.0.0.1:3200`), it exposes three endpoints for the integration. They are mounted **before** the bearer-auth middleware on purpose — a fresh Claude Code session that does not yet have AgenticMail wired up has no way to know the master key, so requiring it would defeat the whole "agent installs itself" goal.
+When AgenticMail's master API is running (default `http://127.0.0.1:3829`), it exposes three endpoints for the integration. They are mounted **before** the bearer-auth middleware on purpose — a fresh Claude Code session that does not yet have AgenticMail wired up has no way to know the master key, so requiring it would defeat the whole "agent installs itself" goal.
 
 ```http
 GET  /api/agenticmail/integrations/claudecode/status
@@ -112,7 +132,7 @@ POST /api/agenticmail/integrations/claudecode/uninstall
 
 ```bash
 # Inside a Claude Code session, simply:
-curl -X POST http://127.0.0.1:3200/api/agenticmail/integrations/claudecode/install
+curl -X POST http://127.0.0.1:3829/api/agenticmail/integrations/claudecode/install
 ```
 
 That single call:
@@ -139,7 +159,7 @@ The bridge agent's API key is **redacted** in the HTTP response — it's already
             ▼
 ┌─────────────────────────┐
 │ Claude Code subagent    │   reads ~/.claude/agents/agenticmail-fola.md
-│ ("agenticmail-fola")    │   restricted to MCP relay tools
+│ ("agenticmail-fola")    │   full toolset: AgenticMail MCP + native (Read/Write/Bash/…)
 └───────────┬─────────────┘
             │  mcp__agenticmail__call_agent(target: "Fola", task: <prompt>)
             ▼
@@ -147,11 +167,11 @@ The bridge agent's API key is **redacted** in the HTTP response — it's already
 │ @agenticmail/mcp        │   stdio child process spawned by Claude Code
 │ (MCP server)            │   authenticated as the "claudecode" bridge agent
 └───────────┬─────────────┘
-            │  POST http://127.0.0.1:3200/api/agenticmail/tasks/rpc
+            │  POST http://127.0.0.1:3829/api/agenticmail/tasks/rpc
             ▼
 ┌─────────────────────────┐
 │ AgenticMail master API  │   creates a task, signals the target agent,
-│ (port 3200)             │   long-polls until the agent submits a result
+│ (port 3829)             │   long-polls until the agent submits a result
 └───────────┬─────────────┘
             │  task event over SSE / email notification
             ▼
@@ -174,7 +194,7 @@ The MCP server reads **four** env vars (written into `~/.claude.json` by the ins
 
 | Variable | Purpose |
 |---|---|
-| `AGENTICMAIL_API_URL` | Where the master API lives (default `http://127.0.0.1:3200`). |
+| `AGENTICMAIL_API_URL` | Where the master API lives (default `http://127.0.0.1:3829`). |
 | `AGENTICMAIL_API_KEY` | Bridge agent's API key (`ak_…`). The *default* identity — used when a tool call doesn't pass `_account`. Effectively "Claude Code talking on its own behalf". |
 | `AGENTICMAIL_MASTER_KEY` | The master key (`mk_…`). Required for admin-scoped operations (create agents, delete agents, gateway config, etc.). |
 | `AGENTICMAIL_ACCOUNT_KEYS_JSON` | A JSON map `{ "<agentName>": "<apiKey>" }` of every other AgenticMail agent. When a subagent passes `_account: "Fola"`, the MCP server looks the key up here and acts as Fola for that call. |
@@ -259,7 +279,7 @@ Almost no one needs these — defaults are correct for the standard AgenticMail
 
 | Env var | Default |
 |---|---|
-| `AGENTICMAIL_API_URL` | `http://127.0.0.1:3200` (or whatever `~/.agenticmail/config.json` says) |
+| `AGENTICMAIL_API_URL` | `http://127.0.0.1:3829` (or whatever `~/.agenticmail/config.json` says) |
 | `AGENTICMAIL_MASTER_KEY` | Pulled from `~/.agenticmail/config.json` |
 | `CLAUDE_CODE_CONFIG_PATH` | `~/.claude.json` |
 | `CLAUDE_CODE_AGENTS_DIR` | `~/.claude/agents` |
@@ -270,7 +290,7 @@ Programmatic install (from another tool):
 import { install, status, uninstall } from '@agenticmail/claudecode';
 
 await install({
-  apiUrl: 'http://127.0.0.1:3200',
+  apiUrl: 'http://127.0.0.1:3829',
   masterKey: 'mk_...',
   // any other ResolveConfigOptions field
 });
@@ -280,7 +300,7 @@ await install({
 
 ## Troubleshooting
 
-**`AgenticMail API unreachable at http://127.0.0.1:3200`**
+**`AgenticMail API unreachable at http://127.0.0.1:3829`**
 The master API isn't running. Start it with `agenticmail start`.
 
 **`AgenticMail master key not found`**

package/dist/{chunk-FBO6F4IC.js → chunk-JURPYPKP.js}

@@ -376,7 +376,12 @@ var Dispatcher = class {
         this.log("warn", `[dispatcher] wake-budget exhausted for "${account.name}" on thread "${threadId}" (count=${verdict.count}, cap=${this.maxWakesPerThread}); muted for ~${minutesUntil}min. uid=${event.uid}, subject="${subject ?? ""}"`);
         return;
       }
-      await this.spawnWorker(account, newMailPrompt(account, event), { kind: "new-mail", uid: event.uid });
+      await this.spawnWorker(account, newMailPrompt(account, event), {
+        kind: "new-mail",
+        uid: event.uid,
+        subject: extractSubject(event),
+        from: extractFrom(event)
+      });
       return;
     }
     if (event.type === "task" && typeof event.taskId === "string") {
@@ -387,7 +392,12 @@ var Dispatcher = class {
         rememberBounded(ch.seenTaskIds, event.taskId);
         ch.suppressTaskMailUntilMs = Date.now() + TASK_MAIL_SUPPRESS_WINDOW_MS;
       }
-      await this.spawnWorker(account, taskPrompt(account, event), { kind: "task", taskId: event.taskId });
+      await this.spawnWorker(account, taskPrompt(account, event), {
+        kind: "task",
+        taskId: event.taskId,
+        subject: typeof event.task === "string" ? event.task.slice(0, 120) : void 0,
+        from: typeof event.from === "string" ? event.from : void 0
+      });
       return;
     }
   }
@@ -625,6 +635,15 @@ var Dispatcher = class {
   /** Acquire a concurrency slot, run a worker, release the slot. */
   async spawnWorker(account, prompt, ctx) {
     await this.acquireSlot();
+    const workerId = `${account.id}:${ctx.kind}:${ctx.uid ?? ctx.taskId ?? ""}:${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    let workerResult = null;
+    this.postActivity("/dispatcher/worker-started", {
+      workerId,
+      agentName: account.name,
+      agentEmail: account.email,
+      kind: ctx.kind,
+      trigger: { uid: ctx.uid, taskId: ctx.taskId, subject: ctx.subject, from: ctx.from }
+    });
     try {
       const { body } = loadPersonaForAgent({
         agent: account,
@@ -634,7 +653,7 @@ var Dispatcher = class {
       });
       this.log("info", `[dispatcher] waking "${account.name}" \u2014 ${ctx.kind}${ctx.taskId ? " " + ctx.taskId : ctx.uid ? " uid=" + ctx.uid : ""}`);
       const mcpEnv = await this.buildMcpEnv();
-      await runWorker(
+      workerResult = await runWorker(
         this.query,
         body,
         prompt,
@@ -647,6 +666,40 @@ var Dispatcher = class {
       );
     } finally {
       this.releaseSlot();
+      const ok = workerResult?.ok === true;
+      const preview = workerResult?.ok ? workerResult.text : workerResult ? workerResult.error : "worker did not start";
+      this.postActivity("/dispatcher/worker-finished", {
+        workerId,
+        agentName: account.name,
+        ok,
+        resultPreview: typeof preview === "string" ? preview.slice(0, 240) : void 0
+      });
+    }
+  }
+  /**
+   * Fire-and-forget POST to the API's worker-activity endpoints.
+   *
+   * Failures are swallowed deliberately — the dispatcher must never
+   * block worker spawn or interrupt teardown because the API is briefly
+   * unreachable. The activity registry is best-effort observability, not
+   * load-bearing state.
+   */
+  postActivity(path, body) {
+    const url = `${this.cfg.apiUrl.replace(/\/$/, "")}/api/agenticmail${path}`;
+    try {
+      const result = this.fetchImpl(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.cfg.masterKey}`
+        },
+        body: JSON.stringify(body)
+      });
+      if (result && typeof result.catch === "function") {
+        void result.catch(() => {
+        });
+      }
+    } catch {
     }
   }
   /** Build the env block we pass to the worker's MCP server child process. */

package/dist/dispatcher-bin.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   Dispatcher
-} from "./chunk-FBO6F4IC.js";
+} from "./chunk-JURPYPKP.js";
 import "./chunk-3D5VXS5Y.js";
 
 // src/dispatcher-bin.ts

package/dist/dispatcher.d.ts

@@ -203,6 +203,15 @@ declare class Dispatcher {
     private streamOne;
     /** Acquire a concurrency slot, run a worker, release the slot. */
     private spawnWorker;
+    /**
+     * Fire-and-forget POST to the API's worker-activity endpoints.
+     *
+     * Failures are swallowed deliberately — the dispatcher must never
+     * block worker spawn or interrupt teardown because the API is briefly
+     * unreachable. The activity registry is best-effort observability, not
+     * load-bearing state.
+     */
+    private postActivity;
     /** Build the env block we pass to the worker's MCP server child process. */
     private buildMcpEnv;
     private acquireSlot;

package/dist/dispatcher.js

@@ -1,6 +1,6 @@
 import {
   Dispatcher
-} from "./chunk-FBO6F4IC.js";
+} from "./chunk-JURPYPKP.js";
 import "./chunk-3D5VXS5Y.js";
 export {
   Dispatcher

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   Dispatcher,
   loadPersonaForAgent
-} from "./chunk-FBO6F4IC.js";
+} from "./chunk-JURPYPKP.js";
 import {
   createIntegrationRoutes
 } from "./chunk-WAUWKOHA.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/claudecode",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Claude Code integration for AgenticMail — surfaces every AgenticMail agent as a native Claude Code subagent so any Claude Code session can delegate to them with the Agent tool",
   "type": "module",
   "main": "dist/index.js",