agent-inbox 0.0.1 → 0.1.1

package/src/federation/routing-engine.ts

@@ -0,0 +1,188 @@
+import { EventEmitter } from "node:events";
+import type {
+  FederatedAddress,
+  FederationRoutingConfig,
+  RoutingEntry,
+  WarmAgentStatus,
+} from "../types.js";
+
+const DEFAULT_CONFIG: FederationRoutingConfig = {
+  strategy: "table",
+  tableTTL: 300_000, // 5 minutes
+  refreshOnMiss: true,
+  broadcastTimeout: 5_000,
+};
+
+/**
+ * Federation routing engine with configurable strategies.
+ *
+ * - table: In-memory routing table populated from federation exposure data
+ * - broadcast: Forward to all peers, first responder wins
+ * - hierarchical: Local table first, then delegate to upstream hubs
+ */
+export class RoutingEngine {
+  private table = new Map<string, RoutingEntry>();
+  private config: FederationRoutingConfig;
+
+  constructor(
+    private events: EventEmitter,
+    config?: Partial<FederationRoutingConfig>
+  ) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * Resolve a federated address to a peer system ID.
+   * Returns null if no route found.
+   */
+  resolveRoute(addr: FederatedAddress): string | null {
+    // If the address specifies a system directly, use it
+    if (addr.system) {
+      return addr.system;
+    }
+
+    // Otherwise, look up the agent in the routing table
+    if (addr.agent) {
+      return this.lookupAgent(addr.agent);
+    }
+
+    return null;
+  }
+
+  /**
+   * Look up an agent in the routing table.
+   * Respects TTL — expired entries are not returned.
+   */
+  lookupAgent(agentId: string): string | null {
+    const entry = this.table.get(agentId);
+    if (!entry) return null;
+
+    // Check TTL
+    const age = Date.now() - new Date(entry.lastSeen).getTime();
+    if (age > (this.config.tableTTL ?? DEFAULT_CONFIG.tableTTL!)) {
+      this.table.delete(agentId);
+      return null;
+    }
+
+    // Only route to active or away agents
+    if (entry.status === "expired") return null;
+
+    return entry.peerId;
+  }
+
+  /**
+   * Update the routing table with exposure data from a peer.
+   * Called when federation/connect completes or peer sends updates.
+   */
+  updateFromExposure(
+    peerId: string,
+    agents: Array<{ agentId: string; status?: WarmAgentStatus }>
+  ): void {
+    const now = new Date().toISOString();
+    for (const agent of agents) {
+      this.table.set(agent.agentId, {
+        agentId: agent.agentId,
+        peerId,
+        lastSeen: now,
+        status: agent.status ?? "active",
+      });
+    }
+    this.events.emit("routing.updated", { peerId, agentCount: agents.length });
+  }
+
+  /**
+   * Update status for a specific agent in the routing table.
+   */
+  updateAgentStatus(agentId: string, status: WarmAgentStatus): void {
+    const entry = this.table.get(agentId);
+    if (entry) {
+      entry.status = status;
+      entry.lastSeen = new Date().toISOString();
+    }
+  }
+
+  /**
+   * Remove all routing entries for a peer (e.g., on disconnect).
+   */
+  removePeer(peerId: string): number {
+    let removed = 0;
+    for (const [agentId, entry] of this.table.entries()) {
+      if (entry.peerId === peerId) {
+        this.table.delete(agentId);
+        removed++;
+      }
+    }
+    return removed;
+  }
+
+  /**
+   * Get all known peers from the routing table.
+   */
+  knownPeers(): string[] {
+    const peers = new Set<string>();
+    for (const entry of this.table.values()) {
+      peers.add(entry.peerId);
+    }
+    return Array.from(peers);
+  }
+
+  /**
+   * Get all routing entries (for debugging/inspection).
+   */
+  getTable(): RoutingEntry[] {
+    return Array.from(this.table.values());
+  }
+
+  /**
+   * Get the routing strategy in use.
+   */
+  getStrategy(): FederationRoutingConfig["strategy"] {
+    return this.config.strategy;
+  }
+
+  /**
+   * Get configured upstream hubs (for hierarchical strategy).
+   */
+  getUpstream(): string[] {
+    return this.config.upstream ?? [];
+  }
+
+  /**
+   * Whether to query peers on cache miss (for table strategy).
+   */
+  shouldRefreshOnMiss(): boolean {
+    return this.config.refreshOnMiss ?? true;
+  }
+
+  /**
+   * Get broadcast timeout (for broadcast strategy).
+   */
+  getBroadcastTimeout(): number {
+    return this.config.broadcastTimeout ?? 5_000;
+  }
+
+  /**
+   * Clean expired entries from the routing table.
+   */
+  cleanup(): number {
+    const ttl = this.config.tableTTL ?? DEFAULT_CONFIG.tableTTL!;
+    const now = Date.now();
+    let removed = 0;
+
+    for (const [agentId, entry] of this.table.entries()) {
+      const age = now - new Date(entry.lastSeen).getTime();
+      if (age > ttl) {
+        this.table.delete(agentId);
+        removed++;
+      }
+    }
+    return removed;
+  }
+
+  /**
+   * Clear all state.
+   */
+  destroy(): void {
+    this.table.clear();
+  }
+}

