agent-inbox 0.0.1 → 0.1.2

package/src/traceability/traceability.ts

@@ -0,0 +1,183 @@
+import { EventEmitter } from "node:events";
+import { ulid } from "ulid";
+import type { Message, Conversation, Turn, Thread } from "../types.js";
+import type { Storage } from "../storage/interface.js";
+
+/**
+ * Auto-creates Conversations, Turns, and Threads from messaging events.
+ *
+ * Rules:
+ * 1. Message with conversationId → add Turn to that Conversation
+ * 2. Message with thread_tag, no conversationId → find/create Conversation for thread_tag+scope
+ * 3. Message with neither → add Turn to catch-all Conversation for scope
+ * 4. Reply (in_reply_to) → create Thread if not exists, link Turn
+ */
+export class TraceabilityLayer {
+  /** Maps "thread_tag:scope" → conversation ID */
+  private tagToConversation = new Map<string, string>();
+  /** Maps scope → catch-all conversation ID */
+  private scopeCatchAll = new Map<string, string>();
+  /** Maps original message ID → thread ID (for reply chains) */
+  private replyChainToThread = new Map<string, string>();
+
+  constructor(
+    private storage: Storage,
+    events: EventEmitter
+  ) {
+    events.on("message.created", (msg: Message) => this.onMessage(msg));
+  }
+
+  private onMessage(message: Message): void {
+    const conversationId = this.resolveConversation(message);
+
+    // Update message's conversation_id if not already set
+    if (!message.conversation_id) {
+      message.conversation_id = conversationId;
+      this.storage.putMessage(message);
+    }
+
+    // Ensure sender is a participant
+    this.ensureParticipant(conversationId, message.sender_id);
+
+    // Ensure recipients are participants
+    for (const r of message.recipients) {
+      this.ensureParticipant(conversationId, r.agent_id);
+    }
+
+    // Create Turn
+    const turn: Turn = {
+      id: `turn-${ulid()}`,
+      conversation_id: conversationId,
+      participant_id: message.sender_id,
+      source_message_id: message.id,
+      content_type: message.content.type,
+      content: message.content,
+      created_at: message.created_at,
+    };
+
+    // Handle reply threading
+    if (message.in_reply_to) {
+      const threadId = this.resolveThread(message, conversationId, turn.id);
+      turn.thread_id = threadId;
+      turn.in_reply_to = this.findTurnForMessage(message.in_reply_to);
+    }
+
+    this.storage.addTurn(turn);
+
+    // Update conversation updated_at
+    const conv = this.storage.getConversation(conversationId);
+    if (conv) {
+      conv.updated_at = message.created_at;
+      this.storage.putConversation(conv);
+    }
+  }
+
+  private resolveConversation(message: Message): string {
+    // 1. Explicit conversation ID
+    if (message.conversation_id) {
+      const existing = this.storage.getConversation(message.conversation_id);
+      if (existing) return existing.id;
+      // Create it if it doesn't exist
+      return this.createConversation(
+        message.scope,
+        message.subject,
+        message.conversation_id
+      );
+    }
+
+    // 2. thread_tag → conversation
+    if (message.thread_tag) {
+      const key = `${message.thread_tag}:${message.scope}`;
+      const existing = this.tagToConversation.get(key);
+      if (existing) return existing;
+
+      const convId = this.createConversation(
+        message.scope,
+        message.thread_tag
+      );
+      this.tagToConversation.set(key, convId);
+      return convId;
+    }
+
+    // 3. Catch-all for scope
+    const existing = this.scopeCatchAll.get(message.scope);
+    if (existing) return existing;
+
+    const convId = this.createConversation(message.scope, "General");
+    this.scopeCatchAll.set(message.scope, convId);
+    return convId;
+  }
+
+  private createConversation(
+    scope: string,
+    subject?: string,
+    explicitId?: string
+  ): string {
+    const now = new Date().toISOString();
+    const conv: Conversation = {
+      id: explicitId ?? `conv-${ulid()}`,
+      scope,
+      subject,
+      status: "active",
+      participants: [],
+      metadata: {},
+      created_at: now,
+      updated_at: now,
+    };
+    this.storage.putConversation(conv);
+    return conv.id;
+  }
+
+  private ensureParticipant(conversationId: string, agentId: string): void {
+    const conv = this.storage.getConversation(conversationId);
+    if (!conv) return;
+    if (conv.participants.some((p) => p.agent_id === agentId)) return;
+    conv.participants.push({
+      agent_id: agentId,
+      joined_at: new Date().toISOString(),
+    });
+    this.storage.putConversation(conv);
+  }
+
+  private resolveThread(
+    message: Message,
+    conversationId: string,
+    turnId: string
+  ): string {
+    // Find the root of the reply chain
+    const rootMessageId = this.findRootMessage(message.in_reply_to!);
+
+    const existingThreadId = this.replyChainToThread.get(rootMessageId);
+    if (existingThreadId) return existingThreadId;
+
+    // Create new thread
+    const rootTurnId =
+      this.findTurnForMessage(rootMessageId) ?? turnId;
+    const thread: Thread = {
+      id: `thread-${ulid()}`,
+      conversation_id: conversationId,
+      root_turn_id: rootTurnId,
+      subject: message.subject,
+      created_at: new Date().toISOString(),
+    };
+    this.storage.putThread(thread);
+    this.replyChainToThread.set(rootMessageId, thread.id);
+    return thread.id;
+  }
+
+  private findRootMessage(messageId: string): string {
+    const msg = this.storage.getMessage(messageId);
+    if (!msg || !msg.in_reply_to) return messageId;
+    return this.findRootMessage(msg.in_reply_to);
+  }
+
+  private findTurnForMessage(messageId: string): string | undefined {
+    // Look through all conversations for a turn with this source_message_id
+    for (const conv of this.storage.listConversations()) {
+      const turns = this.storage.getTurns(conv.id);
+      const turn = turns.find((t) => t.source_message_id === messageId);
+      if (turn) return turn.id;
+    }
+    return undefined;
+  }
+}

