agent-inbox 0.0.1 → 0.1.2

package/src/push/notifier.ts

@@ -0,0 +1,192 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { EventEmitter } from "node:events";
+import type { Message } from "../types.js";
+import type { Storage } from "../storage/interface.js";
+
+/**
+ * Push notification system for Agent Inbox.
+ *
+ * Agents can't receive server-initiated messages via MCP stdio transport,
+ * so we use the same injection pattern as claude-code-swarm:
+ *
+ * 1. New messages arrive → written to per-agent inbox files (NDJSON)
+ * 2. Agent's hook (UserPromptSubmit) reads the inbox file and injects
+ *    messages into the agent's context as formatted markdown
+ * 3. Agent sees new messages at the start of their next turn
+ *
+ * This class also supports webhook-style push for external consumers.
+ */
+
+export interface NotifierConfig {
+  /** Directory for per-agent inbox files */
+  inboxDir: string;
+  /** Optional webhook URLs to POST new messages to */
+  webhooks?: string[];
+}
+
+export interface InboxFileEntry {
+  messageId: string;
+  from: string;
+  to: string;
+  subject?: string;
+  content: unknown;
+  threadTag?: string;
+  importance: string;
+  timestamp: string;
+}
+
+export class PushNotifier {
+  private webhooks: string[];
+
+  constructor(
+    private config: NotifierConfig,
+    private storage: Storage,
+    events: EventEmitter
+  ) {
+    this.webhooks = config.webhooks ?? [];
+
+    // Subscribe to message.created events
+    events.on("message.created", (msg: Message) => this.onMessage(msg));
+
+    // Ensure inbox directory exists
+    fs.mkdirSync(config.inboxDir, { recursive: true });
+  }
+
+  private onMessage(message: Message): void {
+    // Write to each recipient's per-agent inbox file
+    for (const recipient of message.recipients) {
+      this.writeAgentInbox(recipient.agent_id, message);
+    }
+
+    // Fire webhooks (best-effort)
+    for (const url of this.webhooks) {
+      this.fireWebhook(url, message).catch(() => {});
+    }
+  }
+
+  /** Write a message to an agent's inbox file (NDJSON) */
+  private writeAgentInbox(agentId: string, message: Message): void {
+    const filePath = this.agentInboxPath(agentId);
+    const entry: InboxFileEntry = {
+      messageId: message.id,
+      from: message.sender_id,
+      to: agentId,
+      subject: message.subject,
+      content: message.content,
+      threadTag: message.thread_tag,
+      importance: message.importance,
+      timestamp: message.created_at,
+    };
+    try {
+      fs.appendFileSync(filePath, JSON.stringify(entry) + "\n");
+    } catch {
+      // Best-effort write
+    }
+  }
+
+  /** Read and format an agent's pending inbox as markdown (for hook injection) */
+  readAndClearAgentInbox(agentId: string): string | null {
+    const filePath = this.agentInboxPath(agentId);
+    let raw: string;
+    try {
+      raw = fs.readFileSync(filePath, "utf-8").trim();
+    } catch {
+      return null;
+    }
+
+    if (!raw) return null;
+
+    // Parse entries
+    const entries: InboxFileEntry[] = [];
+    for (const line of raw.split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        entries.push(JSON.parse(line) as InboxFileEntry);
+      } catch {
+        // Skip malformed lines
+      }
+    }
+
+    if (entries.length === 0) return null;
+
+    // Clear the file
+    try {
+      fs.writeFileSync(filePath, "");
+    } catch {
+      // Best-effort clear
+    }
+
+    return formatInboxMarkdown(entries);
+  }
+
+  /** Get the path to an agent's inbox file */
+  agentInboxPath(agentId: string): string {
+    // Sanitize agentId for use as filename
+    const safe = agentId.replace(/[^a-zA-Z0-9_-]/g, "_");
+    return path.join(this.config.inboxDir, `${safe}.inbox.jsonl`);
+  }
+
+  /** Fire webhook notification (best-effort) */
+  private async fireWebhook(url: string, message: Message): Promise<void> {
+    try {
+      await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          event: "message.created",
+          message: {
+            id: message.id,
+            from: message.sender_id,
+            recipients: message.recipients.map((r) => r.agent_id),
+            content: message.content,
+            threadTag: message.thread_tag,
+            importance: message.importance,
+            createdAt: message.created_at,
+          },
+        }),
+        signal: AbortSignal.timeout(5000),
+      });
+    } catch {
+      // Best-effort
+    }
+  }
+}
+
+/** Format inbox entries as markdown for agent context injection */
+export function formatInboxMarkdown(entries: InboxFileEntry[]): string {
+  const lines: string[] = [];
+  lines.push(`## [Inbox] ${entries.length} new message(s)\n`);
+
+  for (const entry of entries) {
+    const age = formatAge(entry.timestamp);
+    const priority =
+      entry.importance !== "normal" ? ` [${entry.importance}]` : "";
+    const subject = entry.subject ? ` — ${entry.subject}` : "";
+    const thread = entry.threadTag ? ` (thread: ${entry.threadTag})` : "";
+
+    lines.push(`**From ${entry.from}** (${age} ago)${priority}${subject}${thread}`);
+
+    // Format content
+    const content = entry.content as Record<string, unknown>;
+    if (content && typeof content === "object" && content.type === "text") {
+      lines.push(`> ${(content as { text: string }).text}`);
+    } else if (typeof entry.content === "string") {
+      lines.push(`> ${entry.content}`);
+    } else {
+      lines.push(`> \`${JSON.stringify(content)}\``);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+function formatAge(timestamp: string): string {
+  const diff = Date.now() - new Date(timestamp).getTime();
+  if (diff < 1000) return "<1s";
+  if (diff < 60_000) return `${Math.floor(diff / 1000)}s`;
+  if (diff < 3600_000) return `${Math.floor(diff / 60_000)}m`;
+  if (diff < 86400_000) return `${Math.floor(diff / 3600_000)}h`;
+  return `${Math.floor(diff / 86400_000)}d`;
+}

package/src/registry/warm-registry.ts

@@ -0,0 +1,210 @@
+import { EventEmitter } from "node:events";
+import type {
+  Agent,
+  AgentRegistryConfig,
+  WarmAgentStatus,
+} from "../types.js";
+import type { Storage } from "../storage/interface.js";
+
+const DEFAULT_CONFIG: AgentRegistryConfig = {
+  gracePeriodMs: 60_000,
+  retainExpiredMs: 3_600_000,
+  requeueOnReconnect: true,
+};
+
+interface RegistryEntry {
+  agentId: string;
+  warmStatus: WarmAgentStatus;
+  graceTimer?: ReturnType<typeof setTimeout>;
+  expireTimer?: ReturnType<typeof setTimeout>;
+  disconnectedAt?: string;
+}
+
+/**
+ * Warm agent registry with active/away/expired lifecycle.
+ *
+ * Wraps the storage layer to add TTL-based status management.
+ * Agents transition: active → away (on disconnect) → expired (after grace period).
+ */
+export class WarmRegistry {
+  private entries = new Map<string, RegistryEntry>();
+  private config: AgentRegistryConfig;
+
+  constructor(
+    private storage: Storage,
+    private events: EventEmitter,
+    config?: Partial<AgentRegistryConfig>
+  ) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * Register an agent. First-wins — rejects if ID is taken by an active/away agent.
+   * Returns true if registered, false if ID conflict.
+   */
+  register(agent: Agent): boolean {
+    const existing = this.entries.get(agent.agent_id);
+    if (existing && (existing.warmStatus === "active" || existing.warmStatus === "away")) {
+      return false; // ID conflict
+    }
+
+    // Clear any existing timers
+    if (existing) {
+      this.clearTimers(existing);
+    }
+
+    this.entries.set(agent.agent_id, {
+      agentId: agent.agent_id,
+      warmStatus: "active",
+    });
+
+    agent.status = "active";
+    this.storage.putAgent(agent);
+    this.events.emit("registry.registered", agent.agent_id);
+    return true;
+  }
+
+  /**
+   * Mark an agent as disconnected. Starts grace period timer.
+   */
+  disconnect(agentId: string): boolean {
+    const entry = this.entries.get(agentId);
+    if (!entry || entry.warmStatus !== "active") return false;
+
+    entry.warmStatus = "away";
+    entry.disconnectedAt = new Date().toISOString();
+
+    // Start grace period timer
+    entry.graceTimer = setTimeout(() => {
+      this.expire(agentId);
+    }, this.config.gracePeriodMs);
+
+    // Update storage
+    const agent = this.storage.getAgent(agentId);
+    if (agent) {
+      agent.status = "idle"; // Map "away" to "idle" in the existing AgentStatus type
+      this.storage.putAgent(agent);
+    }
+
+    this.events.emit("registry.disconnected", agentId);
+    return true;
+  }
+
+  /**
+   * Reconnect a previously disconnected agent.
+   * Cancels grace period and restores active status.
+   */
+  reconnect(agentId: string): boolean {
+    const entry = this.entries.get(agentId);
+    if (!entry) return false;
+    if (entry.warmStatus !== "away") return false;
+
+    this.clearTimers(entry);
+    entry.warmStatus = "active";
+    entry.disconnectedAt = undefined;
+
+    const agent = this.storage.getAgent(agentId);
+    if (agent) {
+      agent.status = "active";
+      agent.last_active_at = new Date().toISOString();
+      this.storage.putAgent(agent);
+    }
+
+    this.events.emit("registry.reconnected", agentId);
+    return true;
+  }
+
+  /**
+   * Transition agent to expired. Not routable, but retained for audit.
+   */
+  expire(agentId: string): void {
+    const entry = this.entries.get(agentId);
+    if (!entry) return;
+
+    this.clearTimers(entry);
+    entry.warmStatus = "expired";
+
+    const agent = this.storage.getAgent(agentId);
+    if (agent) {
+      agent.status = "offline";
+      this.storage.putAgent(agent);
+    }
+
+    // Schedule cleanup after retainExpiredMs
+    entry.expireTimer = setTimeout(() => {
+      this.remove(agentId);
+    }, this.config.retainExpiredMs);
+
+    this.events.emit("registry.expired", agentId);
+  }
+
+  /**
+   * Fully remove an agent from the registry.
+   */
+  remove(agentId: string): void {
+    const entry = this.entries.get(agentId);
+    if (entry) {
+      this.clearTimers(entry);
+      this.entries.delete(agentId);
+    }
+    this.storage.removeAgent(agentId);
+    this.events.emit("registry.removed", agentId);
+  }
+
+  /**
+   * Check if an agent is routable (active or away).
+   */
+  isRoutable(agentId: string): boolean {
+    const entry = this.entries.get(agentId);
+    if (!entry) return false;
+    return entry.warmStatus === "active" || entry.warmStatus === "away";
+  }
+
+  /**
+   * Get the warm status of an agent.
+   */
+  getStatus(agentId: string): WarmAgentStatus | "unknown" {
+    const entry = this.entries.get(agentId);
+    return entry?.warmStatus ?? "unknown";
+  }
+
+  /**
+   * List all entries with their warm status.
+   */
+  listEntries(): Array<{ agentId: string; warmStatus: WarmAgentStatus }> {
+    return Array.from(this.entries.values()).map((e) => ({
+      agentId: e.agentId,
+      warmStatus: e.warmStatus,
+    }));
+  }
+
+  /**
+   * List all routable agent IDs.
+   */
+  listRoutable(): string[] {
+    return Array.from(this.entries.values())
+      .filter((e) => e.warmStatus === "active" || e.warmStatus === "away")
+      .map((e) => e.agentId);
+  }
+
+  /**
+   * Clean up all timers. Call on shutdown.
+   */
+  destroy(): void {
+    for (const entry of this.entries.values()) {
+      this.clearTimers(entry);
+    }
+    this.entries.clear();
+  }
+
+  private clearTimers(entry: RegistryEntry): void {
+    if (entry.graceTimer) {
+      clearTimeout(entry.graceTimer);
+      entry.graceTimer = undefined;
+    }
+    if (entry.expireTimer) {
+      clearTimeout(entry.expireTimer);
+      entry.expireTimer = undefined;
+    }
+  }
+}

package/src/router/message-router.ts

@@ -0,0 +1,175 @@
+import { EventEmitter } from "node:events";
+import { ulid } from "ulid";
+import type {
+  Message,
+  MessageContent,
+  Recipient,
+  RecipientKind,
+  Importance,
+} from "../types.js";
+import type { Storage } from "../storage/interface.js";
+import type { ConnectionManager } from "../federation/connection-manager.js";
+import { parseAddress, isRemoteAddress } from "../federation/address.js";
+
+export interface SendOptions {
+  from: string;
+  to: string | string[] | { agent_id: string; kind?: RecipientKind }[];
+  payload: unknown;
+  scope?: string;
+  threadTag?: string;
+  inReplyTo?: string;
+  importance?: Importance;
+  conversationId?: string;
+  subject?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export class MessageRouter {
+  private federation: ConnectionManager | null = null;
+
+  constructor(
+    private storage: Storage,
+    private events: EventEmitter,
+    private defaultScope: string = "default"
+  ) {}
+
+  /**
+   * Attach a federation connection manager for cross-system routing.
+   */
+  setFederation(federation: ConnectionManager): void {
+    this.federation = federation;
+  }
+
+  async routeMessage(opts: SendOptions): Promise<Message> {
+    const recipients = this.resolveRecipients(opts.to);
+    const content = normalizeContent(opts.payload);
+    const scope = opts.scope ?? this.defaultScope;
+    const now = new Date().toISOString();
+
+    // If replying, inherit thread_tag and scope from the parent message
+    let threadTag = opts.threadTag;
+    let conversationId = opts.conversationId;
+    if (opts.inReplyTo) {
+      const parent = this.storage.getMessage(opts.inReplyTo);
+      if (parent) {
+        threadTag = threadTag ?? parent.thread_tag;
+        conversationId = conversationId ?? parent.conversation_id;
+      }
+    }
+
+    const message: Message = {
+      id: ulid(),
+      scope,
+      sender_id: opts.from,
+      recipients,
+      subject: opts.subject,
+      content,
+      thread_tag: threadTag,
+      in_reply_to: opts.inReplyTo,
+      conversation_id: conversationId,
+      importance: opts.importance ?? "normal",
+      metadata: opts.metadata ?? {},
+      created_at: now,
+    };
+
+    // Mark local recipients as delivered; route remote ones via federation
+    for (const r of message.recipients) {
+      const addr = parseAddress(r.agent_id);
+      if (!isRemoteAddress(addr) && this.isLocal(r.agent_id)) {
+        r.delivered_at = now;
+      }
+    }
+
+    this.storage.putMessage(message);
+
+    // Update sender's last_active_at
+    const sender = this.storage.getAgent(opts.from);
+    if (sender) {
+      sender.last_active_at = now;
+      this.storage.putAgent(sender);
+    }
+
+    this.events.emit("message.created", message);
+
+    // Route remote recipients via federation
+    if (this.federation) {
+      const hasRemote = message.recipients.some((r) =>
+        isRemoteAddress(parseAddress(r.agent_id))
+      );
+      if (hasRemote) {
+        // Fire-and-forget federation routing (results tracked via events)
+        this.federation.route(message).catch(() => {
+          // Federation routing failures are handled by the delivery queue
+        });
+      }
+    }
+
+    return message;
+  }
+
+  markRead(messageId: string, agentId: string): boolean {
+    const msg = this.storage.getMessage(messageId);
+    if (!msg) return false;
+    const recipient = msg.recipients.find((r) => r.agent_id === agentId);
+    if (!recipient) return false;
+    recipient.read_at = new Date().toISOString();
+    this.storage.putMessage(msg);
+    return true;
+  }
+
+  markAcknowledged(messageId: string, agentId: string): boolean {
+    const msg = this.storage.getMessage(messageId);
+    if (!msg) return false;
+    const recipient = msg.recipients.find((r) => r.agent_id === agentId);
+    if (!recipient) return false;
+    recipient.ack_at = new Date().toISOString();
+    this.storage.putMessage(msg);
+    return true;
+  }
+
+  resolveRecipients(
+    to: string | string[] | { agent_id: string; kind?: RecipientKind }[]
+  ): Recipient[] {
+    if (typeof to === "string") {
+      return [{ agent_id: to, kind: "to" }];
+    }
+    if (Array.isArray(to)) {
+      return to.map((item) => {
+        if (typeof item === "string") {
+          return { agent_id: item, kind: "to" as RecipientKind };
+        }
+        return { agent_id: item.agent_id, kind: item.kind ?? "to" };
+      });
+    }
+    return [{ agent_id: String(to), kind: "to" }];
+  }
+
+  isLocal(agentId: string): boolean {
+    // Remote addresses are never local
+    const addr = parseAddress(agentId);
+    if (isRemoteAddress(addr)) return false;
+    return this.storage.getAgent(agentId) !== undefined;
+  }
+
+  /**
+   * Get the federation connection manager (if attached).
+   */
+  getFederation(): ConnectionManager | null {
+    return this.federation;
+  }
+}
+
+export function normalizeContent(payload: unknown): MessageContent {
+  if (typeof payload === "string") {
+    return { type: "text", text: payload };
+  }
+  if (
+    payload !== null &&
+    typeof payload === "object" &&
+    "type" in payload &&
+    typeof (payload as Record<string, unknown>).type === "string"
+  ) {
+    return payload as MessageContent;
+  }
+  return { type: "data", data: payload };
+}

package/src/storage/interface.ts

@@ -0,0 +1,48 @@
+import type {
+  Agent,
+  Message,
+  Conversation,
+  Turn,
+  Thread,
+} from "../types.js";
+
+export interface InboxQuery {
+  unreadOnly?: boolean;
+  limit?: number;
+  since?: string;
+}
+
+export interface ThreadQuery {
+  threadTag: string;
+  scope: string;
+}
+
+export interface Storage {
+  // Agents
+  getAgent(agentId: string): Agent | undefined;
+  putAgent(agent: Agent): void;
+  listAgents(scope?: string): Agent[];
+  removeAgent(agentId: string): boolean;
+
+  // Messages
+  getMessage(id: string): Message | undefined;
+  putMessage(message: Message): Message;
+  getInbox(agentId: string, opts?: InboxQuery): Message[];
+  getThread(query: ThreadQuery): Message[];
+  getSentMessages(agentId: string, limit?: number): Message[];
+  searchMessages(query: string, scope?: string): Message[];
+
+  // Conversations
+  getConversation(id: string): Conversation | undefined;
+  putConversation(conversation: Conversation): Conversation;
+  listConversations(scope?: string): Conversation[];
+
+  // Turns
+  addTurn(turn: Turn): void;
+  getTurns(conversationId: string): Turn[];
+
+  // Threads
+  getThread2(id: string): Thread | undefined;
+  putThread(thread: Thread): Thread;
+  getThreadsByConversation(conversationId: string): Thread[];
+}