package/src/federation/trust.ts

@@ -0,0 +1,71 @@
+import type { FederationTrustPolicy } from "../types.js";
+
+const DEFAULT_POLICY: FederationTrustPolicy = {
+  allowedServers: [],
+  scopePermissions: {},
+  requireAuth: false,
+};
+
+/**
+ * Federation trust enforcement.
+ *
+ * Layer 1 (implemented): Server allow-list
+ * Layer 2 (stub): Scope-based permissions
+ * Layer 3 (stub): Token-based auth
+ */
+export class TrustManager {
+  private policy: FederationTrustPolicy;
+
+  constructor(policy?: Partial<FederationTrustPolicy>) {
+    this.policy = { ...DEFAULT_POLICY, ...policy };
+  }
+
+  /**
+   * Check if a system is allowed to connect (Layer 1).
+   * If allowedServers is empty, all servers are allowed (open federation).
+   */
+  canConnect(systemId: string): boolean {
+    if (this.policy.allowedServers.length === 0) return true;
+    return this.policy.allowedServers.includes(systemId);
+  }
+
+  /**
+   * Check if routing from a remote system to a local scope is allowed (Layer 2 — stub).
+   * Currently always returns true.
+   */
+  canRoute(fromSystem: string, toScope: string): boolean {
+    // Stub: check scope permissions when implemented
+    const allowed = this.policy.scopePermissions[toScope];
+    if (!allowed) return true; // No restrictions defined = allow all
+    return allowed.includes(fromSystem);
+  }
+
+  /**
+   * Validate authentication credentials for a system (Layer 3 — stub).
+   * Currently always returns true unless requireAuth is explicitly set.
+   */
+  validateAuth(
+    systemId: string,
+    _credentials?: { method?: string; token?: string }
+  ): boolean {
+    if (!this.policy.requireAuth) return true;
+    // Stub: when implemented, validate credentials against authTokens
+    const expectedToken = this.policy.authTokens?.[systemId];
+    if (!expectedToken) return true; // No token configured = allow
+    return _credentials?.token === expectedToken;
+  }
+
+  /**
+   * Update the trust policy at runtime.
+   */
+  updatePolicy(updates: Partial<FederationTrustPolicy>): void {
+    Object.assign(this.policy, updates);
+  }
+
+  /**
+   * Get current policy (for inspection/debugging).
+   */
+  getPolicy(): Readonly<FederationTrustPolicy> {
+    return this.policy;
+  }
+}

package/src/index.ts