package/src/types.ts

@@ -0,0 +1,297 @@
+// Core types for Agent Inbox
+
+// --- Agent ---
+
+export type AgentStatus = "active" | "idle" | "offline";
+
+export interface Agent {
+  agent_id: string;
+  display_name?: string;
+  program?: string;
+  model?: string;
+  scope: string;
+  status: AgentStatus;
+  metadata: Record<string, unknown>;
+  registered_at: string;
+  last_active_at: string;
+}
+
+// --- Message Content ---
+
+export type MessageContent =
+  | { type: "text"; text: string }
+  | { type: "data"; schema?: string; data: unknown }
+  | { type: "event"; event: string; data?: unknown }
+  | { type: "reference"; uri: string; label?: string }
+  | { type: string; [key: string]: unknown };
+
+export type RecipientKind = "to" | "cc" | "bcc";
+export type Importance = "low" | "normal" | "high" | "urgent";
+
+export interface Recipient {
+  agent_id: string;
+  kind: RecipientKind;
+  delivered_at?: string;
+  read_at?: string;
+  ack_at?: string;
+}
+
+export interface Message {
+  id: string;
+  scope: string;
+  sender_id: string;
+  recipients: Recipient[];
+  subject?: string;
+  content: MessageContent;
+  thread_tag?: string;
+  in_reply_to?: string;
+  conversation_id?: string;
+  importance: Importance;
+  metadata: Record<string, unknown>;
+  created_at: string;
+}
+
+// --- Traceability ---
+
+export type ConversationStatus = "active" | "completed" | "archived";
+
+export interface Participant {
+  agent_id: string;
+  role?: string;
+  joined_at: string;
+}
+
+export interface Conversation {
+  id: string;
+  scope: string;
+  subject?: string;
+  status: ConversationStatus;
+  participants: Participant[];
+  metadata: Record<string, unknown>;
+  created_at: string;
+  updated_at: string;
+}
+
+export type ContentType = "text" | "data" | "event" | "reference" | string;
+
+export interface Turn {
+  id: string;
+  conversation_id: string;
+  participant_id: string;
+  source_message_id?: string;
+  content_type: ContentType;
+  content: MessageContent;
+  thread_id?: string;
+  in_reply_to?: string;
+  created_at: string;
+}
+
+export interface Thread {
+  id: string;
+  conversation_id: string;
+  root_turn_id: string;
+  parent_thread_id?: string;
+  subject?: string;
+  created_at: string;
+}
+
+// --- IPC Protocol ---
+
+export interface IpcSendCommand {
+  action: "send";
+  from: string;
+  to: string | string[] | { agent_id: string; kind?: RecipientKind }[];
+  payload: unknown;
+  scope?: string;
+  threadTag?: string;
+  inReplyTo?: string;
+  importance?: Importance;
+  meta?: Record<string, unknown>;
+}
+
+export interface IpcEmitCommand {
+  action: "emit";
+  event: unknown;
+  meta?: Record<string, unknown>;
+}
+
+export interface IpcNotifyCommand {
+  action: "notify";
+  event: {
+    type: string;
+    agent?: {
+      agentId: string;
+      name?: string;
+      role?: string;
+      scopes?: string[];
+      metadata?: Record<string, unknown>;
+    };
+    agentId?: string;
+    reason?: string;
+    [key: string]: unknown;
+  };
+}
+
+export interface IpcCheckInboxCommand {
+  action: "check_inbox";
+  agentId?: string;
+  scope?: string;
+  unreadOnly?: boolean;
+  clear?: boolean;
+}
+
+export interface IpcPingCommand {
+  action: "ping";
+}
+
+export type IpcCommand =
+  | IpcSendCommand
+  | IpcEmitCommand
+  | IpcNotifyCommand
+  | IpcCheckInboxCommand
+  | IpcPingCommand;
+
+export interface IpcResponse {
+  ok: boolean;
+  messageId?: string;
+  messages?: Message[];
+  error?: string;
+  pid?: number;
+}
+
+// --- Federation ---
+
+export type WarmAgentStatus = "active" | "away" | "expired";
+
+export interface AgentRegistryConfig {
+  /** Time after disconnect before away → expired (default: 60000ms) */
+  gracePeriodMs: number;
+  /** How long to keep expired entries for audit (default: 3600000ms) */
+  retainExpiredMs: number;
+  /** Flush queued messages when agent reconnects (default: true) */
+  requeueOnReconnect: boolean;
+}
+
+export interface FederatedAddress {
+  agent?: string;
+  system?: string;
+  scope?: string;
+}
+
+export interface FederationPeerConfig {
+  systemId: string;
+  url: string;
+  auth?: FederationAuth;
+  exposure?: ExposurePolicy;
+}
+
+export interface FederationAuth {
+  method: "bearer" | "api-key" | "mtls" | "did:wba" | "none";
+  token?: string;
+  key?: string;
+}
+
+export type ExposureLevel = "none" | "gateway" | "tagged" | "all";
+
+export interface ExposurePolicy {
+  agents: ExposureLevel;
+  scopes?: string[];
+  events?: ExposureLevel;
+}
+
+export interface FederationLink {
+  peerId: string;
+  sessionId: string;
+  status: "connected" | "disconnected" | "authenticating";
+  exposure: ExposurePolicy;
+  url: string;
+  connectedAt?: string;
+}
+
+export interface SystemId {
+  id: string;
+  source: "config" | "map" | "auto";
+}
+
+export interface FederationRoutingConfig {
+  strategy: "table" | "broadcast" | "hierarchical";
+  /** Routing entry TTL in ms (default: 300000) */
+  tableTTL?: number;
+  /** Re-query peers on cache miss before failing (default: true) */
+  refreshOnMiss?: boolean;
+  /** Ms to wait for first responder in broadcast mode (default: 5000) */
+  broadcastTimeout?: number;
+  /** System IDs of upstream hubs for hierarchical routing */
+  upstream?: string[];
+}
+
+export interface DeliveryQueueConfig {
+  persistence: "memory" | "sqlite";
+  /** Max age before dropping in ms (default: 86400000 / 24h) */
+  maxTTL: number;
+  /** Max messages per destination (default: 10000) */
+  maxQueueSize: number;
+  retryStrategy: "exponential" | "fixed";
+  /** Base retry interval in ms (default: 1000) */
+  retryBaseInterval: number;
+  /** Max retries, 0 = unlimited until TTL (default: 0) */
+  retryMaxAttempts: number;
+  /** Drain queue when connection restored (default: true) */
+  flushOnReconnect: boolean;
+  overflow: "drop-oldest" | "drop-newest" | "reject-new";
+}
+
+export interface FederationTrustPolicy {
+  /** System IDs or URLs allowed to connect (Layer 1 — implemented) */
+  allowedServers: string[];
+  /** Local scope → allowed remote scopes (Layer 2 — stub) */
+  scopePermissions: Record<string, string[]>;
+  /** Require tokens for cross-server delivery (Layer 3 — stub) */
+  requireAuth: boolean;
+  authMethod?: "bearer" | "api-key" | "mtls" | "did:wba";
+  authTokens?: Record<string, string>;
+}
+
+export interface FederationConfig {
+  systemId?: string;
+  peers?: FederationPeerConfig[];
+  routing?: Partial<FederationRoutingConfig>;
+  deliveryQueue?: Partial<DeliveryQueueConfig>;
+  trust?: Partial<FederationTrustPolicy>;
+  registry?: Partial<AgentRegistryConfig>;
+}
+
+export interface RoutingEntry {
+  agentId: string;
+  peerId: string;
+  lastSeen: string;
+  status: WarmAgentStatus;
+}
+
+export interface QueuedMessage {
+  id: string;
+  peerId: string;
+  message: Message;
+  enqueuedAt: string;
+  attempts: number;
+  lastAttempt?: string;
+  nextRetry?: string;
+}
+
+// --- Config ---
+
+export interface InboxConfig {
+  socketPath?: string;
+  scope?: string;
+  map?: {
+    enabled: boolean;
+    server?: string;
+    scope?: string;
+    systemId?: string;
+    auth?: {
+      token?: string;
+      param?: string;
+    };
+  };
+  federation?: FederationConfig;
+}

