@agenticmail/claudecode 0.2.0 → 0.2.2

package/dist/{chunk-UCI2HLHM.js → chunk-T3J2WZMM.js}

@@ -12345,9 +12345,17 @@ async function runWorker(query, persona, userPrompt, agent, mcpServerName, mcpCo
           }
         }
       }
-      if (m.type === "result" && typeof m.result === "string") {
-        collectedText.push(m.result);
-        if (observer) observer.onMessage("result", m.result.slice(0, 240).replace(/\s+/g, " ").trim());
+      if (m.type === "result") {
+        const r = m;
+        if (typeof r.result === "string") {
+          collectedText.push(r.result);
+          if (observer) observer.onMessage("result", r.result.slice(0, 240).replace(/\s+/g, " ").trim());
+        }
+        if (r.usage && observer) {
+          const u = r.usage;
+          const summary = `in=${u.input_tokens ?? 0} out=${u.output_tokens ?? 0} cacheR=${u.cache_read_input_tokens ?? 0} cacheW=${u.cache_creation_input_tokens ?? 0}${typeof r.total_cost_usd === "number" ? ` cost=$${r.total_cost_usd.toFixed(4)}` : ""}`;
+          observer.onMessage("usage", summary);
+        }
       }
     }
     const text = collectedText.join("\n").trim();
