@agenticmail/api 0.7.1 → 0.7.3

package/README.md

@@ -10,7 +10,9 @@ This package runs a web server that handles everything: sending email and SMS, r
 npm install @agenticmail/api
 ```
 
-**Requirements:** Node.js 20+, `@agenticmail/core`, Stalwart Mail Server running (via Docker)
+**Requirements:** Node.js 22+ (uses Node's built-in `node:sqlite`, no native compilation), `@agenticmail/core@^0.7.0`, Stalwart Mail Server running (via Docker / Colima).
+
+**Default listen address:** `http://127.0.0.1:3829`. The port changed from `3100` to `3829` in `0.7.x` to avoid clashes with common dev-tool defaults (Grafana Loki, Express scaffolds, etc.). Override via `AGENTICMAIL_API_PORT` env var or `api.port` in `~/.agenticmail/config.json`.
 
 ---
 
@@ -24,8 +26,21 @@ The API server is the central hub. It sits between agents (or any client) and th
 - **The interactive shell** (`agenticmail start`) — powers every command in the CLI
 - **The MCP server** (`@agenticmail/mcp`) — translates AI tool calls into API requests
 - **OpenClaw sub-agents** (`@agenticmail/openclaw`) — same thing but for the OpenClaw framework
+- **Claude Code sessions** (`@agenticmail/claudecode`) — surfaces every AgenticMail agent as a callable subagent and bridges inbound mail/tasks to Claude-powered workers via a dispatcher daemon. The API auto-mounts integration routes under `/api/agenticmail/integrations/claudecode/*` when `@agenticmail/claudecode` is installed as an optional dependency.
 - **Your own code** — any HTTP client can use the API
 
+### Claude Code self-install endpoint
+
+When `@agenticmail/claudecode` is installed alongside the API server, three additional routes light up:
+
+```
+GET  /api/agenticmail/integrations/claudecode/status
+POST /api/agenticmail/integrations/claudecode/install
+POST /api/agenticmail/integrations/claudecode/uninstall
+```
+
+These are mounted **before** the master-key auth middleware on purpose — a fresh Claude Code session that doesn't yet have AgenticMail wired up has no way to know the master key, so requiring it would defeat the "agent installs itself" use case. The API binds to `127.0.0.1` by default, so anything that can reach these endpoints can already read `~/.agenticmail/config.json` — the unauthenticated install endpoint doesn't widen the attack surface beyond that. **If you bind the API to a non-loopback interface, put auth or a firewall in front of it** (same caveat as every other unauthenticated route on the server, e.g. `/health`).
+
 ---
 
 ## How Authentication Works