@@ -0,0 +1,299 @@
+import { EventEmitter } from "node:events";
+import * as path from "node:path";
+import * as os from "node:os";
+import { InMemoryStorage } from "./storage/memory.js";
+import { SqliteStorage } from "./storage/sqlite.js";
+import { MessageRouter } from "./router/message-router.js";
+import { TraceabilityLayer } from "./traceability/traceability.js";
+import { IpcServer } from "./ipc/ipc-server.js";
+import { MapClient } from "./map/map-client.js";
+import { InboxMcpServer } from "./mcp/mcp-server.js";
+import { MailJsonRpcServer } from "./jsonrpc/mail-server.js";
+import { PushNotifier } from "./push/notifier.js";
+import { ConnectionManager } from "./federation/connection-manager.js";
+import { WarmRegistry } from "./registry/warm-registry.js";
+import type { InboxConfig } from "./types.js";
+import type { Storage } from "./storage/interface.js";
+
+export { InMemoryStorage } from "./storage/memory.js";
+export { SqliteStorage } from "./storage/sqlite.js";
+export { MessageRouter, normalizeContent } from "./router/message-router.js";
+export { TraceabilityLayer } from "./traceability/traceability.js";
+export { IpcServer } from "./ipc/ipc-server.js";
+export { MapClient } from "./map/map-client.js";
+export { InboxMcpServer } from "./mcp/mcp-server.js";
+export { MailJsonRpcServer } from "./jsonrpc/mail-server.js";
+export { PushNotifier, formatInboxMarkdown } from "./push/notifier.js";
+export { ConnectionManager } from "./federation/connection-manager.js";
+export type { DeliveryResult, IncomingMessageHandler } from "./federation/connection-manager.js";
+export type { MapConnection, MapAgentConnectionClass, IncomingMapMessage } from "./map/map-client.js";
+export { WarmRegistry } from "./registry/warm-registry.js";
+export { RoutingEngine } from "./federation/routing-engine.js";
+export { DeliveryQueue } from "./federation/delivery-queue.js";
+export { TrustManager } from "./federation/trust.js";
+export {
+  parseAddress,
+  formatAddress,
+  isRemoteAddress,
+  isBroadcastAddress,
+} from "./federation/address.js";
+export type * from "./types.js";
+export type { Storage, InboxQuery, ThreadQuery } from "./storage/interface.js";
+
+function defaultSocketPath(): string {
+  const home = os.homedir();
+  return path.join(home, ".claude", "agent-inbox", "inbox.sock");
+}
+
+function defaultInboxJsonlPath(): string {
+  const home = os.homedir();
+  return path.join(home, ".claude", "agent-inbox", "inbox.jsonl");
+}
+
+function defaultInboxDir(): string {
+  const home = os.homedir();
+  return path.join(home, ".claude", "agent-inbox", "inboxes");
+}
+
+function defaultSqlitePath(): string {
+  const home = os.homedir();
+  return path.join(home, ".claude", "agent-inbox", "inbox.db");
+}
+
+function loadConfig(): InboxConfig {
+  return {
+    socketPath: process.env.INBOX_SOCKET_PATH ?? defaultSocketPath(),
+    scope: process.env.INBOX_SCOPE ?? "default",
+    map: {
+      enabled: process.env.INBOX_MAP_ENABLED === "true",
+      server: process.env.INBOX_MAP_SERVER,
+      scope: process.env.INBOX_MAP_SCOPE ?? process.env.INBOX_SCOPE ?? "default",
+      systemId: process.env.INBOX_MAP_SYSTEM_ID ?? "agent-inbox",
+    },
+  };
+}
+
+export interface AgentInbox {
+  storage: Storage;
+  router: MessageRouter;
+  traceability: TraceabilityLayer;
+  ipcServer: IpcServer;
+  mapClient: MapClient;
+  jsonRpc: MailJsonRpcServer;
+  notifier: PushNotifier;
+  federation: ConnectionManager | null;
+  registry: WarmRegistry | null;
+  events: EventEmitter;
+  stop(): Promise<void>;
+}
+
+export interface CreateOptions {
+  config?: Partial<InboxConfig>;
+  /** Use SQLite storage at this path (":memory:" for in-memory SQLite) */
+  sqlitePath?: string;
+  /** HTTP port for JSON-RPC endpoint (0 = disabled) */
+  httpPort?: number;
+  /** Webhook URLs for push notifications */
+  webhooks?: string[];
+  /** Enable federation with peer systems */
+  enableFederation?: boolean;
+  /** Use an externally-managed MAP connection instead of creating one.
+   *  When provided, Agent Inbox borrows this connection for messaging
+   *  but does not own its lifecycle (won't disconnect it on stop()). */
+  connection?: import("./map/map-client.js").MapConnection;
+}
+
+export async function createAgentInbox(
+  opts: CreateOptions = {}
+): Promise<AgentInbox> {
+  const config = { ...loadConfig(), ...opts.config };
+
+  // 1. Storage — SQLite if path provided, otherwise in-memory
+  const storage: Storage = opts.sqlitePath
+    ? new SqliteStorage({ path: opts.sqlitePath })
+    : new InMemoryStorage();
+
+  // 2. Event bus (internal)
+  const events = new EventEmitter();
+
+  // 3. Message router
+  const router = new MessageRouter(storage, events, config.scope);
+
+  // 4. Traceability layer (subscribes to message.created events)
+  const traceability = new TraceabilityLayer(storage, events);
+
+  // 5. Push notifier (per-agent inbox files + webhooks)
+  const notifier = new PushNotifier(
+    { inboxDir: defaultInboxDir(), webhooks: opts.webhooks },
+    storage,
+    events
+  );
+
+  // 6. MAP client (connects first to obtain SDK class for federation)
+  const mapClient = new MapClient(
+    storage,
+    router,
+    events,
+    defaultInboxJsonlPath()
+  );
+  if (opts.connection) {
+    // External connection — borrow it, don't manage its lifecycle
+    mapClient.useConnection(opts.connection);
+  } else if (config.map?.enabled) {
+    const connected = await mapClient.connect(config.map);
+    if (connected) {
+      // Replay missed messages from MAP server
+      const replayed = await mapClient.replayMissed();
+      if (replayed > 0) {
+        console.error(`Replayed ${replayed} missed messages from MAP server`);
+      }
+    }
+  }
+
+  // 7. Federation (optional) — inject SDK class from MapClient if available
+  let federation: ConnectionManager | null = null;
+  let registry: WarmRegistry | null = null;
+
+  if (opts.enableFederation || config.federation?.peers?.length) {
+    registry = new WarmRegistry(storage, events, config.federation?.registry);
+
+    const sdkClass = mapClient.getAgentConnectionClass() ?? undefined;
+
+    federation = new ConnectionManager(events, config.federation, {
+      sdkClass,
+      onIncomingMessage: ({ from, peerId, payload, meta }) => {
+        // Delegate incoming federation messages to the router.
+        // The targetAgent in meta tells us which local agent this is for.
+        const targetAgent = (meta?.targetAgent as string) ?? from;
+        router.routeMessage({
+          from: `${from}@${peerId}`,
+          to: targetAgent,
+          payload,
+          scope: meta?.scope as string | undefined,
+          subject: meta?.subject as string | undefined,
+          importance: meta?.importance as "high" | "normal" | undefined,
+          threadTag: meta?.threadTag as string | undefined,
+          inReplyTo: meta?.inReplyTo as string | undefined,
+          metadata: meta,
+        }).catch((err) => {
+          console.error(
+            `Failed to route incoming federation message from ${from}@${peerId}: ${err instanceof Error ? err.message : err}`
+          );
+        });
+      },
+    });
+    router.setFederation(federation);
+
+    // Tier 2 system ID resolution: update from MAP systemInfo if available
+    const mapSystemName = mapClient.getSystemName();
+    if (mapSystemName) {
+      federation.updateSystemIdFromMap(mapSystemName);
+    }
+
+    // Connect to configured federation peers
+    if (config.federation?.peers) {
+      for (const peer of config.federation.peers) {
+        try {
+          await federation.federate(peer);
+          console.error(`Federated with peer: ${peer.systemId} (${peer.url})`);
+        } catch (err) {
+          console.error(
+            `Failed to federate with ${peer.systemId}: ${err instanceof Error ? err.message : err}`
+          );
+        }
+      }
+    }
+
+    // Start delivery queue tick timer
+    federation.queue.startTicking();
+  }
+
+  // 8. JSON-RPC server (mail/* methods)
+  const jsonRpc = new MailJsonRpcServer(storage, router, events);
+  if (opts.httpPort && opts.httpPort > 0) {
+    await jsonRpc.startHttp(opts.httpPort);
+    console.error(`JSON-RPC HTTP server listening on port ${opts.httpPort}`);
+  }
+
+  // 9. IPC server (UNIX socket — handles both NDJSON commands and JSON-RPC inline)
+  const socketPath = config.socketPath ?? defaultSocketPath();
+  const ipcServer = new IpcServer(socketPath, router, storage, jsonRpc);
+  await ipcServer.start();
+
+  const stop = async () => {
+    await ipcServer.stop();
+    await jsonRpc.stopHttp();
+    await mapClient.disconnect();
+    if (federation) await federation.destroy();
+    if (registry) registry.destroy();
+    if ("close" in storage && typeof storage.close === "function") {
+      (storage as SqliteStorage).close();
+    }
+  };
+
+  return {
+    storage,
+    router,
+    traceability,
+    ipcServer,
+    mapClient,
+    jsonRpc,
+    notifier,
+    federation,
+    registry,
+    events,
+    stop,
+  };
+}
+
+// CLI entry point
+const isMainModule =
+  process.argv[1] &&
+  (process.argv[1].endsWith("/index.js") ||
+    process.argv[1].endsWith("/index.ts"));
+
+if (isMainModule) {
+  const mode = process.argv[2] ?? "ipc";
+
+  if (mode === "mcp") {
+    // MCP-only mode (stdio transport for Claude Code integration)
+    const config = loadConfig();
+    const sqlitePath = process.env.INBOX_SQLITE_PATH;
+    const storage: Storage = sqlitePath
+      ? new SqliteStorage({ path: sqlitePath })
+      : new InMemoryStorage();
+    const events = new EventEmitter();
+    const router = new MessageRouter(storage, events, config.scope);
+    const _traceability = new TraceabilityLayer(storage, events);
+    const mcpServer = new InboxMcpServer(router, storage, config.scope);
+    mcpServer.start().catch((err) => {
+      console.error("MCP server failed:", err);
+      process.exit(1);
+    });
+  } else {
+    // IPC server mode (default)
+    const httpPort = process.env.INBOX_HTTP_PORT
+      ? parseInt(process.env.INBOX_HTTP_PORT, 10)
+      : 0;
+    const sqlitePath = process.env.INBOX_SQLITE_PATH;
+
+    createAgentInbox({ httpPort, sqlitePath })
+      .then((inbox) => {
+        console.error(
+          `Agent Inbox IPC server listening on ${process.env.INBOX_SOCKET_PATH ?? defaultSocketPath()}`
+        );
+        process.on("SIGINT", async () => {
+          await inbox.stop();
+          process.exit(0);
+        });
+        process.on("SIGTERM", async () => {
+          await inbox.stop();
+          process.exit(0);
+        });
+      })
+      .catch((err) => {
+        console.error("Failed to start Agent Inbox:", err);
+        process.exit(1);
+      });
+  }
+}