@@ -12454,15 +12462,26 @@ function newMailPrompt(agent, event) {
     `   see ./foo.py, runs with \`python3 foo.py\`"); the filesystem is for`,
     `   DELIVERABLES. Then:`,
     `     reply_email({ uid: ${uid ?? "<uid>"}, replyAll: true, text: "...", _account: "${agent.name}" })`,
-    `   Sign with your name. Be substantive but concise. If you are handing off`,
-    `   to the next teammate, name them explicitly in your reply ("Orion \u2014 over to you, please \u2026").`,
-    `   **NAME the next actor in the \`wake\` parameter** so the dispatcher only`,
-    `   gives them a Claude turn \u2014 every other CC'd teammate still receives the`,
-    `   mail in their inbox but stays asleep, saving the project a lot of tokens.`,
-    `   Example: \`reply_email({ uid, replyAll: true, text: "Orion \u2014 your turn \u2026",`,
-    `   wake: ["orion"], _account: "${agent.name}" })\`. If nobody specific is`,
-    `   next (the work is complete and you're just signing off), pass \`wake: []\``,
-    `   to deliver silently with zero Claude turns spawned.`,
+    `   Sign with your name. Be substantive but concise.`,
+    ``,
+    `   ## Reply addressing \u2014 CRITICAL for wake control`,
+    `   reply_email({ replyAll: true }) automatically builds the right shape:`,
+    `   the ORIGINAL SENDER ends up on To (so they wake by default),`,
+    `   every other participant ends up on Cc (so they see it without`,
+    `   waking). DO NOT pass a hand-rolled comma-separated address list`,
+    `   via send_email \u2014 that puts every recipient on To and re-wakes`,
+    `   the whole thread, defeating the wake gating. Trust replyAll.`,
+    ``,
+    `   If you want to wake someone OTHER than the original sender`,
+    `   (e.g. you are handing off to a different next actor), name them`,
+    `   explicitly in the reply body ("Orion \u2014 over to you, please\u2026")`,
+    `   AND pass \`wake: ["orion"]\` so the dispatcher gives them a`,
+    `   Claude turn instead. Example:`,
+    `     reply_email({ uid, replyAll: true, text: "Orion \u2014 your turn \u2026",`,
+    `                   wake: ["orion"], _account: "${agent.name}" })`,
+    `   If nobody specific is next (the work is complete and you're just`,
+    `   signing off), pass \`wake: []\` to deliver silently \u2014 every`,
+    `   participant still sees the reply, no Claude turn is spawned.`,
     ``,
     `7. **If you need additional help from a teammate not yet on the thread,**`,
     `   include them by CC'ing in your reply-all \u2014 DO NOT spin up a separate`,
@@ -12565,6 +12584,13 @@ var Dispatcher = class {
    */
   wakeCoalesce = /* @__PURE__ */ new Map();
   wakeCoalesceMs;
+  /** Wall-clock timestamp the dispatcher started. Surfaced via
+   *  process-heartbeat so check_activity can show uptime. */
+  startedAtMs = Date.now();
+  /** Periodic timer that posts a process-heartbeat to the API.
+   *  Without this, a hung dispatcher looks identical to "no
+   *  events to wake on" — the host has no liveness signal. */
+  processHeartbeatTimer = null;
   constructor(opts = {}) {
     this.cfg = resolveConfig(opts);
     this.maxConcurrent = opts.maxConcurrentWorkers ?? DEFAULT_MAX_CONCURRENT;
@@ -12636,16 +12662,38 @@ var Dispatcher = class {
   }
   async start() {
     this.log("info", `[dispatcher] starting (maxConcurrent=${this.maxConcurrent}, syncEvery=${this.syncIntervalMs}ms)`);
+    this.startedAtMs = Date.now();
     await this.syncAccounts();
     this.accountSyncTimer = setInterval(() => {
       this.syncAccounts().catch((err) => this.log("warn", `[dispatcher] account sync failed: ${err}`));
     }, this.syncIntervalMs);
+    this.processHeartbeatTimer = setInterval(() => {
+      this.postActivity("/dispatcher/process-heartbeat", {
+        startedAtMs: this.startedAtMs,
+        uptimeMs: Date.now() - this.startedAtMs,
+        channels: this.channels.size,
+        coalesceQueueSize: this.wakeCoalesce.size,
+        running: this.running,
+        maxConcurrent: this.maxConcurrent
+      });
+    }, 3e4);
+    this.processHeartbeatTimer.unref?.();
+    this.postActivity("/dispatcher/process-heartbeat", {
+      startedAtMs: this.startedAtMs,
+      uptimeMs: 0,
+      channels: this.channels.size,
+      coalesceQueueSize: 0,
+      running: 0,
+      maxConcurrent: this.maxConcurrent
+    });
     void this.runSystemChannel();
   }
   async stop() {
     this.stopped = true;
     if (this.accountSyncTimer) clearInterval(this.accountSyncTimer);
     this.accountSyncTimer = null;
+    if (this.processHeartbeatTimer) clearInterval(this.processHeartbeatTimer);
+    this.processHeartbeatTimer = null;
     if (this.systemChannelController) {
       try {
         this.systemChannelController.abort();
@@ -12695,6 +12743,7 @@ var Dispatcher = class {
       if (ch) rememberBounded(ch.seenUids, event.uid);
       if (isThreadClosedSubject(subject)) {
         this.log("info", `[dispatcher] thread closed (subject="${subject ?? ""}") \u2014 skipping wake for "${account.name}" uid=${event.uid}`);
+        this.postSkipped(account, event, "thread-closed", `subject contains a thread-close marker: "${subject ?? ""}"`);
         try {
           this.threadCache.delete(cacheThreadId);
         } catch {
@@ -12708,8 +12757,18 @@ var Dispatcher = class {
       const allowlist = extractWakeAllowlist(event);
       if (!isAgentOnWakeAllowlist(account.name, allowlist)) {
         this.log("info", `[dispatcher] wake allowlist excludes "${account.name}" (list=${JSON.stringify(allowlist)}) \u2014 mail delivered, no Claude turn`);
+        this.postSkipped(account, event, "allowlist-excluded", `wake list ${JSON.stringify(allowlist)} did not include "${account.name}"`);
         return;
       }
+      const wakeOnCc = account.wakeOnCc !== false;
+      if (!wakeOnCc) {
+        const wasOnTo = event.wasOnTo === true;
+        if (!wasOnTo) {
+          this.log("info", `[dispatcher] "${account.name}" has wake_on_cc:false and was not on To \u2014 mail delivered, no Claude turn (uid=${event.uid})`);
+          this.postSkipped(account, event, "wake-on-cc", `"${account.name}" has wake_on_cc:false; not on To`);
+          return;
+        }
+      }
       const threadId = threadIdFromSubject(subject);
       await this.scheduleCoalescedWake(account, event, threadId);
       return;
@@ -12985,27 +13044,37 @@ var Dispatcher = class {
     }
     const key = `${account.id}::${threadId}`;
     const existing = this.wakeCoalesce.get(key);
-    if (existing) {
-      clearTimeout(existing.timer);
-      existing.events.push(event);
-      existing.timer = setTimeout(() => this.fireCoalescedWake(key), this.wakeCoalesceMs);
-      const elapsedFromFirst = this.now() - existing.firstScheduledAt;
-      if (elapsedFromFirst > this.wakeCoalesceMs * 5) {
-        clearTimeout(existing.timer);
-        this.fireCoalescedWake(key);
-      }
-      existing.timer.unref?.();
+    if (!existing) {
+      const entry = {
+        events: [],
+        // empty — first event already fired
+        account,
+        threadId,
+        firstScheduledAt: this.now(),
+        timer: setTimeout(() => this.fireCoalescedWake(key), this.wakeCoalesceMs)
+      };
+      entry.timer.unref?.();
+      this.wakeCoalesce.set(key, entry);
+      await this.fireWakeImmediately(account, event, threadId);
       return;
     }
-    const entry = {
-      events: [event],
-      account,
+    clearTimeout(existing.timer);
+    existing.events.push(event);
+    this.postActivity("/dispatcher/worker-queued", {
+      agentName: account.name,
+      agentId: account.id,
       threadId,
-      firstScheduledAt: this.now(),
-      timer: setTimeout(() => this.fireCoalescedWake(key), this.wakeCoalesceMs)
-    };
-    entry.timer.unref?.();
-    this.wakeCoalesce.set(key, entry);
+      queuedCount: existing.events.length,
+      fireAtMs: this.now() + this.wakeCoalesceMs,
+      reason: "coalescing subsequent burst events"
+    });
+    existing.timer = setTimeout(() => this.fireCoalescedWake(key), this.wakeCoalesceMs);
+    existing.timer.unref?.();
+    const elapsedFromFirst = this.now() - existing.firstScheduledAt;
+    if (elapsedFromFirst > this.wakeCoalesceMs * 5) {
+      clearTimeout(existing.timer);
+      this.fireCoalescedWake(key);
+    }
   }
   /**
    * Pre-0.9.0 fast path used when coalescing is disabled. Same
@@ -13016,6 +13085,7 @@ var Dispatcher = class {
     const verdict = this.chargeWake(account.id, threadId);
     if (!verdict.ok) {
       this.log("warn", `[dispatcher] wake-budget exhausted for "${account.name}" on thread "${threadId}" \u2014 dropped uid=${event.uid}`);
+      this.postSkipped(account, event, "budget-exhausted", `wake budget exhausted for thread "${threadId}" (count=${verdict.count}, cap=${this.maxWakesPerThread})`);
       return;
     }
     await this.spawnWorker(account, newMailPrompt(account, event), {
@@ -13150,6 +13220,7 @@ var Dispatcher = class {
     }
     let turnCount = 0;
     let lastTool = "";
+    let lastUsage;
     const observer = {
       onMessage: (tag, summary) => {
         writeLog(`${tag} ${summary}`);
@@ -13157,6 +13228,7 @@ var Dispatcher = class {
           lastTool = summary.split(" ")[0];
           turnCount++;
         }
+        if (tag === "usage") lastUsage = summary;
       }
     };
     const heartbeatHandle = setInterval(() => {
@@ -13210,6 +13282,11 @@ var Dispatcher = class {
         agentName: account.name,
         ok,
         turnCount,
+        // Context-budget telemetry: the SDK-reported usage line
+        // (input/output/cache tokens + cost). Forwarded so
+        // check_activity can show real cost per worker and the
+        // cache+memory savings vs pre-0.9.0 become measurable.
+        usage: lastUsage,
         resultPreview: typeof preview === "string" ? preview.slice(0, 240) : void 0
       });
     }
@@ -13240,6 +13317,32 @@ var Dispatcher = class {
     } catch {
     }
   }
+  /**
+   * Post a "skipped wake" notification with the reason the
+   * dispatcher decided not to fire a Claude turn. Surfaced in
+   * `check_activity` so the host can see the decision instead
+   * of just observing silence ("did my mail land? did the
+   * dispatcher skip it? is the dispatcher even alive?").
+   *
+   * Reasons cover every filter that drops a wake:
+   *   - thread-closed       — subject had [FINAL]/[DONE]/[CLOSED]/[WRAP]
+   *   - allowlist-excluded  — sender's `wake` list did not include the agent
+   *   - wake-on-cc          — agent registered wake_on_cc:false and was on Cc
+   *   - dedup               — duplicate UID seen recently
+   *   - rpc-suppress        — RPC-notification mail right after a task event
+   *   - budget-exhausted    — per-(agent, thread) wake budget hit the cap
+   */
+  postSkipped(account, event, reason, detail) {
+    this.postActivity("/dispatcher/worker-skipped", {
+      agentId: account.id,
+      agentName: account.name,
+      uid: event.uid,
+      subject: extractSubject(event),
+      from: extractFrom(event),
+      reason,
+      detail
+    });
+  }
   /** Build the env block we pass to the worker's MCP server child process. */
   async buildMcpEnv() {
     return {

package/dist/{config-CjEDSvVy.d.ts → config-CXW3gXFC.d.ts}

@@ -12,6 +12,10 @@ interface AgenticMailAccount {
     apiKey: string;
     role?: string;
     metadata?: Record<string, unknown>;
+    /** Per-agent wake preference. When false, the dispatcher
+     *  drops wakes where this agent was on Cc/Bcc but not To,
+     *  regardless of the sender's wake list. Defaults to true. */
+    wakeOnCc?: boolean;
 }
 /** Resolved configuration for everything the package does. */
 interface ClaudeCodeIntegrationConfig {

package/dist/dispatcher-bin.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   Dispatcher
-} from "./chunk-UCI2HLHM.js";
+} from "./chunk-T3J2WZMM.js";
 import "./chunk-DDJNA5HP.js";
 import "./chunk-B276KPVO.js";
 import "./chunk-RB5MGRT3.js";

package/dist/dispatcher.d.ts

@@ -1,4 +1,4 @@
-import { R as ResolveConfigOptions, A as AgenticMailAccount } from './config-CjEDSvVy.js';
+import { R as ResolveConfigOptions, A as AgenticMailAccount } from './config-CXW3gXFC.js';
 
 /**
  * AgenticMail → Claude Code event dispatcher.
@@ -68,6 +68,11 @@ interface SSEEvent {
      * Claude turn. When absent, every CC'd recipient wakes (v0.8.x default).
      */
     wakeAllowlist?: string[];
+    /** Per-recipient "was I on the To field?" flag emitted by the
+     *  API in 0.9.1+. Pairs with the recipient's `wake_on_cc`
+     *  preference: when the agent registered with wake_on_cc:false
+     *  and `wasOnTo !== true`, the dispatcher drops the wake. */
+    wasOnTo?: boolean;
     [key: string]: unknown;
 }
 interface DispatcherOptions extends ResolveConfigOptions {
@@ -191,6 +196,13 @@ declare class Dispatcher {
      */
     private wakeCoalesce;
     private wakeCoalesceMs;
+    /** Wall-clock timestamp the dispatcher started. Surfaced via
+     *  process-heartbeat so check_activity can show uptime. */
+    private startedAtMs;
+    /** Periodic timer that posts a process-heartbeat to the API.
+     *  Without this, a hung dispatcher looks identical to "no
+     *  events to wake on" — the host has no liveness signal. */
+    private processHeartbeatTimer;
     constructor(opts?: DispatcherOptions);
     /**
      * Charge one wake against the (agent, thread) budget. Returns true
@@ -316,6 +328,22 @@ declare class Dispatcher {
      * load-bearing state.
      */
     private postActivity;
+    /**
+     * Post a "skipped wake" notification with the reason the
+     * dispatcher decided not to fire a Claude turn. Surfaced in
+     * `check_activity` so the host can see the decision instead
+     * of just observing silence ("did my mail land? did the
+     * dispatcher skip it? is the dispatcher even alive?").
+     *
+     * Reasons cover every filter that drops a wake:
+     *   - thread-closed       — subject had [FINAL]/[DONE]/[CLOSED]/[WRAP]
+     *   - allowlist-excluded  — sender's `wake` list did not include the agent
+     *   - wake-on-cc          — agent registered wake_on_cc:false and was on Cc
+     *   - dedup               — duplicate UID seen recently
+     *   - rpc-suppress        — RPC-notification mail right after a task event
+     *   - budget-exhausted    — per-(agent, thread) wake budget hit the cap
+     */
+    private postSkipped;
     /** 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-UCI2HLHM.js";
+} from "./chunk-T3J2WZMM.js";
 import "./chunk-DDJNA5HP.js";
 import "./chunk-B276KPVO.js";
 import "./chunk-RB5MGRT3.js";

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export { install } from './install.js';
 export { UninstallOptions, uninstall } from './uninstall.js';
 export { status } from './status.js';
-import { A as AgenticMailAccount } from './config-CjEDSvVy.js';
-export { C as ClaudeCodeIntegrationConfig, I as InstallResult, a as InstallStatus, R as ResolveConfigOptions, U as UninstallResult, r as resolveConfig } from './config-CjEDSvVy.js';
+import { A as AgenticMailAccount } from './config-CXW3gXFC.js';
+export { C as ClaudeCodeIntegrationConfig, I as InstallResult, a as InstallStatus, R as ResolveConfigOptions, U as UninstallResult, r as resolveConfig } from './config-CXW3gXFC.js';
 export { createIntegrationRoutes } from './http-routes.js';
 export { Dispatcher, DispatcherOptions, QueryFn } from './dispatcher.js';
 import 'express';

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   Dispatcher,
   loadPersonaForAgent
-} from "./chunk-UCI2HLHM.js";
+} from "./chunk-T3J2WZMM.js";
 import "./chunk-DDJNA5HP.js";
 import "./chunk-B276KPVO.js";
 import "./chunk-RB5MGRT3.js";

package/dist/install.d.ts

@@ -1,4 +1,4 @@
-import { R as ResolveConfigOptions, I as InstallResult, A as AgenticMailAccount, C as ClaudeCodeIntegrationConfig } from './config-CjEDSvVy.js';
+import { R as ResolveConfigOptions, I as InstallResult, A as AgenticMailAccount, C as ClaudeCodeIntegrationConfig } from './config-CXW3gXFC.js';
 
 /**
  * Install AgenticMail into Claude Code.

package/dist/status.d.ts

@@ -1,4 +1,4 @@
-import { R as ResolveConfigOptions, a as InstallStatus } from './config-CjEDSvVy.js';
+import { R as ResolveConfigOptions, a as InstallStatus } from './config-CXW3gXFC.js';
 
 /**
  * Inspect the current install state of @agenticmail/claudecode.

package/dist/uninstall.d.ts

@@ -1,4 +1,4 @@
-import { R as ResolveConfigOptions, U as UninstallResult } from './config-CjEDSvVy.js';
+import { R as ResolveConfigOptions, U as UninstallResult } from './config-CXW3gXFC.js';
 
 /**
  * Uninstall AgenticMail from Claude Code.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/claudecode",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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",
@@ -47,7 +47,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@agenticmail/mcp": "^0.9.0",
+    "@agenticmail/mcp": "^0.9.2",
     "@anthropic-ai/claude-agent-sdk": "^0.2.140"
   },
   "peerDependencies": {