@essentialai/cogent-plugin 3.16.0 → 3.18.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cogent",
-  "version": "3.16.0",
+  "version": "3.18.0",
   "description": "Inter-session communication bridge for Claude Code with Slack integration. Enables CC agents and Slack team members to communicate in real time.",
   "author": {
     "name": "Essential AI Solutions",

package/bridge/cogent-bridge.mjs

@@ -192,7 +192,7 @@ Your peer identity: **peerId=\`${peerId}\`**, **label=\`${label}\`**
 ### On Session Start
 1. Find your Claude Code session ID:
    \`\`\`bash
-   ls -t ~/.claude/projects/$(pwd | sed 's/[^a-zA-Z0-9-]/-/g')/*.jsonl 2>/dev/null | head -1 | xargs -I{} basename {} .jsonl
+   ls -t "\${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/projects/$(pwd | sed 's/[^a-zA-Z0-9-]/-/g')/*.jsonl 2>/dev/null | head -1 | xargs -I{} basename {} .jsonl
    \`\`\`
 2. Register yourself on the bridge:
    - Use \`cogent_register_peer\` with peerId="${peerId}", label="${label}"
@@ -1259,8 +1259,8 @@ var init_parseUtil = __esm({
     init_errors();
     init_en();
     makeIssue = (params) => {
-      const { data, path: path16, errorMaps, issueData } = params;
-      const fullPath = [...path16, ...issueData.path || []];
+      const { data, path: path17, errorMaps, issueData } = params;
+      const fullPath = [...path17, ...issueData.path || []];
       const fullIssue = {
         ...issueData,
         path: fullPath
@@ -1540,11 +1540,11 @@ var init_types = __esm({
     init_parseUtil();
     init_util();
     ParseInputLazyPath = class {
-      constructor(parent, value, path16, key) {
+      constructor(parent, value, path17, key) {
         this._cachedPath = [];
         this.parent = parent;
         this.data = value;
-        this._path = path16;
+        this._path = path17;
         this._key = key;
       }
       get path() {
@@ -4996,10 +4996,10 @@ function assignProp(target, prop, value) {
     configurable: true
   });
 }
-function getElementAtPath(obj, path16) {
-  if (!path16)
+function getElementAtPath(obj, path17) {
+  if (!path17)
     return obj;
-  return path16.reduce((acc, key) => acc?.[key], obj);
+  return path17.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -5248,11 +5248,11 @@ function aborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path16, issues) {
+function prefixIssues(path17, issues) {
   return issues.map((iss) => {
     var _a;
     (_a = iss).path ?? (_a.path = []);
-    iss.path.unshift(path16);
+    iss.path.unshift(path17);
     return iss;
   });
 }
@@ -17058,8 +17058,8 @@ var require_utils = __commonJS({
       }
       return ind;
     }
-    function removeDotSegments(path16) {
-      let input = path16;
+    function removeDotSegments(path17) {
+      let input = path17;
       const output = [];
       let nextSlash = -1;
       let len = 0;
@@ -17258,8 +17258,8 @@ var require_schemes = __commonJS({
         wsComponent.secure = void 0;
       }
       if (wsComponent.resourceName) {
-        const [path16, query] = wsComponent.resourceName.split("?");
-        wsComponent.path = path16 && path16 !== "/" ? path16 : void 0;
+        const [path17, query] = wsComponent.resourceName.split("?");
+        wsComponent.path = path17 && path17 !== "/" ? path17 : void 0;
         wsComponent.query = query;
         wsComponent.resourceName = void 0;
       }
@@ -21729,8 +21729,8 @@ var require_parseUtil = __commonJS({
     var errors_js_1 = require_errors2();
     var en_js_1 = __importDefault(require_en());
     var makeIssue2 = (params) => {
-      const { data, path: path16, errorMaps, issueData } = params;
-      const fullPath = [...path16, ...issueData.path || []];
+      const { data, path: path17, errorMaps, issueData } = params;
+      const fullPath = [...path17, ...issueData.path || []];
       const fullIssue = {
         ...issueData,
         path: fullPath
@@ -21884,11 +21884,11 @@ var require_types2 = __commonJS({
     var parseUtil_js_1 = require_parseUtil();
     var util_js_1 = require_util2();
     var ParseInputLazyPath2 = class {
-      constructor(parent, value, path16, key) {
+      constructor(parent, value, path17, key) {
         this._cachedPath = [];
         this.parent = parent;
         this.data = value;
-        this._path = path16;
+        this._path = path17;
         this._key = key;
       }
       get path() {
@@ -26389,8 +26389,8 @@ var init_stdio2 = __esm({
 // src/constants.ts
 import { createRequire } from "node:module";
 function resolveVersion() {
-  if ("3.16.0") {
-    return "3.16.0";
+  if ("3.18.0") {
+    return "3.18.0";
   }
   try {
     const require2 = createRequire(import.meta.url);
@@ -26679,7 +26679,13 @@ var init_config = __esm({
       // "human-broadcast" (toPeerId === "*" from a human origin: slack/gchat/web).
       // Default both. Agent-origin broadcasts are never auto-surfaced by C (storm-safe;
       // COGENT_BROADCAST_AWARENESS already handles seeing peer broadcasts).
-      COGENT_CHECK_ON_STOP_SCOPE: import_zod2.z.string().default("directed,human-broadcast")
+      COGENT_CHECK_ON_STOP_SCOPE: import_zod2.z.string().default("directed,human-broadcast"),
+      // Cogent Mail F4 — the mailbox domains an agent may configure + send to. CSV; default is the
+      // single Cogent mail domain. Cogent mail is ORGANISATION-ONLY (compliance: an accountable org
+      // owns every mailbox), so BYO external / corporate-domain mailboxes are BLOCKED for now — this
+      // allowlist is the configurable seam for adding per-org corporate domains in a future release.
+      // Baked default here (a LIBRARY default, not plugin env) so Team agents get it too.
+      COGENT_MAIL_ALLOWED_DOMAINS: import_zod2.z.string().default("mail.cogent.tools")
     });
     _config = null;
   }
@@ -27010,21 +27016,45 @@ var init_peer_registry = __esm({
   }
 });
 
+// src/services/agent-config.ts
+import os4 from "node:os";
+import path8 from "node:path";
+function claudeConfigDir() {
+  const override = process.env.CLAUDE_CONFIG_DIR?.trim();
+  return override ? override : path8.join(os4.homedir(), ".claude");
+}
+function codexHomeDir() {
+  const override = process.env.CODEX_HOME?.trim();
+  return override ? override : path8.join(os4.homedir(), ".codex");
+}
+function buildResumeEnv(source, vendorPrefix, preserve) {
+  const keep = new Set(preserve);
+  return Object.fromEntries(
+    Object.entries(source).filter(
+      ([key]) => (!key.startsWith(vendorPrefix) || keep.has(key)) && key !== "MCP_TRANSPORT"
+    )
+  );
+}
+var init_agent_config = __esm({
+  "src/services/agent-config.ts"() {
+    "use strict";
+  }
+});
+
 // src/services/cc-cli.ts
 import { spawn } from "node:child_process";
 import fs7 from "node:fs/promises";
-import os4 from "node:os";
-import path8 from "node:path";
+import path9 from "node:path";
 async function listCandidates(cwd) {
   try {
     const escapedCwd = cwd.replace(/[^a-zA-Z0-9-]/g, "-");
-    const projectDir = path8.join(os4.homedir(), ".claude", "projects", escapedCwd);
+    const projectDir = path9.join(claudeConfigDir(), "projects", escapedCwd);
     const entries = await fs7.readdir(projectDir);
     const jsonlFiles = entries.filter((f) => f.endsWith(".jsonl"));
     return await Promise.all(
       jsonlFiles.map(async (f) => ({
         sessionId: f.replace(".jsonl", ""),
-        mtimeMs: (await fs7.stat(path8.join(projectDir, f))).mtimeMs
+        mtimeMs: (await fs7.stat(path9.join(projectDir, f))).mtimeMs
       }))
     );
   } catch {
@@ -27039,9 +27069,8 @@ async function detectCurrentSession(cwd) {
 }
 async function validateSession(sessionId, cwd) {
   const projectHash = cwd.replace(/[^a-zA-Z0-9-]/g, "-");
-  const sessionPath = path8.join(
-    os4.homedir(),
-    ".claude",
+  const sessionPath = path9.join(
+    claudeConfigDir(),
     "projects",
     projectHash,
     `${sessionId}.jsonl`
@@ -27079,11 +27108,7 @@ function execClaude(sessionId, message, cwd, timeoutMs) {
       "-p",
       truncated
     ];
-    const cleanEnv = Object.fromEntries(
-      Object.entries(process.env).filter(
-        ([key]) => !key.startsWith("CLAUDE") && key !== "MCP_TRANSPORT"
-      )
-    );
+    const cleanEnv = buildResumeEnv(process.env, "CLAUDE", ["CLAUDE_CONFIG_DIR"]);
     cleanEnv.COGENT_CHECK_ON_STOP = "0";
     const child = spawn(config2.COGENT_CLAUDE_PATH, args, {
       cwd,
@@ -27208,6 +27233,7 @@ var init_cc_cli = __esm({
   "src/services/cc-cli.ts"() {
     "use strict";
     init_config();
+    init_agent_config();
   }
 });
 
@@ -27339,14 +27365,14 @@ var init_codex_preflight = __esm({
 
 // src/services/health-check.ts
 import fs9 from "node:fs/promises";
-import path9 from "node:path";
+import path10 from "node:path";
 import { execFile as execFile3 } from "node:child_process";
 function getStatePath2() {
-  return path9.join(getConfig().COGENT_STATE_PATH, "cogent-state.json");
+  return path10.join(getConfig().COGENT_STATE_PATH, "cogent-state.json");
 }
 async function checkStateFile() {
   const statePath = getStatePath2();
-  const dir = path9.dirname(statePath);
+  const dir = path10.dirname(statePath);
   try {
     await fs9.access(dir, fs9.constants.R_OK | fs9.constants.W_OK);
   } catch {
@@ -27424,7 +27450,7 @@ async function checkHealth() {
   return {
     healthy,
     mcpServerVersion: SERVER_VERSION,
-    statePath: path9.join(config2.COGENT_STATE_PATH, "cogent-state.json"),
+    statePath: path10.join(config2.COGENT_STATE_PATH, "cogent-state.json"),
     claudePath: config2.COGENT_CLAUDE_PATH,
     checks,
     timestamp: (/* @__PURE__ */ new Date()).toISOString()
@@ -27463,8 +27489,8 @@ var init_file_backend = __esm({
           threadId
         );
       }
-      deregisterPeer(peerId) {
-        return deregisterPeer(peerId);
+      async deregisterPeer(peerId) {
+        return { removed: await deregisterPeer(peerId), mailboxDeprovisioned: false };
       }
       getPeer(peerId) {
         return getPeer(peerId);
@@ -27531,7 +27557,7 @@ var init_relay_version_cache = __esm({
 });
 
 // src/backend/http-backend.ts
-var PATHS, HttpBackend;
+var MAILBOX_DEPROVISIONED_HEADER, PATHS, HttpBackend;
 var init_http_backend = __esm({
   "src/backend/http-backend.ts"() {
     "use strict";
@@ -27539,6 +27565,7 @@ var init_http_backend = __esm({
     init_constants();
     init_config();
     init_relay_version_cache();
+    MAILBOX_DEPROVISIONED_HEADER = "X-Cogent-Mailbox-Deprovisioned";
     PATHS = {
       peers: "/api/sessions/:sessionId/peers",
       peer: "/api/sessions/:sessionId/peers/:peerId",
@@ -27562,7 +27589,7 @@ var init_http_backend = __esm({
        * in cloud mode we ignore it and use this.sessionId (the cloud session).
        */
       async registerPeer(peerId, _sessionId, cwd, label, clientVersion, mode, _channelSessionId, capabilities, workspaceId, threadId) {
-        const path16 = PATHS.peers.replace(":sessionId", this.sessionId);
+        const path17 = PATHS.peers.replace(":sessionId", this.sessionId);
         const body = {
           peerId,
           cwd,
@@ -27590,21 +27617,25 @@ var init_http_backend = __esm({
             body.role = roleCap.slice("role:".length);
           }
         }
-        return this.http.post(path16, body);
+        return this.http.post(path17, body);
       }
       /**
        * Deregister a peer from the cloud session.
        * DELETE /api/sessions/:sessionId/peers/:peerId
        *
-       * Returns true on success, false if the peer was not found.
+       * Returns `{ removed, mailboxDeprovisioned }`. `mailboxDeprovisioned` reflects the relay's
+       * `X-Cogent-Mailbox-Deprovisioned` response header (Cogent Mail F3) — true ONLY when the relay
+       * confirmed the Team mailbox was reaped, so the deregister-peer tool can clear the now-dead
+       * local mail creds. A 404 (peer not found) resolves to `{ removed: false, ... }`, not a throw.
        */
       async deregisterPeer(peerId) {
-        const path16 = PATHS.peer.replace(":sessionId", this.sessionId).replace(":peerId", peerId);
+        const path17 = PATHS.peer.replace(":sessionId", this.sessionId).replace(":peerId", peerId);
         try {
-          await this.http.delete(path16, {});
-          return true;
+          const headers = await this.http.delete(path17, {});
+          const mailboxDeprovisioned = headers.get(MAILBOX_DEPROVISIONED_HEADER) === "true";
+          return { removed: true, mailboxDeprovisioned };
         } catch {
-          return false;
+          return { removed: false, mailboxDeprovisioned: false };
         }
       }
       /**
@@ -27621,8 +27652,8 @@ var init_http_backend = __esm({
        * GET /api/sessions/:sessionId/peers
        */
       async listPeers() {
-        const path16 = PATHS.peers.replace(":sessionId", this.sessionId);
-        const result = await this.http.get(path16);
+        const path17 = PATHS.peers.replace(":sessionId", this.sessionId);
+        const result = await this.http.get(path17);
         return result.peers;
       }
       /**
@@ -27630,8 +27661,8 @@ var init_http_backend = __esm({
        * Calls the lightweight heartbeat endpoint on the cloud relay server.
        */
       async updateLastSeen(peerId) {
-        const path16 = PATHS.heartbeat.replace(":sessionId", this.sessionId);
-        await this.http.post(path16, { peerId });
+        const path17 = PATHS.heartbeat.replace(":sessionId", this.sessionId);
+        await this.http.post(path17, { peerId });
       }
       /**
        * Record a message in the cloud session.
@@ -27642,7 +27673,7 @@ var init_http_backend = __esm({
        * the input record to construct a full MessageRecord.
        */
       async recordMessage(record2) {
-        const path16 = PATHS.messages.replace(":sessionId", this.sessionId);
+        const path17 = PATHS.messages.replace(":sessionId", this.sessionId);
         const body = {
           fromPeerId: record2.fromPeerId,
           toPeerId: record2.toPeerId,
@@ -27651,7 +27682,10 @@ var init_http_backend = __esm({
         if (record2.isRelayEcho === true) {
           body.isRelayEcho = true;
         }
-        const resp = await this.http.post(path16, body);
+        if (record2.attachments && record2.attachments.length > 0) {
+          body.attachments = record2.attachments;
+        }
+        const resp = await this.http.post(path17, body);
         return {
           ...record2,
           id: resp.id,
@@ -27665,7 +27699,7 @@ var init_http_backend = __esm({
        * Supports optional peerId filter and limit (default 300).
        */
       async getHistory(peerId, limit, includeRelayEchoes, metadataOnly, dedupInferredEchoes) {
-        const path16 = PATHS.messages.replace(":sessionId", this.sessionId);
+        const path17 = PATHS.messages.replace(":sessionId", this.sessionId);
         const query = {};
         if (peerId) {
           query.peerId = peerId;
@@ -27680,7 +27714,7 @@ var init_http_backend = __esm({
         if (dedupInferredEchoes) {
           query.dedupInferredEchoes = "true";
         }
-        const result = await this.http.get(path16, query);
+        const result = await this.http.get(path17, query);
         return result.messages;
       }
       /**
@@ -27691,12 +27725,12 @@ var init_http_backend = __esm({
        * so that get-history shows the actual response (not null).
        */
       async updateMessageResponse(messageId, response, durationMs, pending) {
-        const path16 = PATHS.message.replace(":sessionId", this.sessionId).replace(":messageId", messageId);
+        const path17 = PATHS.message.replace(":sessionId", this.sessionId).replace(":messageId", messageId);
         const body = { response, durationMs };
         if (pending === true) {
           body.pending = true;
         }
-        await this.http.patch(path16, body);
+        await this.http.patch(path17, body);
       }
       /**
        * Validate a session.
@@ -27838,8 +27872,8 @@ var init_http_client = __esm({
        * Perform an authenticated GET request.
        * Appends query parameters to the URL if provided.
        */
-      async get(path16, query) {
-        const url = new URL(path16, this.baseUrl);
+      async get(path17, query) {
+        const url = new URL(path17, this.baseUrl);
         if (query) {
           for (const [k, v] of Object.entries(query)) {
             url.searchParams.set(k, v);
@@ -27854,8 +27888,8 @@ var init_http_client = __esm({
       /**
        * Perform an authenticated POST request with a JSON body.
        */
-      async post(path16, body) {
-        const url = new URL(path16, this.baseUrl);
+      async post(path17, body) {
+        const url = new URL(path17, this.baseUrl);
         const resp = await this.fetchWithTimeout(url, {
           method: "POST",
           headers: this.headers(),
@@ -27873,8 +27907,8 @@ var init_http_client = __esm({
        * Perform an authenticated PATCH request with a JSON body.
        * Used to update existing resources (e.g., message response fields).
        */
-      async patch(path16, body) {
-        const url = new URL(path16, this.baseUrl);
+      async patch(path17, body) {
+        const url = new URL(path17, this.baseUrl);
         const resp = await this.fetchWithTimeout(url, {
           method: "PATCH",
           headers: this.headers(),
@@ -27890,15 +27924,17 @@ var init_http_client = __esm({
       }
       /**
        * Perform an authenticated DELETE request.
-       * Returns void; ignores 204 No Content responses.
+       * Returns the RESPONSE HEADERS (a 204 carries no body, but the relay conveys
+       * out-of-band signals — e.g. Cogent Mail F3's `X-Cogent-Mailbox-Deprovisioned` —
+       * via headers, so callers that need them can read them without a body).
        *
        * When no body is provided, Content-Type is omitted so servers don't try
        * to parse an empty payload as JSON. This was the root cause of a
        * "Malformed JSON in request body" 400 from cogent-server <=3.1.2 when
        * any client (including third-party tools) DELETEd a peer without a body.
        */
-      async delete(path16, body) {
-        const url = new URL(path16, this.baseUrl);
+      async delete(path17, body) {
+        const url = new URL(path17, this.baseUrl);
         const headers = {
           "Authorization": `Bearer ${this.token}`
         };
@@ -27913,6 +27949,7 @@ var init_http_client = __esm({
         if (!resp.ok && resp.status !== 204) {
           await this.throwMappedError(resp);
         }
+        return resp.headers;
       }
       /**
        * Update the Bearer token (e.g., after join-session returns a new token).
@@ -32077,14 +32114,14 @@ var init_ws_client = __esm({
         if (this.pollTimer) return;
         const poll = async () => {
           try {
-            const path16 = `/api/sessions/${this.opts.sessionId}/poll`;
+            const path17 = `/api/sessions/${this.opts.sessionId}/poll`;
             const query = {
               peerId: this.opts.peerId
             };
             if (this.lastMessageId) {
               query.lastMessageId = this.lastMessageId;
             }
-            const result = await this.opts.http.get(path16, query);
+            const result = await this.opts.http.get(path17, query);
             if (result.messages && result.messages.length > 0) {
               this.opts.onMessages(result.messages);
               this.lastMessageId = result.messages[result.messages.length - 1].id;
@@ -32143,7 +32180,7 @@ var init_cloud = __esm({
 import { spawn as spawn2 } from "node:child_process";
 import fs10 from "node:fs/promises";
 import os5 from "node:os";
-import path10 from "node:path";
+import path11 from "node:path";
 import { randomUUID } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { createInterface as createInterface2 } from "node:readline";
@@ -32171,7 +32208,7 @@ function execCodex(sessionId, message, cwd, timeoutMs) {
     const config2 = getConfig();
     const effectiveTimeout = timeoutMs ?? config2.COGENT_TIMEOUT_MS;
     const truncated = config2.COGENT_CHAR_LIMIT > 0 && message.length > config2.COGENT_CHAR_LIMIT ? message.slice(0, config2.COGENT_CHAR_LIMIT) + "\n...[truncated]" : message;
-    const lastMsgFile = path10.join(os5.tmpdir(), `cogent-codex-${randomUUID()}.txt`);
+    const lastMsgFile = path11.join(os5.tmpdir(), `cogent-codex-${randomUUID()}.txt`);
     const args = [
       "exec",
       "resume",
@@ -32182,11 +32219,7 @@ function execCodex(sessionId, message, cwd, timeoutMs) {
       lastMsgFile,
       truncated
     ];
-    const cleanEnv = Object.fromEntries(
-      Object.entries(process.env).filter(
-        ([key]) => !key.startsWith("CODEX") && key !== "MCP_TRANSPORT"
-      )
-    );
+    const cleanEnv = buildResumeEnv(process.env, "CODEX", ["CODEX_HOME"]);
     cleanEnv.COGENT_CHECK_ON_STOP = "0";
     const child = spawn2(config2.COGENT_CODEX_PATH, args, {
       cwd,
@@ -32278,7 +32311,7 @@ async function listRolloutFiles(root) {
       return;
     }
     for (const e of entries) {
-      const full = path10.join(dir, e.name);
+      const full = path11.join(dir, e.name);
       if (e.isDirectory()) await walk(full);
       else if (e.isFile() && e.name.endsWith(".jsonl")) out.push(full);
     }
@@ -32310,10 +32343,10 @@ async function readSessionMeta(file) {
   }
 }
 function codexSessionsRoot() {
-  return path10.join(os5.homedir(), ".codex", "sessions");
+  return path11.join(codexHomeDir(), "sessions");
 }
 async function cwdCanonicals(cwd) {
-  const resolved = path10.resolve(cwd);
+  const resolved = path11.resolve(cwd);
   const forms = /* @__PURE__ */ new Set([resolved]);
   try {
     forms.add(await fs10.realpath(resolved));
@@ -32322,7 +32355,7 @@ async function cwdCanonicals(cwd) {
   return forms;
 }
 function metaCwdMatches(metaCwd, forms) {
-  return forms.has(path10.resolve(metaCwd));
+  return forms.has(path11.resolve(metaCwd));
 }
 async function detectCurrentCodexSession(cwd) {
   try {
@@ -32381,6 +32414,7 @@ var init_codex_cli = __esm({
   "src/services/codex-cli.ts"() {
     "use strict";
     init_config();
+    init_agent_config();
     sandboxOverride = null;
     SANDBOX_FAILURE_RE = /bwrap:|setting up uid ?map|\/proc\/self\/(uid|gid)_map|newuidmap|user namespaces?|RTM_NEWADDR|unshare[^\n]*(Operation not permitted|Permission denied)|clone3?[^\n]*(EPERM|not permitted)/i;
   }
@@ -32514,27 +32548,40 @@ function parseStatusNotice(message) {
   const m = STATUS_MARKER_RE.exec(message);
   return m ? m[1] : null;
 }
-function formatRelayMessage(fromLabel, fromPeerId, message) {
+function formatAttachmentsBlock(attachments) {
+  if (!attachments || attachments.length === 0) return "";
+  const lines = attachments.map((a) => {
+    const name = a.name || a.mailMessageId || a.url || "file";
+    const ref = a.mailMessageId ? `fetch via cogent_fetch_mail (${a.mailMessageId})` : a.url ? a.url : "no fetchable reference";
+    const meta = [a.mimeType, a.size != null ? `${a.size}B` : null].filter(Boolean).join(", ");
+    return `  [file: ${name}${meta ? ` (${meta})` : ""} \u2014 ${ref}]`;
+  });
+  return `
+
+\u{1F4CE} Attachments (byte transport = email):
+${lines.join("\n")}`;
+}
+function formatRelayMessage(fromLabel, fromPeerId, message, attachments) {
   return `[Cogent Bridge message from ${fromLabel} (${fromPeerId})]
 
-${message}
+${message}${formatAttachmentsBlock(attachments)}
 
 ---
 Respond directly to the message above. Your entire response is delivered automatically to whoever should receive it \u2014 a broadcast question (to the whole channel) is answered to everyone; a direct message, to the sender. You do NOT need to \u2014 and should NOT \u2014 call cogent_send_message or any bridge tool to deliver it; just answer normally.`;
 }
-function formatInjectOnlyMessage(fromLabel, fromPeerId, message) {
+function formatInjectOnlyMessage(fromLabel, fromPeerId, message, attachments) {
   return `[Cogent Bridge: Response from ${fromLabel} (${fromPeerId})]
 
-${message}
+${message}${formatAttachmentsBlock(attachments)}
 
 ---
 This is the response to your earlier cogent_send_message. No reply will be relayed.
 To continue the conversation, use cogent_send_message again.`;
 }
-function formatPeerBroadcastNotice(fromLabel, fromPeerId, message) {
+function formatPeerBroadcastNotice(fromLabel, fromPeerId, message, attachments) {
   return `[Cogent Bridge: broadcast from ${fromLabel} (${fromPeerId}) to the whole channel]
 
-${message}
+${message}${formatAttachmentsBlock(attachments)}
 
 ---
 FYI ONLY \u2014 another agent addressed the whole channel. Take note for context, but do NOT reply and do NOT call any cogent_* tool in response. A human will drive any reply.`;
@@ -33076,7 +33123,7 @@ var init_auto_relay = __esm({
           }
         } catch {
         }
-        const formatted = formatRelayMessage(fromLabel, msg.fromPeerId, msg.message);
+        const formatted = formatRelayMessage(fromLabel, msg.fromPeerId, msg.message, msg.attachments);
         logger.info(`Auto-relay: processing message from ${fromLabel} (${msg.fromPeerId})`);
         const traceId = msg.traceId ?? randomUUID2();
         const startMs = Date.now();
@@ -33234,7 +33281,7 @@ var init_auto_relay = __esm({
           }
         } catch {
         }
-        const formatted = formatInjectOnlyMessage(fromLabel, msg.fromPeerId, msg.message);
+        const formatted = formatInjectOnlyMessage(fromLabel, msg.fromPeerId, msg.message, msg.attachments);
         try {
           await this.refreshSessionId();
           const result = await execRemote(
@@ -33269,7 +33316,7 @@ var init_auto_relay = __esm({
           }
         } catch {
         }
-        const formatted = formatPeerBroadcastNotice(fromLabel, msg.fromPeerId, msg.message);
+        const formatted = formatPeerBroadcastNotice(fromLabel, msg.fromPeerId, msg.message, msg.attachments);
         try {
           await this.refreshSessionId();
           const result = await execRemote(
@@ -33573,7 +33620,7 @@ __export(startup_exports, {
   triggerReRegistration: () => triggerReRegistration
 });
 import os6 from "node:os";
-import path11 from "node:path";
+import path12 from "node:path";
 import fs11 from "node:fs/promises";
 import readline2 from "node:readline";
 import { execFile as execFile5 } from "node:child_process";
@@ -33624,7 +33671,7 @@ First run detected. Where should cogent-bridge store its data?
 }
 async function validateStateDir(statePath) {
   await fs11.mkdir(statePath, { recursive: true });
-  const testFile = path11.join(statePath, ".write-test");
+  const testFile = path12.join(statePath, ".write-test");
   try {
     await fs11.writeFile(testFile, "test", "utf-8");
     await fs11.unlink(testFile);
@@ -33773,10 +33820,10 @@ async function runStartup() {
   if (envStatePath) {
     statePath = envStatePath;
   } else {
-    const defaultPath = path11.join(os6.homedir(), ".cogent");
+    const defaultPath = path12.join(os6.homedir(), ".cogent");
     statePath = await firstRunPrompt(defaultPath);
   }
-  if (!envStatePath && statePath !== path11.join(os6.homedir(), ".cogent")) {
+  if (!envStatePath && statePath !== path12.join(os6.homedir(), ".cogent")) {
     process.env.COGENT_STATE_PATH = statePath;
   } else if (!envStatePath) {
     process.env.COGENT_STATE_PATH = statePath;
@@ -33853,7 +33900,7 @@ async function runStartup() {
   }
   initLogger(
     config2.COGENT_LOG_LEVEL,
-    path11.join(config2.COGENT_STATE_PATH, "logs")
+    path12.join(config2.COGENT_STATE_PATH, "logs")
   );
   if (isCloud && effectiveSessionId && effectiveToken) {
     cloudInbox = new MessageInbox();
@@ -33910,7 +33957,7 @@ var init_startup = __esm({
     init_auto_relay();
     UUID_V4_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
     execFileAsync3 = promisify4(execFile5);
-    PERSIST_PATH = path11.join(os6.homedir(), ".cogent-config.json");
+    PERSIST_PATH = path12.join(os6.homedir(), ".cogent-config.json");
     legacyWarnEmitted = false;
     cloudWsClient = null;
     cloudInbox = null;
@@ -33922,11 +33969,11 @@ var init_startup = __esm({
 // src/cloud/mail-credential-store.ts
 import crypto3 from "node:crypto";
 import fs12 from "node:fs/promises";
-import path12 from "node:path";
+import path13 from "node:path";
 import os7 from "node:os";
 function defaultMailCredentialPath(cwd = process.cwd()) {
-  const hash = crypto3.createHash("sha256").update(path12.resolve(cwd)).digest("hex").slice(0, 16);
-  return path12.join(os7.homedir(), ".cogent", "mail-credentials", `${hash}.json`);
+  const hash = crypto3.createHash("sha256").update(path13.resolve(cwd)).digest("hex").slice(0, 16);
+  return path13.join(os7.homedir(), ".cogent", "mail-credentials", `${hash}.json`);
 }
 function resolveMailCredentialPath(credentialPath) {
   if (credentialPath) return credentialPath;
@@ -33944,7 +33991,7 @@ async function loadMailCredentials(credentialPath) {
 }
 async function saveMailCredentials(creds, credentialPath) {
   const filePath = resolveMailCredentialPath(credentialPath);
-  await fs12.mkdir(path12.dirname(filePath), { recursive: true, mode: 448 });
+  await fs12.mkdir(path13.dirname(filePath), { recursive: true, mode: 448 });
   await fs12.writeFile(filePath, JSON.stringify(creds, null, 2) + "\n", { encoding: "utf-8", mode: 384 });
   await fs12.chmod(filePath, 384);
 }
@@ -33964,6 +34011,14 @@ async function persistProvisionedMailbox(mailbox, credentialPath) {
   );
   return true;
 }
+async function clearMailCredentials(credentialPath) {
+  const filePath = resolveMailCredentialPath(credentialPath);
+  try {
+    await fs12.unlink(filePath);
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+}
 var MAIL_DEFAULT_HOST;
 var init_mail_credential_store = __esm({
   "src/cloud/mail-credential-store.ts"() {
@@ -34519,11 +34574,18 @@ var init_peer = __esm({
 });
 
 // cogent/dist/types/message.js
-var import_zod6, MessageRecordSchema;
+var import_zod6, AttachmentSchema, MessageRecordSchema;
 var init_message = __esm({
   "cogent/dist/types/message.js"() {
     "use strict";
     import_zod6 = __toESM(require_zod(), 1);
+    AttachmentSchema = import_zod6.z.object({
+      url: import_zod6.z.string().optional().describe("Public/fetchable URL reference"),
+      mailMessageId: import_zod6.z.string().optional().describe("IMAP message-id in the recipient mailbox"),
+      name: import_zod6.z.string().optional().describe("Display name / filename"),
+      mimeType: import_zod6.z.string().optional().describe("MIME type"),
+      size: import_zod6.z.number().int().nonnegative().optional().describe("Size in bytes")
+    }).describe("A file reference carried alongside a message (byte transport = email)");
     MessageRecordSchema = import_zod6.z.object({
       id: import_zod6.z.string().uuid().describe("Unique message identifier"),
       fromPeerId: import_zod6.z.string().min(1).describe("Sender peer ID"),
@@ -34534,7 +34596,8 @@ var init_message = __esm({
       durationMs: import_zod6.z.number().nullable().describe("Round-trip duration in ms"),
       success: import_zod6.z.boolean().describe("Whether delivery succeeded"),
       error: import_zod6.z.string().nullable().describe("Error message if delivery failed"),
-      originPlatform: import_zod6.z.enum(["cc", "codex", "slack", "gchat", "web", "gemini", "whatsapp", "telegram", "discord"]).optional().describe("Platform that originated this message")
+      originPlatform: import_zod6.z.enum(["cc", "codex", "slack", "gchat", "web", "gemini", "whatsapp", "telegram", "discord"]).optional().describe("Platform that originated this message"),
+      attachments: import_zod6.z.array(AttachmentSchema).optional().describe("Cogent Mail M2.5 \u2014 file references (byte transport = email)")
     });
   }
 });
@@ -35094,8 +35157,16 @@ function registerDeregisterPeerTool(server) {
     async ({ peerId }) => {
       try {
         const backend = getBackend();
-        const removed = await backend.deregisterPeer(peerId);
+        const { removed, mailboxDeprovisioned } = await backend.deregisterPeer(peerId);
         if (removed) heartbeat.stop();
+        if (mailboxDeprovisioned) {
+          try {
+            await clearMailCredentials();
+            logger.info("cleared local mail credentials after mailbox deprovision", { peerId });
+          } catch (err) {
+            logger.warn("failed to clear local mail credentials after deprovision", { error: err });
+          }
+        }
         return successResult({
           success: removed,
           message: removed ? `Peer '${peerId}' deregistered` : `Peer '${peerId}' was not registered`
@@ -35116,6 +35187,7 @@ var init_deregister_peer = __esm({
     init_errors4();
     init_logger();
     init_heartbeat();
+    init_mail_credential_store();
   }
 });
 
@@ -35501,12 +35573,36 @@ function assertValidEmail(value, field) {
     );
   }
 }
-var EMAIL_RE;
+function parseAllowedMailDomains(csv) {
+  const list = (csv ?? DEFAULT_MAIL_DOMAIN).split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+  return list.length ? list : [DEFAULT_MAIL_DOMAIN];
+}
+function allowedMailDomains() {
+  try {
+    return parseAllowedMailDomains(getConfig().COGENT_MAIL_ALLOWED_DOMAINS);
+  } catch {
+    return parseAllowedMailDomains(process.env.COGENT_MAIL_ALLOWED_DOMAINS);
+  }
+}
+function assertAllowedMailDomain(address, field) {
+  const domain = address.split("@")[1]?.toLowerCase() ?? "";
+  const allowed = allowedMailDomains();
+  if (!allowed.includes(domain)) {
+    throw new BridgeError(
+      "INVALID_INPUT" /* INVALID_INPUT */,
+      `${field} domain "${domain}" is not an allowed Cogent mail domain`,
+      `Cogent mail is limited to: ${allowed.join(", ")}. External or corporate-domain mail is a future release.`
+    );
+  }
+}
+var EMAIL_RE, DEFAULT_MAIL_DOMAIN;
 var init_validate = __esm({
   "src/mail/validate.ts"() {
     "use strict";
     init_errors4();
+    init_config();
     EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    DEFAULT_MAIL_DOMAIN = "mail.cogent.tools";
   }
 });
 
@@ -35530,6 +35626,7 @@ function registerSetupMailTool(server) {
     async ({ address, password, imapHost, imapPort, smtpHost, smtpPort }) => {
       try {
         assertValidEmail(address, "address");
+        assertAllowedMailDomain(address, "address");
         await saveMailCredentials({
           address,
           password,
@@ -35560,12 +35657,12 @@ var init_setup_mail = __esm({
 
 // src/mail/mail-sender.ts
 import fs13 from "node:fs/promises";
-import path13 from "node:path";
+import path14 from "node:path";
 async function buildAndSendMail(sender, creds, params) {
   const attachments = [];
   for (const p of params.attachmentPaths ?? []) {
     const content = await fs13.readFile(p);
-    attachments.push({ filename: path13.basename(p), content });
+    attachments.push({ filename: path14.basename(p), content });
   }
   const { messageId } = await sender.send({
     from: creds.address,
@@ -35613,6 +35710,25 @@ var init_mail_sender = __esm({
   }
 });
 
+// src/mail/auth-error.ts
+function isMailAuthError(err) {
+  if (!err || typeof err !== "object") return false;
+  const e = err;
+  if (e.authenticationFailed === true) return true;
+  if (typeof e.serverResponseCode === "string" && e.serverResponseCode.toUpperCase() === "AUTHENTICATIONFAILED") return true;
+  if (e.code === "EAUTH") return true;
+  if (e.responseCode === 535) return true;
+  return false;
+}
+function mailAuthErrorHint() {
+  return "The mail server refused these credentials. The mailbox may be temporarily SUSPENDED by an admin (retry after it is resumed \u2014 your saved credentials will work again), or it was deleted (only then re-run cogent_setup_mail with a fresh address + password). Your local credentials are kept.";
+}
+var init_auth_error = __esm({
+  "src/mail/auth-error.ts"() {
+    "use strict";
+  }
+});
+
 // src/tools/send-mail.ts
 function registerSendMailTool(server, deps = {}) {
   const makeSender = deps.senderFactory ?? ((creds) => new NodemailerMailSender(creds));
@@ -35632,6 +35748,7 @@ function registerSendMailTool(server, deps = {}) {
     async ({ to, subject, body, attachments }) => {
       try {
         assertValidEmail(to, "to");
+        assertAllowedMailDomain(to, "to");
         const creds = await loadMailCredentials();
         if (!creds) {
           return errorResult(
@@ -35650,6 +35767,10 @@ function registerSendMailTool(server, deps = {}) {
         });
         return successResult({ ...result, attachmentCount: attachments?.length ?? 0 });
       } catch (err) {
+        if (isMailAuthError(err)) {
+          const detail = err instanceof Error ? err.message : String(err);
+          return errorResult(new BridgeError("INVALID_INPUT" /* INVALID_INPUT */, `Mailbox login was refused: ${detail}`, mailAuthErrorHint()));
+        }
         return errorResult(err);
       }
     }
@@ -35664,19 +35785,20 @@ var init_send_mail = __esm({
     init_mail_credential_store();
     init_mail_sender();
     init_validate();
+    init_auth_error();
   }
 });
 
 // src/mail/mail-fetcher.ts
 import fs14 from "node:fs/promises";
-import path14 from "node:path";
+import path15 from "node:path";
 async function saveAttachments(attachments, downloadDir) {
   if (attachments.length === 0) return [];
   await fs14.mkdir(downloadDir, { recursive: true });
   const saved = [];
   for (const a of attachments) {
-    const name = path14.basename(a.filename) || "attachment";
-    const savedPath = path14.join(downloadDir, name);
+    const name = path15.basename(a.filename) || "attachment";
+    const savedPath = path15.join(downloadDir, name);
     await fs14.writeFile(savedPath, a.content);
     saved.push({ filename: name, savedPath, size: a.content.length });
   }
@@ -35809,7 +35931,7 @@ var init_mail_fetcher = __esm({
 
 // src/tools/fetch-mail.ts
 import os8 from "node:os";
-import path15 from "node:path";
+import path16 from "node:path";
 function registerFetchMailTool(server, deps = {}) {
   const makeFetcher = deps.fetcherFactory ?? ((creds) => new ImapflowMailFetcher(creds));
   server.registerTool(
@@ -35838,6 +35960,7 @@ function registerFetchMailTool(server, deps = {}) {
             )
           );
         }
+        assertAllowedMailDomain(creds.address, "mailbox");
         const fetcher = makeFetcher(creds);
         if (action === "fetch") {
           if (uid === void 0) {
@@ -35851,6 +35974,10 @@ function registerFetchMailTool(server, deps = {}) {
         const messages = await fetcher.list({ unreadOnly, limit: limit ?? 25 });
         return successResult({ mailbox: creds.address, count: messages.length, messages });
       } catch (err) {
+        if (isMailAuthError(err)) {
+          const detail = err instanceof Error ? err.message : String(err);
+          return errorResult(new BridgeError("INVALID_INPUT" /* INVALID_INPUT */, `Mailbox login was refused: ${detail}`, mailAuthErrorHint()));
+        }
         return errorResult(err);
       }
     }
@@ -35864,7 +35991,94 @@ var init_fetch_mail = __esm({
     init_errors4();
     init_mail_credential_store();
     init_mail_fetcher();
-    DEFAULT_DOWNLOAD_DIR = path15.join(os8.homedir(), ".cogent", "mail-downloads");
+    init_auth_error();
+    init_validate();
+    DEFAULT_DOWNLOAD_DIR = path16.join(os8.homedir(), ".cogent", "mail-downloads");
+  }
+});
+
+// src/tools/rotate-mail-creds.ts
+function registerRotateMailCredsTool(server) {
+  server.registerTool(
+    "cogent_rotate_mail_creds",
+    {
+      title: "Rotate this agent's mailbox password",
+      description: "Rotate (re-key) this agent's Team mailbox password on the mail server and update the local credential store, so cogent_send_mail / cogent_fetch_mail keep working with the fresh secret. Use it if the mailbox password may be compromised. Team channels only.",
+      inputSchema: {},
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
+    },
+    async () => {
+      try {
+        const creds = await loadCredentials();
+        if (!creds || !creds.endpoint || !creds.sessionId || !creds.token) {
+          throw new BridgeError(
+            "INVALID_INPUT" /* INVALID_INPUT */,
+            "Not registered in cloud mode",
+            "Rotation applies to a cloud Team channel \u2014 register the peer first"
+          );
+        }
+        if (!creds.peerId) {
+          throw new BridgeError(
+            "INVALID_INPUT" /* INVALID_INPUT */,
+            "Cannot identify this peer",
+            "Re-register the peer so its peerId is stored, then rotate"
+          );
+        }
+        const url = `${creds.endpoint.replace(/\/+$/, "")}/api/sessions/${encodeURIComponent(creds.sessionId)}/peers/${encodeURIComponent(creds.peerId)}/mail/rotate`;
+        let res;
+        try {
+          res = await fetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/json", authorization: `Bearer ${creds.token}` },
+            body: "{}",
+            signal: AbortSignal.timeout(ROTATE_TIMEOUT_MS)
+          });
+        } catch {
+          throw new BridgeError("NETWORK_TIMEOUT" /* NETWORK_TIMEOUT */, "Could not reach the relay to rotate the mailbox", "Check connectivity and try again");
+        }
+        if (!res.ok) {
+          const detail = await res.text().catch(() => "");
+          throw new BridgeError(
+            "INVALID_INPUT" /* INVALID_INPUT */,
+            `Mailbox rotation was rejected (HTTP ${res.status})`,
+            detail.slice(0, 200) || "Rotation applies to Team channels with a provisioned mailbox"
+          );
+        }
+        const data = await res.json().catch(() => null);
+        if (!data || data.success !== true) {
+          throw new BridgeError("NETWORK_TIMEOUT" /* NETWORK_TIMEOUT */, "Mailbox rotation failed", "The relay returned an unexpected response");
+        }
+        if (!data.rotated) {
+          return successResult({ rotated: false, reason: data.reason ?? "no_mailbox" });
+        }
+        if (!data.address || !data.password) {
+          throw new BridgeError("NETWORK_TIMEOUT" /* NETWORK_TIMEOUT */, "Rotation returned no new password", "Try again; the mailbox password was not updated locally");
+        }
+        const existing = await loadMailCredentials();
+        await saveMailCredentials({
+          address: data.address,
+          password: data.password,
+          imapHost: existing?.imapHost ?? MAIL_DEFAULT_HOST,
+          imapPort: existing?.imapPort ?? 993,
+          smtpHost: existing?.smtpHost ?? MAIL_DEFAULT_HOST,
+          smtpPort: existing?.smtpPort ?? 465,
+          savedAt: (/* @__PURE__ */ new Date()).toISOString()
+        });
+        return successResult({ rotated: true, address: data.address });
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+}
+var ROTATE_TIMEOUT_MS;
+var init_rotate_mail_creds = __esm({
+  "src/tools/rotate-mail-creds.ts"() {
+    "use strict";
+    init_errors4();
+    init_credential_store();
+    init_mail_credential_store();
+    ROTATE_TIMEOUT_MS = 8e3;
   }
 });
 
@@ -35884,6 +36098,7 @@ async function main() {
   registerSetupMailTool(server);
   registerSendMailTool(server);
   registerFetchMailTool(server);
+  registerRotateMailCredsTool(server);
   if (cloudInbox) {
     server.registerResource(
       "cogent_inbox",
@@ -35946,6 +36161,7 @@ var init_index = __esm({
     init_setup_mail();
     init_send_mail();
     init_fetch_mail();
+    init_rotate_mail_creds();
     init_heartbeat();
     process.on("uncaughtException", (err) => {
       if (err.code === "EPIPE") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@essentialai/cogent-plugin",
-  "version": "3.16.0",
+  "version": "3.18.0",
   "description": "Cogent — Claude Code plugin (skills + slash-commands + MCP server) for the cross-agent comms fabric.",
   "author": { "name": "Essential AI Solutions Ltd.", "url": "https://essentialai.uk" },
   "homepage": "https://cogent.tools",