claude-code-swarm 0.3.3 → 0.3.5

package/references/agent-inbox/src/federation/delivery-queue.ts

@@ -0,0 +1,222 @@
+import { EventEmitter } from "node:events";
+import { ulid } from "ulid";
+import type { Message, DeliveryQueueConfig, QueuedMessage } from "../types.js";
+
+const DEFAULT_CONFIG: DeliveryQueueConfig = {
+  persistence: "memory",
+  maxTTL: 86_400_000, // 24h
+  maxQueueSize: 10_000,
+  retryStrategy: "exponential",
+  retryBaseInterval: 1_000,
+  retryMaxAttempts: 0, // unlimited until TTL
+  flushOnReconnect: true,
+  overflow: "drop-oldest",
+};
+
+/**
+ * Delivery queue for messages to offline or unreachable federation peers.
+ *
+ * Supports configurable TTL, overflow policy, and retry strategy.
+ * Currently memory-only; SQLite persistence is a future enhancement.
+ */
+export class DeliveryQueue {
+  private queues = new Map<string, QueuedMessage[]>();
+  private config: DeliveryQueueConfig;
+  private tickTimer?: ReturnType<typeof setInterval>;
+
+  constructor(
+    private events: EventEmitter,
+    config?: Partial<DeliveryQueueConfig>
+  ) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * Enqueue a message for a peer. Returns the queued message ID, or null if rejected.
+   */
+  enqueue(peerId: string, message: Message): string | null {
+    let queue = this.queues.get(peerId);
+    if (!queue) {
+      queue = [];
+      this.queues.set(peerId, queue);
+    }
+
+    // Check queue size limit
+    if (queue.length >= this.config.maxQueueSize) {
+      switch (this.config.overflow) {
+        case "drop-oldest":
+          queue.shift();
+          break;
+        case "drop-newest":
+          return null; // Don't enqueue
+        case "reject-new":
+          return null;
+      }
+    }
+
+    const now = new Date().toISOString();
+    const entry: QueuedMessage = {
+      id: ulid(),
+      peerId,
+      message,
+      enqueuedAt: now,
+      attempts: 0,
+      nextRetry: now, // Ready to send immediately
+    };
+
+    queue.push(entry);
+    this.events.emit("queue.enqueued", { peerId, messageId: entry.id });
+    return entry.id;
+  }
+
+  /**
+   * Flush all queued messages for a peer (on reconnect).
+   * Returns the messages and removes them from the queue.
+   */
+  flush(peerId: string): QueuedMessage[] {
+    const queue = this.queues.get(peerId);
+    if (!queue || queue.length === 0) return [];
+
+    const messages = [...queue];
+    this.queues.delete(peerId);
+    this.events.emit("queue.flushed", { peerId, count: messages.length });
+    return messages;
+  }
+
+  /**
+   * Get messages ready for retry. Does not remove them from the queue.
+   */
+  getRetryable(peerId: string): QueuedMessage[] {
+    const queue = this.queues.get(peerId);
+    if (!queue) return [];
+
+    const now = Date.now();
+    return queue.filter((entry) => {
+      if (!entry.nextRetry) return true;
+      return new Date(entry.nextRetry).getTime() <= now;
+    });
+  }
+
+  /**
+   * Record a retry attempt for a message. Updates attempt count and next retry time.
+   * Returns false if max attempts exceeded (message should be dropped).
+   */
+  recordAttempt(peerId: string, messageId: string): boolean {
+    const queue = this.queues.get(peerId);
+    if (!queue) return false;
+
+    const entry = queue.find((e) => e.id === messageId);
+    if (!entry) return false;
+
+    entry.attempts++;
+    entry.lastAttempt = new Date().toISOString();
+
+    // Check max attempts
+    if (this.config.retryMaxAttempts > 0 && entry.attempts >= this.config.retryMaxAttempts) {
+      this.removeEntry(peerId, messageId);
+      return false;
+    }
+
+    // Calculate next retry
+    const delay =
+      this.config.retryStrategy === "exponential"
+        ? this.config.retryBaseInterval * Math.pow(2, entry.attempts - 1)
+        : this.config.retryBaseInterval;
+    entry.nextRetry = new Date(Date.now() + delay).toISOString();
+    return true;
+  }
+
+  /**
+   * Remove a specific entry (e.g., after successful delivery).
+   */
+  removeEntry(peerId: string, messageId: string): boolean {
+    const queue = this.queues.get(peerId);
+    if (!queue) return false;
+
+    const idx = queue.findIndex((e) => e.id === messageId);
+    if (idx === -1) return false;
+
+    queue.splice(idx, 1);
+    if (queue.length === 0) this.queues.delete(peerId);
+    return true;
+  }
+
+  /**
+   * Process tick: expire old messages past TTL.
+   */
+  tick(): number {
+    const now = Date.now();
+    let expired = 0;
+
+    for (const [peerId, queue] of this.queues.entries()) {
+      const before = queue.length;
+      const remaining = queue.filter((entry) => {
+        const age = now - new Date(entry.enqueuedAt).getTime();
+        return age < this.config.maxTTL;
+      });
+      expired += before - remaining.length;
+
+      if (remaining.length === 0) {
+        this.queues.delete(peerId);
+      } else {
+        this.queues.set(peerId, remaining);
+      }
+    }
+
+    if (expired > 0) {
+      this.events.emit("queue.expired", { count: expired });
+    }
+    return expired;
+  }
+
+  /**
+   * Start periodic tick timer for TTL expiry.
+   */
+  startTicking(intervalMs: number = 60_000): void {
+    this.stopTicking();
+    this.tickTimer = setInterval(() => this.tick(), intervalMs);
+  }
+
+  /**
+   * Stop periodic tick timer.
+   */
+  stopTicking(): void {
+    if (this.tickTimer) {
+      clearInterval(this.tickTimer);
+      this.tickTimer = undefined;
+    }
+  }
+
+  /**
+   * Get queue depth for a peer.
+   */
+  size(peerId: string): number {
+    return this.queues.get(peerId)?.length ?? 0;
+  }
+
+  /**
+   * Get total queue depth across all peers.
+   */
+  totalSize(): number {
+    let total = 0;
+    for (const queue of this.queues.values()) {
+      total += queue.length;
+    }
+    return total;
+  }
+
+  /**
+   * List peers with queued messages.
+   */
+  peers(): string[] {
+    return Array.from(this.queues.keys());
+  }
+
+  /**
+   * Clean up all state. Call on shutdown.
+   */
+  destroy(): void {
+    this.stopTicking();
+    this.queues.clear();
+  }
+}

package/references/agent-inbox/src/federation/index.ts

@@ -0,0 +1,6 @@
+export { parseAddress, formatAddress, isRemoteAddress, isBroadcastAddress } from "./address.js";
+export { ConnectionManager } from "./connection-manager.js";
+export type { DeliveryResult } from "./connection-manager.js";
+export { DeliveryQueue } from "./delivery-queue.js";
+export { RoutingEngine } from "./routing-engine.js";
+export { TrustManager } from "./trust.js";

package/references/agent-inbox/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/references/agent-inbox/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;
+  }
+}