@wrongstack/core 0.313.0 → 0.313.1

package/dist/chunk-RD6DEE36.js

@@ -0,0 +1,1178 @@
+import {
+  MAILBOX_PROJECT_SERVER_MAX_FRAME_CHARS,
+  MAILBOX_PROJECT_SERVER_PROTOCOL_VERSION,
+  SQLITE_MAILBOX_FILE,
+  encodeMailboxProjectServerMessage,
+  isMailboxProjectServerMessage,
+  mailboxProjectServerEndpoint,
+  mailboxProjectServerMetadataPath
+} from "./chunk-5RP3QTRL.js";
+import {
+  HQ_MAILBOX_SNAPSHOT_MIN_INTERVAL_MS,
+  resolveProjectDir,
+  resolveSendTypeSafe
+} from "./chunk-GM54GJBU.js";
+import {
+  acceptMailboxMessageForSession,
+  isMailboxMessageVisibleTo,
+  normalizeRecipient
+} from "./chunk-W4A6QA3D.js";
+import {
+  ToolCapabilities
+} from "./chunk-A455ATZB.js";
+import {
+  wstackGlobalRoot
+} from "./chunk-YNCVSFGF.js";
+import {
+  toErrorMessage
+} from "./chunk-TBRL2RCC.js";
+
+// src/coordination/mailbox-project-server-client.ts
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as net from "node:net";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+var CONNECT_ATTEMPT_TIMEOUT_MS = 750;
+var SERVER_START_TIMEOUT_MS = 1e4;
+var DEFAULT_CALL_TIMEOUT_MS = 3e4;
+var DEFAULT_HEARTBEAT_INTERVAL_MS = 1e4;
+var AUTH_RETRY_DELAY_MS = 150;
+var AUTH_RETRY_MAX_ATTEMPTS = 13;
+function normalizePath(value) {
+  const resolved = path.resolve(value);
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+function resolveProjectServerUrl() {
+  for (const relative of [
+    // Unbundled / per-subpath output: dist/coordination/index.js.
+    "./mailbox-project-server.js",
+    // Root-level output — dist/index.js and, since core is built with code
+    // splitting, the shared chunks that sit next to it. Without this entry the
+    // lookup silently reports missing-build and every process quietly opens
+    // its own store, which is exactly the "one mailbox per project" invariant
+    // this resolver exists to protect.
+    "./coordination/mailbox-project-server.js",
+    "../../dist/coordination/mailbox-project-server.js"
+  ]) {
+    try {
+      const url = new URL(relative, import.meta.url);
+      if (url.protocol === "file:" && fs.existsSync(fileURLToPath(url))) return url;
+    } catch {
+    }
+  }
+  return null;
+}
+function isMailboxProjectServerAvailable() {
+  return resolveProjectServerUrl() !== null;
+}
+function delay(ms) {
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
+}
+function isUnauthorizedMailboxError(error) {
+  return error instanceof Error && error.name === "UnauthorizedMailboxRequest";
+}
+var MailboxProjectServerConnection = class {
+  constructor(projectDir) {
+    this.projectDir = projectDir;
+    this.projectDir = path.resolve(projectDir);
+    this.endpoint = mailboxProjectServerEndpoint(this.projectDir);
+    this.state = {
+      status: isMailboxProjectServerAvailable() ? "offline" : "unavailable",
+      connected: false,
+      projectDir: this.projectDir,
+      endpoint: this.endpoint
+    };
+  }
+  projectDir;
+  endpoint;
+  socket = null;
+  info = null;
+  buffer = "";
+  connecting = null;
+  connectResolve = null;
+  connectReject = null;
+  nextId = 1;
+  /**
+   * WS-027: read from the daemon's owner-only metadata file, never from the
+   * `hello` frame — the daemon sends `hello` to every socket that connects, so
+   * a token carried there would be handed to exactly the caller it must
+   * refuse (the mistake WS-028 found in the SAGE daemon).
+   */
+  authToken;
+  heartbeatTimer = null;
+  pending = /* @__PURE__ */ new Map();
+  eventListeners = /* @__PURE__ */ new Set();
+  mailboxEventListeners = /* @__PURE__ */ new Set();
+  stateListeners = /* @__PURE__ */ new Set();
+  state;
+  getState() {
+    return { ...this.state };
+  }
+  onStateChange(listener) {
+    this.stateListeners.add(listener);
+    return () => this.stateListeners.delete(listener);
+  }
+  onEvent(listener) {
+    this.eventListeners.add(listener);
+    return () => this.eventListeners.delete(listener);
+  }
+  onMailboxEvent(listener) {
+    this.mailboxEventListeners.add(listener);
+    return () => this.mailboxEventListeners.delete(listener);
+  }
+  async connect() {
+    await this.ensureConnected(true);
+  }
+  async status() {
+    return this.call("ping", {}, { timeoutMs: 3e3 });
+  }
+  /**
+   * Inspect an existing project server without starting one.
+   * Returns null when no server is running (ECONNREFUSED / timeout).
+   * Mirrors the SAGE `status()` probe pattern.
+   */
+  async probeStatus() {
+    try {
+      await this.ensureConnected(false);
+      return await this.request(
+        { type: "request", op: "ping", args: {} },
+        3e3
+      );
+    } catch {
+      this.close();
+      return null;
+    }
+  }
+  async call(op, args, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_CALL_TIMEOUT_MS;
+    let lastError;
+    for (let attempt = 0; attempt <= AUTH_RETRY_MAX_ATTEMPTS; attempt++) {
+      try {
+        await this.ensureConnected(true);
+        return await this.request(
+          { type: "request", op, args },
+          timeoutMs
+        );
+      } catch (error) {
+        lastError = error;
+        const retriable = isUnauthorizedMailboxError(error) && attempt < AUTH_RETRY_MAX_ATTEMPTS;
+        if (!retriable) throw error;
+        await delay(AUTH_RETRY_DELAY_MS);
+      }
+    }
+    throw lastError;
+  }
+  async shutdown(reason) {
+    try {
+      await this.ensureConnected(false);
+    } catch {
+      return { stopped: false, reason: "offline" };
+    }
+    const pid = this.info?.pid;
+    const result = await this.request(
+      { type: "shutdown", reason },
+      5e3
+    );
+    return { ...result, ...pid !== void 0 && result.pid === void 0 ? { pid } : {} };
+  }
+  close() {
+    this.stopHeartbeat();
+    const socket = this.socket;
+    this.socket = null;
+    this.info = null;
+    socket?.destroy();
+    this.rejectPending(new Error("Mailbox project server connection closed"));
+    this.transition("offline");
+  }
+  transition(status, error) {
+    this.state = {
+      status,
+      connected: status === "connected",
+      projectDir: this.projectDir,
+      endpoint: this.endpoint,
+      ...status === "connected" && this.info ? { pid: this.info.pid } : {},
+      ...error !== void 0 ? { lastError: error instanceof Error ? error.message : String(error) } : {}
+    };
+    for (const listener of [...this.stateListeners]) listener({ ...this.state });
+  }
+  async ensureConnected(spawnIfMissing) {
+    if (this.socket && !this.socket.destroyed && this.info) return;
+    if (this.connecting) return this.connecting;
+    if (!isMailboxProjectServerAvailable()) {
+      this.transition("unavailable");
+      throw new Error(
+        "Built mailbox project server is unavailable. Run `pnpm --filter @wrongstack/core build`. The mailbox has no in-process mode: there is no env var to fall back to, by design."
+      );
+    }
+    this.transition("connecting");
+    this.connecting = this.connectWithElection(spawnIfMissing).catch((error) => {
+      this.transition("error", error);
+      throw error;
+    }).finally(() => {
+      this.connecting = null;
+    });
+    return this.connecting;
+  }
+  async connectWithElection(spawnIfMissing) {
+    const deadline = Date.now() + (spawnIfMissing ? SERVER_START_TIMEOUT_MS : CONNECT_ATTEMPT_TIMEOUT_MS);
+    let spawned = false;
+    let lastError = new Error("Mailbox project server unavailable");
+    while (Date.now() < deadline) {
+      try {
+        await this.connectOnce();
+        return;
+      } catch (error) {
+        lastError = error;
+      }
+      if (!spawnIfMissing) break;
+      if (!spawned) {
+        this.spawnDetachedServer();
+        spawned = true;
+      }
+      await delay(75);
+    }
+    throw lastError;
+  }
+  connectOnce() {
+    this.socket?.destroy();
+    this.socket = null;
+    this.info = null;
+    this.buffer = "";
+    this.authToken = void 0;
+    return new Promise((resolve3, reject) => {
+      const socket = net.createConnection(this.endpoint);
+      this.socket = socket;
+      socket.setEncoding("utf8");
+      const timer = setTimeout(() => {
+        this.connectReject?.(new Error("Mailbox project server handshake timed out"));
+        socket.destroy();
+      }, CONNECT_ATTEMPT_TIMEOUT_MS);
+      timer.unref?.();
+      this.connectResolve = () => {
+        clearTimeout(timer);
+        this.connectResolve = null;
+        this.connectReject = null;
+        this.startHeartbeat();
+        this.transition("connected");
+        resolve3();
+        void this.request({ type: "request", op: "ping", args: {} }, 3e3).catch(
+          () => void 0
+        );
+      };
+      this.connectReject = (error) => {
+        clearTimeout(timer);
+        this.connectResolve = null;
+        this.connectReject = null;
+        reject(error);
+      };
+      socket.on("data", (chunk) => this.onData(socket, chunk));
+      socket.on("error", (error) => {
+        if (!this.info) this.connectReject?.(error);
+      });
+      socket.on("close", () => this.onClose(socket));
+    });
+  }
+  /**
+   * The token, read lazily and re-read while still unknown.
+   *
+   * The daemon starts listening before it writes its metadata (endpoint
+   * ownership has to be won first, and clobbering another daemon's file to win
+   * it would be worse), so a client that connects in that window sees no file
+   * yet. Re-reading until one is found costs a single small `readFileSync`.
+   */
+  currentAuthToken() {
+    if (this.authToken === void 0) {
+      try {
+        const raw = fs.readFileSync(mailboxProjectServerMetadataPath(this.projectDir), "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.authToken === "string" && parsed.authToken.length > 0) {
+          this.authToken = parsed.authToken;
+        }
+      } catch {
+      }
+    }
+    return this.authToken;
+  }
+  request(message, timeoutMs) {
+    const socket = this.socket;
+    if (!socket || socket.destroyed) {
+      return Promise.reject(new Error("Mailbox project server connection is unavailable"));
+    }
+    const id = this.nextId++;
+    const encoded = encodeMailboxProjectServerMessage({
+      ...message,
+      id,
+      authToken: this.currentAuthToken()
+    });
+    if (encoded.length > MAILBOX_PROJECT_SERVER_MAX_FRAME_CHARS) {
+      return Promise.reject(new Error("Mailbox project server request exceeded frame limit"));
+    }
+    return new Promise((resolve3, reject) => {
+      const timer = setTimeout(() => {
+        const pending = this.pending.get(id);
+        if (!pending) return;
+        this.pending.delete(id);
+        pending.reject(new Error(`Mailbox ${message.type} exceeded its ${timeoutMs}ms timeout`));
+      }, timeoutMs);
+      timer.unref?.();
+      this.pending.set(id, { resolve: resolve3, reject, timer });
+      socket.write(encoded);
+    });
+  }
+  onData(socket, chunk) {
+    if (socket !== this.socket) return;
+    this.buffer += chunk;
+    while (true) {
+      const newline = this.buffer.indexOf("\n");
+      if (newline < 0) {
+        if (this.buffer.length > MAILBOX_PROJECT_SERVER_MAX_FRAME_CHARS) {
+          socket.destroy(new Error("Mailbox project server response exceeded frame limit"));
+        }
+        return;
+      }
+      if (newline > MAILBOX_PROJECT_SERVER_MAX_FRAME_CHARS) {
+        socket.destroy(new Error("Mailbox project server response exceeded frame limit"));
+        return;
+      }
+      const line = this.buffer.slice(0, newline);
+      this.buffer = this.buffer.slice(newline + 1);
+      if (!line) continue;
+      let parsed;
+      try {
+        parsed = JSON.parse(line);
+      } catch {
+        socket.destroy(new Error("Invalid mailbox project server response"));
+        return;
+      }
+      if (!isMailboxProjectServerMessage(parsed)) {
+        socket.destroy(new Error("Invalid mailbox project server response"));
+        return;
+      }
+      this.onMessage(parsed);
+    }
+  }
+  onMessage(message) {
+    if (message.type === "hello") {
+      if (message.protocolVersion !== MAILBOX_PROJECT_SERVER_PROTOCOL_VERSION) {
+        this.connectReject?.(
+          new Error(
+            `Mailbox protocol mismatch: client=${MAILBOX_PROJECT_SERVER_PROTOCOL_VERSION}, server=${message.protocolVersion}`
+          )
+        );
+        this.socket?.destroy();
+        return;
+      }
+      if (normalizePath(message.projectDir) !== normalizePath(this.projectDir)) {
+        this.connectReject?.(new Error("Mailbox project server identity mismatch"));
+        this.socket?.destroy();
+        return;
+      }
+      this.info = message;
+      this.connectResolve?.();
+      return;
+    }
+    if (message.type === "event") {
+      for (const listener of [...this.eventListeners]) listener(message.event, message.payload);
+      return;
+    }
+    if (message.type === "mailbox-event") {
+      for (const listener of [...this.mailboxEventListeners]) listener(message.event);
+      return;
+    }
+    const pending = this.pending.get(message.id);
+    if (!pending) return;
+    this.pending.delete(message.id);
+    clearTimeout(pending.timer);
+    if (message.ok) pending.resolve(message.result);
+    else {
+      if (message.errorName === "UnauthorizedMailboxRequest") this.authToken = void 0;
+      const error = new Error(message.error);
+      if (message.errorName) error.name = message.errorName;
+      pending.reject(error);
+    }
+  }
+  onClose(socket) {
+    if (socket !== this.socket) return;
+    this.socket = null;
+    this.info = null;
+    this.stopHeartbeat();
+    const error = new Error("Mailbox project server connection closed");
+    this.connectReject?.(error);
+    this.connectResolve = null;
+    this.connectReject = null;
+    this.rejectPending(error);
+    this.transition("offline");
+  }
+  rejectPending(error) {
+    const pending = [...this.pending.values()];
+    this.pending.clear();
+    for (const item of pending) {
+      clearTimeout(item.timer);
+      item.reject(error);
+    }
+  }
+  startHeartbeat() {
+    this.stopHeartbeat();
+    const configured = Number(process.env["WRONGSTACK_MAILBOX_CLIENT_HEARTBEAT_MS"]);
+    const intervalMs = Number.isFinite(configured) && configured >= 50 ? configured : DEFAULT_HEARTBEAT_INTERVAL_MS;
+    this.heartbeatTimer = setInterval(() => {
+      const socket = this.socket;
+      if (socket && !socket.destroyed) {
+        socket.write(encodeMailboxProjectServerMessage({ type: "heartbeat" }));
+      }
+    }, intervalMs);
+    this.heartbeatTimer.unref?.();
+  }
+  stopHeartbeat() {
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+    this.heartbeatTimer = null;
+  }
+  spawnDetachedServer() {
+    const url = resolveProjectServerUrl();
+    if (!url) throw new Error("Mailbox project server entrypoint is unavailable");
+    fs.mkdirSync(this.projectDir, { recursive: true });
+    const child = spawn(process.execPath, [fileURLToPath(url), "--project-dir", this.projectDir], {
+      cwd: this.projectDir,
+      detached: process.platform !== "win32",
+      stdio: "ignore",
+      windowsHide: true,
+      env: process.env
+    });
+    child.unref();
+  }
+};
+
+// src/coordination/remote-mailbox.ts
+import * as path2 from "node:path";
+var HQ_MAILBOX_EVENT_MAX_PENDING = 256;
+var sharedRemoteMailboxes = /* @__PURE__ */ new Map();
+var sharedProjectConnections = /* @__PURE__ */ new Map();
+function dependencyCache() {
+  return { byPublisher: /* @__PURE__ */ new WeakMap() };
+}
+var RemoteMailbox = class {
+  projectDir;
+  messagePath;
+  registryPath;
+  clientRegistryPath;
+  connection;
+  ownsConnection;
+  sharedConnectionKey;
+  events;
+  hqPublisherRef;
+  eventEmitter;
+  unsubscribeEvent;
+  unsubscribeMailboxEvent;
+  cacheEviction;
+  closed = false;
+  /** Pending coalesced HQ snapshot; see {@link scheduleHqSnapshot}. */
+  hqSnapshotTimer;
+  hqSnapshotLastAt = 0;
+  /** At most one full snapshot may query/map/serialize mailbox state at a time. */
+  hqSnapshotInFlight;
+  /** Latest scope requested while a timer or snapshot is already active. */
+  hqSnapshotPendingMailboxId;
+  /** Message deltas are serialized so a burst cannot launch one full mailbox
+   * query per event concurrently. Newer updates for the same message replace
+   * older pending ones; the periodic snapshot remains the lossless rollup. */
+  hqEventPending = /* @__PURE__ */ new Map();
+  hqEventInFlight;
+  hqEventCoalesced = 0;
+  hqEventDropped = 0;
+  constructor(optionsOrProjectDir, events, hqPublisher, eventEmitter) {
+    const options = typeof optionsOrProjectDir === "string" ? {
+      projectDir: optionsOrProjectDir,
+      events,
+      hqPublisher,
+      eventEmitter
+    } : optionsOrProjectDir;
+    this.projectDir = path2.resolve(options.projectDir);
+    this.messagePath = path2.join(this.projectDir, SQLITE_MAILBOX_FILE);
+    this.registryPath = this.messagePath;
+    this.clientRegistryPath = this.messagePath;
+    this.events = options.events;
+    this.hqPublisherRef = options.hqPublisher;
+    this.eventEmitter = options.eventEmitter;
+    if (options.isolatedConnection) {
+      this.connection = new MailboxProjectServerConnection(this.projectDir);
+      this.ownsConnection = true;
+    } else {
+      let entry = sharedProjectConnections.get(this.projectDir);
+      if (!entry) {
+        entry = {
+          connection: new MailboxProjectServerConnection(this.projectDir),
+          references: 0
+        };
+        sharedProjectConnections.set(this.projectDir, entry);
+      }
+      entry.references++;
+      this.connection = entry.connection;
+      this.sharedConnectionKey = this.projectDir;
+      this.ownsConnection = false;
+    }
+    this.unsubscribeEvent = this.connection.onEvent((event, payload) => {
+      this.events?.emitCustom(event, payload);
+      this.publishHqRegistryEvent(event, payload);
+    });
+    this.unsubscribeMailboxEvent = this.connection.onMailboxEvent((event) => {
+      this.eventEmitter?.emit(event);
+      this.publishHqEvent(event);
+    });
+    void this.connection.connect().catch(() => {
+    });
+  }
+  getConnectionState() {
+    return this.connection.getState();
+  }
+  onConnectionStateChange(listener) {
+    return this.connection.onStateChange(listener);
+  }
+  async initialize() {
+    await this.connection.connect();
+    await this.connection.status();
+  }
+  async status() {
+    return this.connection.status();
+  }
+  send(input) {
+    return this.connection.call("send", { input });
+  }
+  sendRuntimeControl(input) {
+    return this.connection.call("sendRuntimeControl", { input });
+  }
+  query(query) {
+    return this.connection.call("query", { query });
+  }
+  ack(input) {
+    return this.connection.call("ack", { input });
+  }
+  ackMany(input) {
+    return this.connection.call("ackMany", { input });
+  }
+  unreadCount(forAgentId, sessionId) {
+    return this.connection.call("unreadCount", { forAgentId, sessionId });
+  }
+  softDelete(mailId, by) {
+    return this.connection.call("softDelete", { mailId, by });
+  }
+  restore(mailId) {
+    return this.connection.call("restore", { mailId });
+  }
+  registerAgent(input) {
+    return this.connection.call("registerAgent", { input });
+  }
+  deregisterAgent(agentId) {
+    return this.connection.call("deregisterAgent", { agentId });
+  }
+  heartbeat(input) {
+    return this.connection.call("heartbeat", { input });
+  }
+  getAgentStatuses() {
+    return this.connection.call("getAgentStatuses", {});
+  }
+  getOnlineAgents() {
+    return this.connection.call("getOnlineAgents", {});
+  }
+  purgeAgents(maxAgeMs) {
+    return this.connection.call("purgeAgents", { maxAgeMs });
+  }
+  registerClient(input) {
+    return this.connection.call("registerClient", { input });
+  }
+  deregisterClient(clientId) {
+    return this.connection.call("deregisterClient", { clientId });
+  }
+  clientHeartbeat(input) {
+    return this.connection.call("clientHeartbeat", { input });
+  }
+  getClientStatuses() {
+    return this.connection.call("getClientStatuses", {});
+  }
+  purgeClients() {
+    return this.connection.call("purgeClients", {});
+  }
+  clearAll() {
+    return this.connection.call("clearAll", {});
+  }
+  purgeStale(options) {
+    return this.connection.call("purgeStale", { options });
+  }
+  autoCompact(options) {
+    return this.connection.call("autoCompact", { options }, { timeoutMs: 2 * 6e4 });
+  }
+  credentialIssue(options) {
+    return this.connection.call("credentialIssue", { options });
+  }
+  credentialVerify(credentialId, secret) {
+    return this.connection.call("credentialVerify", { credentialId, secret });
+  }
+  credentialRevoke(credentialId, reason, by) {
+    return this.connection.call("credentialRevoke", { credentialId, reason, by });
+  }
+  credentialRotate(credentialId, options) {
+    return this.connection.call("credentialRotate", { credentialId, options });
+  }
+  credentialGet(credentialId) {
+    return this.connection.call("credentialGet", { credentialId });
+  }
+  credentialList() {
+    return this.connection.call("credentialList", {});
+  }
+  credentialStatusCounts() {
+    return this.connection.call("credentialStatusCounts", {});
+  }
+  startAutoCompactTimer(_options) {
+    return () => {
+    };
+  }
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.hqSnapshotTimer !== void 0) {
+      clearTimeout(this.hqSnapshotTimer);
+      this.hqSnapshotTimer = void 0;
+    }
+    this.hqSnapshotPendingMailboxId = void 0;
+    this.hqEventPending.clear();
+    this.cacheEviction?.();
+    this.cacheEviction = void 0;
+    this.unsubscribeEvent();
+    this.unsubscribeMailboxEvent();
+    if (this.ownsConnection) {
+      this.connection.close();
+      return;
+    }
+    if (this.sharedConnectionKey !== void 0) {
+      const entry = sharedProjectConnections.get(this.sharedConnectionKey);
+      if (entry?.connection === this.connection) {
+        entry.references = Math.max(0, entry.references - 1);
+        if (entry.references === 0) {
+          entry.connection.close();
+          sharedProjectConnections.delete(this.sharedConnectionKey);
+        }
+      }
+    }
+  }
+  /** @internal Remove a process-shared wrapper from its cache when explicitly closed. */
+  setCacheEviction(evict) {
+    this.cacheEviction = evict;
+  }
+  /** Lightweight diagnostics for the process memory flight recorder. */
+  getHqSnapshotStats() {
+    return {
+      inFlight: this.hqSnapshotInFlight !== void 0,
+      pending: this.hqSnapshotPendingMailboxId !== void 0,
+      timerScheduled: this.hqSnapshotTimer !== void 0,
+      eventInFlight: this.hqEventInFlight !== void 0,
+      pendingEvents: this.hqEventPending.size,
+      coalescedEvents: this.hqEventCoalesced,
+      droppedEvents: this.hqEventDropped
+    };
+  }
+  get hqPublisher() {
+    return typeof this.hqPublisherRef === "function" ? this.hqPublisherRef() : this.hqPublisherRef;
+  }
+  /**
+   * Publish a full HQ mailbox snapshot, at most once per
+   * {@link HQ_MAILBOX_SNAPSHOT_MIN_INTERVAL_MS}.
+   *
+   * Trailing-edge: the first caller after the interval schedules one, and
+   * every caller in the window folds into it. The snapshot is a rollup of
+   * current state, so a coalesced publish carries strictly more up-to-date
+   * information than the ones it replaced — dropping them loses nothing.
+   */
+  scheduleHqSnapshot(mailboxId) {
+    if (this.closed) return;
+    this.hqSnapshotPendingMailboxId = mailboxId;
+    if (this.hqSnapshotTimer !== void 0 || this.hqSnapshotInFlight !== void 0) return;
+    const elapsed = Date.now() - this.hqSnapshotLastAt;
+    const delay2 = Math.max(0, HQ_MAILBOX_SNAPSHOT_MIN_INTERVAL_MS - elapsed);
+    this.hqSnapshotTimer = setTimeout(() => {
+      this.hqSnapshotTimer = void 0;
+      const pendingMailboxId = this.hqSnapshotPendingMailboxId;
+      this.hqSnapshotPendingMailboxId = void 0;
+      const publisher = this.hqPublisher;
+      if (this.closed || !publisher || pendingMailboxId === void 0) return;
+      this.hqSnapshotLastAt = Date.now();
+      const inFlight = (async () => {
+        try {
+          await publisher.publishMailboxSnapshot(this, { mailboxId: pendingMailboxId });
+        } catch {
+        } finally {
+          this.hqSnapshotInFlight = void 0;
+          const nextMailboxId = this.hqSnapshotPendingMailboxId;
+          if (!this.closed && nextMailboxId !== void 0) {
+            this.scheduleHqSnapshot(nextMailboxId);
+          }
+        }
+      })();
+      this.hqSnapshotInFlight = inFlight;
+    }, delay2);
+    this.hqSnapshotTimer.unref?.();
+  }
+  publishHqEvent(event) {
+    if (!this.hqPublisher || this.closed) return;
+    if (this.hqEventPending.has(event.messageId)) {
+      this.hqEventCoalesced += 1;
+    } else if (this.hqEventPending.size >= HQ_MAILBOX_EVENT_MAX_PENDING) {
+      const oldest = this.hqEventPending.keys().next().value;
+      if (oldest !== void 0) this.hqEventPending.delete(oldest);
+      this.hqEventDropped += 1;
+    }
+    this.hqEventPending.set(event.messageId, event);
+    this.drainHqEvents();
+  }
+  drainHqEvents() {
+    if (this.closed || this.hqEventInFlight !== void 0) return;
+    const next = this.hqEventPending.entries().next().value;
+    if (!next) return;
+    const [messageId, event] = next;
+    this.hqEventPending.delete(messageId);
+    const publisher = this.hqPublisher;
+    if (!publisher) {
+      this.hqEventPending.clear();
+      return;
+    }
+    const mailboxId = `${path2.basename(this.projectDir)}:mailbox`;
+    const inFlight = this.query({ includeDeleted: true, limit: 100 }).then((messages) => {
+      const message = messages.find((candidate) => candidate.id === event.messageId);
+      const action = event.type === "message.sent" ? "message.sent" : "message.updated";
+      publisher.publishMailboxEvent({
+        mailboxId,
+        action,
+        ...message ? { message } : {},
+        timestamp: event.timestamp
+      });
+      this.scheduleHqSnapshot(mailboxId);
+    }).catch(() => {
+    }).finally(() => {
+      this.hqEventInFlight = void 0;
+      this.drainHqEvents();
+    });
+    this.hqEventInFlight = inFlight;
+  }
+  publishHqRegistryEvent(event, payload) {
+    const publisher = this.hqPublisher;
+    if (!publisher || this.closed || !event.startsWith("mailbox.agent_") && !event.startsWith("mailbox.client_")) {
+      return;
+    }
+    const mailboxId = `${path2.basename(this.projectDir)}:mailbox`;
+    const record = typeof payload === "object" && payload !== null ? payload : {};
+    const agentId = typeof record["agentId"] === "string" ? record["agentId"] : void 0;
+    const action = event === "mailbox.agent_registered" ? "agent.registered" : event === "mailbox.agent_heartbeat" ? "agent.heartbeat" : event === "mailbox.agent_deregistered" ? "agent.deregistered" : void 0;
+    if (action !== "agent.registered") {
+      if (action) {
+        publisher.publishMailboxEvent({
+          mailboxId,
+          action,
+          ...agentId ? { summary: agentId } : {}
+        });
+      }
+      if (action !== "agent.heartbeat") this.scheduleHqSnapshot(mailboxId);
+      return;
+    }
+    void this.getAgentStatuses().then((statuses) => {
+      if (this.closed) return;
+      const agent = agentId ? statuses.find((candidate) => candidate.agentId === agentId) : void 0;
+      publisher.publishMailboxEvent({
+        mailboxId,
+        action,
+        ...agent ? { agent } : {},
+        ...agentId ? { summary: agentId } : {}
+      });
+      this.scheduleHqSnapshot(mailboxId);
+    }).catch(() => {
+    });
+  }
+};
+function createProjectMailbox(options) {
+  return new RemoteMailbox(options);
+}
+function getSharedProjectMailbox(projectDir, events, hqPublisher) {
+  const key = path2.resolve(projectDir);
+  let projectCache = sharedRemoteMailboxes.get(key);
+  if (!projectCache) {
+    projectCache = {
+      withoutEvents: dependencyCache(),
+      byEvents: /* @__PURE__ */ new WeakMap()
+    };
+    sharedRemoteMailboxes.set(key, projectCache);
+  }
+  let dependencies = projectCache.withoutEvents;
+  if (events) {
+    dependencies = projectCache.byEvents.get(events) ?? dependencyCache();
+    projectCache.byEvents.set(events, dependencies);
+  }
+  if (!hqPublisher) {
+    if (!dependencies.withoutPublisher) {
+      const mailbox2 = new RemoteMailbox(key, events);
+      dependencies.withoutPublisher = mailbox2;
+      mailbox2.setCacheEviction(() => {
+        if (dependencies.withoutPublisher === mailbox2) {
+          delete dependencies.withoutPublisher;
+        }
+      });
+    }
+    return dependencies.withoutPublisher;
+  }
+  const publisherKey = Object(hqPublisher);
+  const existing = dependencies.byPublisher.get(publisherKey);
+  if (existing) return existing;
+  const mailbox = new RemoteMailbox(key, events, hqPublisher);
+  dependencies.byPublisher.set(publisherKey, mailbox);
+  mailbox.setCacheEviction(() => {
+    if (dependencies.byPublisher.get(publisherKey) === mailbox) {
+      dependencies.byPublisher.delete(publisherKey);
+    }
+  });
+  return mailbox;
+}
+
+// src/coordination/mailbox-tool.ts
+import { createHash } from "node:crypto";
+function defaultResolveProjectDir(ctx) {
+  return resolveProjectDir(ctx.projectRoot, wstackGlobalRoot());
+}
+function mailboxSessionTag(sessionId) {
+  return createHash("sha256").update(sessionId).digest("hex").slice(0, 8);
+}
+function resolveMailboxIdentity(ctx, fallbackBase = "leader") {
+  const fieldId = ctx.agentId && ctx.agentId !== "unknown" ? ctx.agentId : void 0;
+  const baseId = ctx.meta["agentId"] ?? fieldId ?? fallbackBase;
+  const sessionId = ctx.meta["sessionId"] ?? ctx.session?.id ?? "default";
+  const callerId = ctx.meta["globalAgentId"] ?? `${baseId}@${mailboxSessionTag(sessionId)}`;
+  const fieldName = ctx.agentName && ctx.agentName !== "Unknown Agent" ? ctx.agentName : void 0;
+  const name = ctx.meta["agentName"] ?? fieldName ?? baseId;
+  const role = ctx.meta["agentRole"];
+  return { baseId, callerId, name, role, sessionId };
+}
+function applyMailboxSendPolicy(ctx, identity, requestedTo, requestedAudience) {
+  const policy = ctx.meta["mailboxSendPolicy"];
+  const isChimeraIdentity = (value) => {
+    const normalized = value.trim().toLowerCase();
+    return normalized === "chimera" || normalized.startsWith("chimera-");
+  };
+  const chimeraSender = isChimeraIdentity(identity.baseId) || isChimeraIdentity(identity.name);
+  if (policy === "leaders-only" || chimeraSender) {
+    return { to: "leader", audience: "leaders" };
+  }
+  return {
+    to: requestedTo,
+    ...requestedAudience !== void 0 ? { audience: requestedAudience } : {}
+  };
+}
+function makeMailboxTool(opts = {}) {
+  const resolveMailbox = opts.resolveMailbox ?? ((ctx) => {
+    const dir = opts.projectDir ?? defaultResolveProjectDir(ctx);
+    return getSharedProjectMailbox(dir, opts.events);
+  });
+  const agentId = opts.agentId ?? "leader";
+  const sessionId = opts.sessionId ?? "default";
+  const shortHint = "Sub-commands: check (unread), send (exact/base/@session/project broadcast), ack (read/complete), query (filter), status (all agents), online (active only), unread (count).";
+  return {
+    name: "mailbox",
+    description: 'Low-level inter-agent mailbox with 7 actions (check, send, ack, query, status, online, unread). For most use cases, prefer the simpler `mail_send` and `mail_inbox` tools \u2014 they cover the common send/read operations with a cleaner interface. This tool is for advanced queries (filter by sender, sender session, priority, since-timestamp), agent status/online lists, and message ack/control. Use to="@session" only for session-local coordination; use "*" or a base alias when another session may be affected.',
+    usageHint: shortHint + " For simple send/read, use mail_send / mail_inbox instead.",
+    category: "Coordination",
+    permission: "auto",
+    mutating: true,
+    capabilities: [ToolCapabilities.COORDINATION_MAIL],
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["check", "send", "ack", "query", "status", "online", "unread"],
+          description: "Which mailbox operation to perform."
+        },
+        to: { type: "string", description: "Recipient agent id, base alias, '@session' for the sender's session, or '*' / 'all' for project broadcast." },
+        type: { type: "string", enum: ["note", "ask", "assign", "steer", "btw", "broadcast", "status", "result", "review", "control"], description: "Required message intent. Actionable: ask (blocking question), assign (task delegation, must have specific to), steer (mid-course direction), review (passive ask). Informational: note (general FYI), btw (low-priority aside), result (completion notice), status (system update). Routing: broadcast (multi-recipient). Reserved: control (runtime only, agents cannot send)." },
+        subject: { type: "string", description: "Short subject line." },
+        body: { type: "string", description: "Full message content." },
+        priority: { type: "string", enum: ["low", "normal", "high"] },
+        audience: { type: "string", enum: ["all", "leaders"], description: 'Delivery audience. "leaders" prevents subagent consumption.' },
+        replyTo: { type: "string", description: "Reply to a specific message id." },
+        messageId: { type: "string", description: "Message id to acknowledge. Required for 'ack'." },
+        read: { type: "boolean", description: "Mark as read (adds read receipt)." },
+        markRead: { type: "boolean", description: "For action=check, add read receipts for returned messages (default true)." },
+        completed: { type: "boolean", description: "Mark as completed. For action=check, completes every returned message." },
+        outcome: { type: "string", description: "Outcome summary when marking complete." },
+        unreadBy: { type: "string", description: "Filter messages unread by this agent. Used by 'check'." },
+        incompleteOnly: { type: "boolean", description: "Only incomplete messages." },
+        from: { type: "string", description: "Filter by sender." },
+        minPriority: { type: "string", enum: ["low", "normal", "high"] },
+        since: { type: "string", description: "ISO8601 timestamp \u2014 only messages after this." },
+        sessionId: { type: "string", description: "Filter query results by sender session id." },
+        limit: { type: "number", description: "Max messages to return." }
+      },
+      required: ["action"]
+    },
+    async execute(input, ctx) {
+      const mb = resolveMailbox(ctx);
+      const i = input ?? {};
+      const action = i.action;
+      const identity = resolveMailboxIdentity(ctx, agentId);
+      const baseCallerId = identity.baseId;
+      const callerId = identity.callerId;
+      const callerSessionId = ctx.meta["sessionId"] ?? (ctx.session?.id ?? sessionId);
+      try {
+        await mb.registerAgent({
+          agentId: callerId,
+          sessionId: callerSessionId,
+          name: identity.name,
+          role: identity.role,
+          pid: process.pid,
+          source: ctx.meta["source"] ?? "cli"
+        });
+      } catch {
+      }
+      try {
+        await mb.heartbeat({ agentId: callerId });
+      } catch {
+      }
+      switch (action) {
+        case "check":
+          return executeCheck(mb, callerId, callerSessionId, [baseCallerId], identity.role, i);
+        case "send":
+          return executeSend(mb, identity, callerSessionId, i, ctx);
+        case "ack":
+          return executeAck(mb, callerId, i);
+        case "query":
+          return executeQuery(mb, callerId, callerSessionId, identity.role, i);
+        case "status":
+          return executeStatus(mb);
+        case "online":
+          return executeOnline(mb);
+        case "unread":
+          return executeUnread(mb, callerId, callerSessionId, [baseCallerId], identity.role);
+        default:
+          return { ok: false, error: `Unknown action: "${action}". Use check, send, ack, query, status, online, or unread.` };
+      }
+    }
+  };
+}
+async function executeCheck(mb, agentId, sessionId, aliases, role, i) {
+  const limit = i.limit ?? 20;
+  const markRead = i.markRead ?? true;
+  const completed = i.completed ?? false;
+  const outcome = i.outcome;
+  const targets = [
+    agentId,
+    ...aliases.filter((al) => al && al !== agentId),
+    `@session:${sessionId}`
+  ];
+  const batches = await Promise.all(
+    targets.map(
+      (to) => mb.query({ to, unreadBy: agentId, readerRole: role, limit, minPriority: "low" }).catch(() => [])
+    )
+  );
+  const seen = /* @__PURE__ */ new Set();
+  const candidates = batches.flat().filter((m) => {
+    if (seen.has(m.id)) return false;
+    if (!isMailboxMessageVisibleTo(m, agentId, role)) return false;
+    seen.add(m.id);
+    return true;
+  });
+  const messages = [];
+  for (const m of candidates) {
+    if (await acceptMailboxMessageForSession(m, sessionId)) {
+      messages.push(m);
+    }
+  }
+  const acked = markRead || completed ? await mb.ackMany({
+    acks: messages.map((m) => ({
+      messageId: m.id,
+      readerId: agentId,
+      read: markRead,
+      completed,
+      outcome: completed ? outcome : void 0
+    }))
+  }).catch(() => messages) : messages;
+  return {
+    ok: true,
+    count: acked.length,
+    messages: acked.map((m) => formatMessage(m, agentId)),
+    summary: acked.length === 0 ? "No unread messages." : `${acked.length} unread message(s)${markRead ? " (marked read)" : ""}${completed ? " (completed)" : ""}.`
+  };
+}
+async function executeSend(mb, identity, sessionId, i, ctx) {
+  const to = i.to;
+  const tp = i.type;
+  const subject = i.subject;
+  const body = i.body;
+  const audience = i.audience;
+  if (!to) return { ok: false, error: '"to" is required.' };
+  if (!tp) return { ok: false, error: '"type" is required.' };
+  if (!subject) return { ok: false, error: '"subject" is required.' };
+  if (body === void 0 || body === null) return { ok: false, error: '"body" is required.' };
+  if (audience !== void 0 && audience !== "all" && audience !== "leaders") {
+    return { ok: false, error: '"audience" must be "all" or "leaders".' };
+  }
+  let normalizedTo;
+  try {
+    normalizedTo = normalizeRecipient(to, sessionId);
+  } catch (err) {
+    return { ok: false, error: `"to" is invalid: ${toErrorMessage(err)}` };
+  }
+  const delivery = applyMailboxSendPolicy(ctx, identity, normalizedTo, audience);
+  const typeResult = resolveSendTypeSafe(tp, delivery.to);
+  if (!typeResult.ok) return { ok: false, error: `"type" is invalid: ${typeResult.error}` };
+  const msg = await mb.send({
+    from: identity.callerId,
+    to: delivery.to,
+    type: typeResult.type,
+    subject,
+    body,
+    audience: delivery.audience,
+    priority: i.priority ?? "normal",
+    replyTo: i.replyTo,
+    senderSessionId: sessionId
+  });
+  return {
+    ok: true,
+    messageId: msg.id,
+    to: msg.to,
+    type: msg.type,
+    timestamp: msg.timestamp,
+    summary: `Message sent to ${msg.to === "*" ? "all agents" : msg.to}. Id: ${msg.id}`
+  };
+}
+async function executeAck(mb, agentId, i) {
+  const messageId = i.messageId;
+  if (!messageId) return { ok: false, error: '"messageId" is required.' };
+  const updated = await mb.ack({
+    messageId,
+    readerId: agentId,
+    read: i.read,
+    completed: i.completed,
+    outcome: i.outcome
+  });
+  if (!updated) return { ok: false, error: `Message "${messageId}" not found.` };
+  return {
+    ok: true,
+    messageId: updated.id,
+    readBy: Object.keys(updated.readBy),
+    readByCount: Object.keys(updated.readBy).length,
+    completed: updated.completed,
+    completedBy: updated.completedBy,
+    outcome: updated.outcome,
+    summary: `Message ${messageId} acknowledged. Read by ${Object.keys(updated.readBy).length} agent(s), Completed: ${updated.completed}.`
+  };
+}
+async function executeQuery(mb, agentId, sessionId, role, i) {
+  const limit = i.limit ?? 50;
+  const messages = await mb.query({
+    to: i.to,
+    from: i.from,
+    unreadBy: i.unreadBy,
+    incompleteOnly: i.incompleteOnly,
+    type: i.type,
+    minPriority: i.minPriority,
+    since: i.since,
+    sessionId: i.sessionId,
+    limit
+  });
+  const visible = [];
+  for (const message of messages) {
+    if (isMailboxMessageVisibleTo(message, agentId, role) && await acceptMailboxMessageForSession(message, sessionId)) {
+      visible.push(message);
+    }
+  }
+  return { ok: true, count: visible.length, messages: visible, summary: `${visible.length} message(s).` };
+}
+async function executeStatus(mb) {
+  const agents = await mb.getAgentStatuses();
+  return {
+    ok: true,
+    count: agents.length,
+    agents: agents.map((a) => ({
+      agentId: a.agentId,
+      name: a.name,
+      role: a.role,
+      sessionId: a.sessionId,
+      status: a.status,
+      currentTool: a.currentTool,
+      currentTask: a.currentTask,
+      iterations: a.iterations,
+      toolCalls: a.toolCalls,
+      lastSeenAt: a.lastSeenAt,
+      online: a.online,
+      pid: a.pid,
+      source: a.source
+    })),
+    summary: `${agents.filter((a) => a.online).length} online, ${agents.length} total.`
+  };
+}
+async function executeOnline(mb) {
+  const agents = await mb.getOnlineAgents();
+  return {
+    ok: true,
+    count: agents.length,
+    agents: agents.map((a) => ({
+      agentId: a.agentId,
+      name: a.name,
+      role: a.role,
+      sessionId: a.sessionId,
+      status: a.status,
+      currentTool: a.currentTool,
+      currentTask: a.currentTask,
+      lastSeenAt: a.lastSeenAt,
+      source: a.source
+    })),
+    summary: `${agents.length} online agent(s).`
+  };
+}
+async function executeUnread(mb, agentId, sessionId, aliases = [], role) {
+  const targets = [
+    agentId,
+    ...aliases.filter((al) => al && al !== agentId),
+    `@session:${sessionId}`
+  ];
+  const batches = await Promise.all(
+    targets.map((to) => mb.query({ to, unreadBy: agentId, readerRole: role, limit: 200 }).catch(() => []))
+  );
+  const ids = /* @__PURE__ */ new Set();
+  for (const m of batches.flat()) {
+    if (!isMailboxMessageVisibleTo(m, agentId, role)) continue;
+    if (await acceptMailboxMessageForSession(m, sessionId)) ids.add(m.id);
+  }
+  return { ok: true, count: ids.size, summary: `${ids.size} unread message(s) for you.` };
+}
+function formatMessage(m, readerId) {
+  const maxBody = 2e3;
+  const truncated = m.body.length > maxBody ? `${m.body.slice(0, maxBody)}\u2026 [truncated]` : m.body;
+  return {
+    id: m.id,
+    from: m.from,
+    to: m.to,
+    type: m.type,
+    audience: m.audience ?? "all",
+    subject: m.subject,
+    body: truncated,
+    priority: m.priority,
+    readByMe: readerId in m.readBy,
+    readByCount: Object.keys(m.readBy).length,
+    readBy: m.readBy,
+    completed: m.completed,
+    completedBy: m.completedBy,
+    outcome: m.outcome,
+    timestamp: m.timestamp,
+    replyTo: m.replyTo,
+    senderSessionId: m.senderSessionId
+  };
+}
+
+export {
+  isMailboxProjectServerAvailable,
+  MailboxProjectServerConnection,
+  RemoteMailbox,
+  createProjectMailbox,
+  getSharedProjectMailbox,
+  defaultResolveProjectDir,
+  mailboxSessionTag,
+  resolveMailboxIdentity,
+  applyMailboxSendPolicy,
+  makeMailboxTool
+};
+//# sourceMappingURL=chunk-RD6DEE36.js.map