package/test/federation/address.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect } from "vitest";
+import {
+  parseAddress,
+  formatAddress,
+  isRemoteAddress,
+  isBroadcastAddress,
+} from "../../src/federation/address.js";
+
+describe("parseAddress", () => {
+  it("should parse local agent ID (no @)", () => {
+    expect(parseAddress("agent-alpha")).toEqual({ agent: "agent-alpha" });
+  });
+
+  it("should parse federated address (agent@system)", () => {
+    expect(parseAddress("agent-beta@backend-team")).toEqual({
+      agent: "agent-beta",
+      system: "backend-team",
+    });
+  });
+
+  it("should parse broadcast address (@system)", () => {
+    expect(parseAddress("@backend-team")).toEqual({
+      agent: undefined,
+      system: "backend-team",
+    });
+  });
+
+  it("should parse address with scope (agent@system/scope)", () => {
+    expect(parseAddress("agent-gamma@ml-team/training")).toEqual({
+      agent: "agent-gamma",
+      system: "ml-team",
+      scope: "training",
+    });
+  });
+
+  it("should parse broadcast with scope (@system/scope)", () => {
+    expect(parseAddress("@ml-team/training")).toEqual({
+      agent: undefined,
+      system: "ml-team",
+      scope: "training",
+    });
+  });
+});
+
+describe("formatAddress", () => {
+  it("should format local address", () => {
+    expect(formatAddress({ agent: "agent-alpha" })).toBe("agent-alpha");
+  });
+
+  it("should format federated address", () => {
+    expect(
+      formatAddress({ agent: "agent-beta", system: "backend-team" })
+    ).toBe("agent-beta@backend-team");
+  });
+
+  it("should format broadcast address", () => {
+    expect(formatAddress({ system: "backend-team" })).toBe("@backend-team");
+  });
+
+  it("should format address with scope", () => {
+    expect(
+      formatAddress({
+        agent: "agent-gamma",
+        system: "ml-team",
+        scope: "training",
+      })
+    ).toBe("agent-gamma@ml-team/training");
+  });
+});
+
+describe("isRemoteAddress", () => {
+  it("should return false for local address", () => {
+    expect(isRemoteAddress({ agent: "local-agent" })).toBe(false);
+  });
+
+  it("should return true for federated address", () => {
+    expect(
+      isRemoteAddress({ agent: "remote-agent", system: "other-system" })
+    ).toBe(true);
+  });
+
+  it("should return true for broadcast address", () => {
+    expect(isRemoteAddress({ system: "other-system" })).toBe(true);
+  });
+});
+
+describe("isBroadcastAddress", () => {
+  it("should return false for local address", () => {
+    expect(isBroadcastAddress({ agent: "local-agent" })).toBe(false);
+  });
+
+  it("should return false for targeted federated address", () => {
+    expect(
+      isBroadcastAddress({ agent: "remote-agent", system: "other-system" })
+    ).toBe(false);
+  });
+
+  it("should return true for system-only address", () => {
+    expect(isBroadcastAddress({ system: "other-system" })).toBe(true);
+  });
+});