@@ -354,7 +369,7 @@ JSON parse errors (malformed request bodies) return a clear 400 error rather tha
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
 | `AGENTICMAIL_MASTER_KEY` | Yes | — | Admin API key (the human owner's key) |
-| `AGENTICMAIL_API_PORT` | No | `3100` | Port for the API server |
+| `AGENTICMAIL_API_PORT` | No | `3829` | Port for the API server |
 | `STALWART_URL` | No | `http://localhost:8080` | Stalwart mail server admin URL |
 | `STALWART_ADMIN_USER` | No | `admin` | Stalwart admin username |
 | `STALWART_ADMIN_PASSWORD` | No | `changeme` | Stalwart admin password |

package/REFERENCE.md

@@ -1297,7 +1297,7 @@ Signals: SIGTERM and SIGINT both trigger shutdown.
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
 | `AGENTICMAIL_MASTER_KEY` | Yes | — | Master API key |
-| `AGENTICMAIL_API_PORT` | No | `3100` | Server port |
+| `AGENTICMAIL_API_PORT` | No | `3829` | Server port |
 | `STALWART_URL` | No | `http://localhost:8080` | Stalwart admin URL |
 | `STALWART_ADMIN_USER` | No | `admin` | Stalwart admin user |
 | `STALWART_ADMIN_PASSWORD` | No | `changeme` | Stalwart admin password |

package/dist/index.js

@@ -246,8 +246,72 @@ function createHealthRoutes(stalwart) {
 }
 
 // src/routes/accounts.ts
-import { Router as Router2 } from "express";
+import { Router as Router3 } from "express";
 import { AGENT_ROLES, AgentDeletionService } from "@agenticmail/core";
+
+// src/routes/system-events.ts
+import { Router as Router2 } from "express";
+var listeners = /* @__PURE__ */ new Set();
+function pushSystemEvent(event) {
+  if (listeners.size === 0) return;
+  const data = `data: ${JSON.stringify(event)}
+
+`;
+  for (const entry of listeners) {
+    try {
+      entry.res.write(data);
+    } catch {
+    }
+  }
+}
+function closeAllSystemEventListeners() {
+  for (const entry of listeners) {
+    try {
+      entry.cleanup();
+    } catch {
+    }
+    try {
+      entry.res.end();
+    } catch {
+    }
+  }
+  listeners.clear();
+}
+function createSystemEventRoutes() {
+  const router = Router2();
+  router.get("/system/events", requireMaster, (req, res) => {
+    res.setHeader("Content-Type", "text/event-stream");
+    res.setHeader("Cache-Control", "no-cache");
+    res.setHeader("Connection", "keep-alive");
+    res.setHeader("X-Accel-Buffering", "no");
+    res.flushHeaders();
+    res.write(`data: ${JSON.stringify({ type: "connected" })}
+
+`);
+    const pingTimer = setInterval(() => {
+      try {
+        res.write(`: ping
+
+`);
+      } catch {
+      }
+    }, 3e4);
+    const entry = {
+      res,
+      cleanup: () => {
+        clearInterval(pingTimer);
+      }
+    };
+    listeners.add(entry);
+    req.on("close", () => {
+      entry.cleanup();
+      listeners.delete(entry);
+    });
+  });
+  return router;
+}
+
+// src/routes/accounts.ts
 function sanitizeAgent(agent) {
   if (!agent) return agent;
   const { metadata, ...rest } = agent;
@@ -261,7 +325,7 @@ function sanitizeAgent(agent) {
   return agent;
 }
 function createAccountRoutes(accountManager, db, config) {
-  const router = Router2();
+  const router = Router3();
   const deletionService = new AgentDeletionService(db, accountManager, config);
   router.post("/accounts", requireMaster, async (req, res, next) => {
     if (!req.body || typeof req.body !== "object") {
@@ -306,6 +370,13 @@ function createAccountRoutes(accountManager, db, config) {
         } catch {
         }
       }
+      try {
+        pushSystemEvent({
+          type: "account_created",
+          account: sanitizeAgent(agent)
+        });
+      } catch {
+      }
       res.status(201).json(sanitizeAgent(agent));
     } catch (err) {
       const msg = err.message ?? "";
@@ -463,9 +534,14 @@ function createAccountRoutes(accountManager, db, config) {
       const archive = req.query.archive !== "false";
       const reason = req.query.reason || void 0;
       const deletedBy = req.query.deletedBy || "api";
+      const deletingAgent = allAgents.find((a) => a.id === req.params.id);
       if (archive) {
         const report = await deletionService.archiveAndDelete(req.params.id, { deletedBy, reason });
         const { emails: _emails, ...summary } = report;
+        try {
+          pushSystemEvent({ type: "account_deleted", accountId: req.params.id, name: deletingAgent?.name });
+        } catch {
+        }
         res.json(summary);
       } else {
         const deleted = await accountManager.delete(req.params.id);
@@ -473,6 +549,10 @@ function createAccountRoutes(accountManager, db, config) {
           res.status(404).json({ error: "Agent not found" });
           return;
         }
+        try {
+          pushSystemEvent({ type: "account_deleted", accountId: req.params.id, name: deletingAgent?.name });
+        } catch {
+        }
         res.status(204).send();
       }
     } catch (err) {
@@ -488,7 +568,7 @@ function createAccountRoutes(accountManager, db, config) {
 }
 
 // src/routes/mail.ts
-import { Router as Router5 } from "express";
+import { Router as Router6 } from "express";
 import crypto from "crypto";
 import {
   MailSender as MailSender2,
@@ -501,7 +581,7 @@ import {
 } from "@agenticmail/core";
 
 // src/routes/events.ts
-import { Router as Router4 } from "express";
+import { Router as Router5 } from "express";
 import {
   InboxWatcher,
   MailReceiver,
@@ -513,7 +593,7 @@ import {
 import { v4 as uuidv42 } from "uuid";
 
 // src/routes/features.ts
-import { Router as Router3 } from "express";
+import { Router as Router4 } from "express";
 import { v4 as uuidv4 } from "uuid";
 import {
   MailSender
@@ -633,7 +713,7 @@ function parseScheduleTime(input) {
   return isNaN(fallback.getTime()) ? null : fallback;
 }
 function createFeatureRoutes(db, _accountManager, config, gatewayManager) {
-  const router = Router3();
+  const router = Router4();
   router.get("/contacts", requireAgent, async (req, res, next) => {
     try {
       const rows = db.prepare("SELECT * FROM contacts WHERE agent_id = ? ORDER BY name, email").all(req.agent.id);
@@ -1210,7 +1290,7 @@ async function closeAllWatchers() {
   activeWatchers.clear();
 }
 function createEventRoutes(accountManager, config, db) {
-  const router = Router4();
+  const router = Router5();
   router.get("/events", requireAgent, async (req, res, next) => {
     try {
       const agent = req.agent;
@@ -1673,7 +1753,7 @@ function saveSentCopy(authUser, password, config, raw) {
   })();
 }
 function createMailRoutes(accountManager, config, db, gatewayManager) {
-  const router = Router5();
+  const router = Router6();
   router.post("/mail/send", requireAgent, async (req, res, next) => {
     try {
       if (!req.body || typeof req.body !== "object") {
@@ -2449,7 +2529,7 @@ function createMailRoutes(accountManager, config, db, gatewayManager) {
 }
 
 // src/routes/inbound.ts
-import { Router as Router6 } from "express";
+import { Router as Router7 } from "express";
 import { randomUUID } from "crypto";
 import {
   parseEmail as parseEmail3,
@@ -2463,7 +2543,7 @@ var INBOUND_SECRET = process.env.AGENTICMAIL_INBOUND_SECRET || (() => {
 })();
 var DEBUG = () => !!process.env.AGENTICMAIL_DEBUG;
 function createInboundRoutes(accountManager, config, gatewayManager) {
-  const router = Router6();
+  const router = Router7();
   router.post("/mail/inbound", async (req, res, next) => {
     try {
       const secret = req.headers["x-inbound-secret"];
@@ -2540,9 +2620,9 @@ function createInboundRoutes(accountManager, config, gatewayManager) {
 }
 
 // src/routes/domains.ts
-import { Router as Router7 } from "express";
+import { Router as Router8 } from "express";
 function createDomainRoutes(domainManager) {
-  const router = Router7();
+  const router = Router8();
   router.post("/domains", requireMaster, async (req, res, next) => {
     try {
       const { domain } = req.body;
@@ -2596,13 +2676,13 @@ function createDomainRoutes(domainManager) {
 }
 
 // src/routes/gateway.ts
-import { Router as Router8 } from "express";
+import { Router as Router9 } from "express";
 import {
   RELAY_PRESETS,
   AGENT_ROLES as AGENT_ROLES2
 } from "@agenticmail/core";
 function createGatewayRoutes(gatewayManager) {
-  const router = Router8();
+  const router = Router9();
   router.get("/gateway/setup-guide", requireMaster, async (_req, res) => {
     res.json({
       modes: [
@@ -2958,12 +3038,12 @@ function createGatewayRoutes(gatewayManager) {
 }
 
 // src/routes/tasks.ts
-import { Router as Router9 } from "express";
+import { Router as Router10 } from "express";
 import { v4 as uuidv43 } from "uuid";
 import { MailSender as MailSender4 } from "@agenticmail/core";
 var rpcResolvers = /* @__PURE__ */ new Map();
 function createTaskRoutes(db, accountManager, config) {
-  const router = Router9();
+  const router = Router10();
   router.post("/tasks/assign", requireAuth, async (req, res, next) => {
     try {
       const { assignee, taskType, payload, expiresInSeconds } = req.body || {};
@@ -3284,7 +3364,7 @@ function parseTask(row) {
 }
 
 // src/routes/sms.ts
-import { Router as Router10 } from "express";
+import { Router as Router11 } from "express";
 import {
   SmsManager,
   parseGoogleVoiceSms,
@@ -3293,7 +3373,7 @@ import {
   isValidPhoneNumber
 } from "@agenticmail/core";
 function createSmsRoutes(db, accountManager, config, gatewayManager) {
-  const router = Router10();
+  const router = Router11();
   const smsManager = new SmsManager(db);
   function getAgent(req, res) {
     const agent = req.agent;
@@ -3535,7 +3615,7 @@ function createSmsRoutes(db, accountManager, config, gatewayManager) {
 }
 
 // src/routes/storage.ts
-import { Router as Router11 } from "express";
+import { Router as Router12 } from "express";
 function mapColumnType(col, dialect) {
   const typeMap = {
     sqlite: { text: "TEXT", integer: "INTEGER", real: "REAL", boolean: "INTEGER", json: "JSON", blob: "BLOB", timestamp: "TEXT" },
@@ -3682,7 +3762,7 @@ function adaptBetterSqlite(raw) {
 }
 function createStorageRoutes(rawDb, accountManager, config, dialect = "sqlite") {
   const db = adaptBetterSqlite(rawDb);
-  const router = Router11();
+  const router = Router12();
   function getAgent(req, res) {
     const agent = req.agent;
     if (!agent) {
@@ -4595,6 +4675,7 @@ function createApp(configOverrides) {
   app2.use("/api/agenticmail", createTaskRoutes(db, accountManager, config));
   app2.use("/api/agenticmail", createSmsRoutes(db, accountManager, config, gatewayManager));
   app2.use("/api/agenticmail", createStorageRoutes(db, accountManager, config));
+  app2.use("/api/agenticmail", createSystemEventRoutes());
   app2.use("/api/agenticmail", (_req, res) => {
     res.status(404).json({ error: "Not found" });
   });
@@ -4700,6 +4781,10 @@ async function shutdown() {
     await closeAllWatchers();
   } catch {
   }
+  try {
+    closeAllSystemEventListeners();
+  } catch {
+  }
   try {
     await closeCaches();
   } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/api",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "REST API server for AgenticMail — email and SMS endpoints for AI agents",
   "type": "module",
   "main": "dist/index.js",