agent-inbox 0.1.8 → 0.2.0

package/src/mesh/mesh-transport.ts

@@ -0,0 +1,157 @@
+import type {
+  MapConnection,
+  IncomingMapMessage,
+} from "../map/map-client.js";
+
+// ---------------------------------------------------------------------------
+// Minimal type stubs for agentic-mesh.
+// We only reference the subset of MeshContext / IMessageChannel that
+// MeshTransport actually uses, so agent-inbox compiles without importing
+// the full agentic-mesh package (it's an optional peer dep).
+// ---------------------------------------------------------------------------
+
+/** Subset of agentic-mesh PeerInfo used by MeshTransport. */
+export interface MeshPeerInfo {
+  id: string;
+  name?: string;
+  groups: string[];
+}
+
+/** Subset of agentic-mesh IMessageChannel<T>. */
+export interface MeshChannel<T> {
+  readonly name: string;
+  readonly isOpen: boolean;
+  open(): Promise<void>;
+  close(): Promise<void>;
+  send(peerId: string, message: T): boolean;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  on(event: string | symbol, listener: (...args: any[]) => void): this;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  off(event: string | symbol, listener: (...args: any[]) => void): this;
+}
+
+/** Subset of agentic-mesh MeshContext used by MeshTransport. */
+export interface MeshContextLike {
+  createChannel<T>(name: string): MeshChannel<T>;
+  _getPeerId(): string;
+}
+
+// ---------------------------------------------------------------------------
+// Wire format
+// ---------------------------------------------------------------------------
+
+/**
+ * Payload exchanged over the mesh channel between agent-inbox instances.
+ * Flat structure that maps 1-to-1 with IncomingMapMessage.
+ */
+export interface InboxWireMessage {
+  to?: { agentId?: string; scope?: string };
+  payload: unknown;
+  from: string;
+  timestamp?: string;
+  meta?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// MeshTransport
+// ---------------------------------------------------------------------------
+
+/** Default channel name used for agent-inbox federation traffic.
+ *  Uses the "proto:" prefix to distinguish protocol channels from
+ *  application channels on the same mesh. */
+export const DEFAULT_CHANNEL_NAME = "proto:agent-inbox";
+
+/**
+ * Implements the MapConnection interface over an agentic-mesh MessageChannel.
+ *
+ * Each instance represents a connection to a single remote peer. Multiple
+ * MeshTransport instances share the same underlying channel (one channel
+ * per mesh, not per peer) and filter incoming messages by remotePeerId.
+ */
+export class MeshTransport implements MapConnection {
+  private channel: MeshChannel<InboxWireMessage>;
+  private handlers: ((msg: IncomingMapMessage) => void)[] = [];
+  private messageListener: ((message: InboxWireMessage, from: MeshPeerInfo) => void) | null = null;
+  private closed = false;
+  readonly systemName: string;
+
+  constructor(
+    private mesh: MeshContextLike,
+    private localPeerId: string,
+    private remotePeerId: string,
+    channelName: string = DEFAULT_CHANNEL_NAME
+  ) {
+    this.systemName = remotePeerId;
+    this.channel = mesh.createChannel<InboxWireMessage>(channelName);
+  }
+
+  /**
+   * Open the underlying channel and start listening for messages.
+   * Must be called before send() or onMessage().
+   */
+  async open(): Promise<void> {
+    if (!this.channel.isOpen) {
+      await this.channel.open();
+    }
+    this.messageListener = (message: InboxWireMessage, from: MeshPeerInfo) => {
+      if (this.closed) return;
+      // Only process messages from our remote peer
+      if (from.id !== this.remotePeerId) return;
+      const incoming = wireToIncoming(message);
+      for (const handler of this.handlers) {
+        handler(incoming);
+      }
+    };
+    this.channel.on("message", this.messageListener);
+  }
+
+  async send(
+    to: { agentId?: string; scope?: string },
+    payload: unknown,
+    meta?: Record<string, unknown>
+  ): Promise<void> {
+    if (this.closed) {
+      throw new Error("MeshTransport is closed");
+    }
+    const wire: InboxWireMessage = {
+      to,
+      payload,
+      from: this.localPeerId,
+      timestamp: new Date().toISOString(),
+      meta,
+    };
+    const sent = this.channel.send(this.remotePeerId, wire);
+    if (!sent) {
+      throw new Error(
+        `Failed to send to peer "${this.remotePeerId}" — peer may be offline`
+      );
+    }
+  }
+
+  onMessage(handler: (msg: IncomingMapMessage) => void): void {
+    this.handlers.push(handler);
+  }
+
+  async disconnect(): Promise<void> {
+    this.closed = true;
+    if (this.messageListener) {
+      this.channel.off("message", this.messageListener);
+      this.messageListener = null;
+    }
+    this.handlers = [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function wireToIncoming(wire: InboxWireMessage): IncomingMapMessage {
+  return {
+    from: wire.from,
+    to: wire.to,
+    payload: wire.payload,
+    timestamp: wire.timestamp,
+    meta: wire.meta,
+  };
+}

package/src/mesh/type-mapper.ts

@@ -0,0 +1,239 @@
+/**
+ * Type mapping between agentic-mesh MAP messages and agent-inbox messages.
+ *
+ * Translates MAP Message (from agentic-mesh's MapServer/FederationGateway)
+ * into agent-inbox's internal Message format and vice versa.
+ *
+ * Inbox-specific fields (subject, thread_tag, importance, recipientKind)
+ * are encoded in the MAP message's `_meta` vendor extension field.
+ */
+
+import { ulid } from "ulid";
+import { normalizeContent } from "../router/message-router.js";
+import type {
+  Message,
+  Recipient,
+  RecipientKind,
+  Importance,
+} from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Minimal MAP message type stubs (matches agentic-mesh v0.2.0)
+// ---------------------------------------------------------------------------
+
+/** MAP Message as delivered by agentic-mesh's MapServer. */
+export interface MapMessage {
+  id: string;
+  from: string;
+  to: MapAddress;
+  timestamp: number;
+  payload?: unknown;
+  meta?: MapMessageMeta;
+  _meta?: Record<string, unknown>;
+}
+
+export type MapAddress =
+  | string
+  | { agent: string }
+  | { agents: string[] }
+  | { scope: string }
+  | { role: string; within?: string }
+  | { broadcast: true }
+  | { system: string; agent: string }
+  | Record<string, unknown>;
+
+export interface MapMessageMeta {
+  priority?: "urgent" | "high" | "normal" | "low";
+  correlationId?: string;
+  delivery?: "fire-and-forget" | "acknowledged" | "guaranteed";
+  _meta?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// MAP → Inbox
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a MAP Message from agentic-mesh into an agent-inbox Message.
+ *
+ * Inbox-specific fields are read from `_meta` (or `meta._meta`):
+ * - `_meta.subject` → `subject`
+ * - `_meta.threadTag` / `meta.correlationId` → `thread_tag`
+ * - `_meta.inReplyTo` → `in_reply_to`
+ * - `_meta.recipientKind` → per-recipient `kind`
+ * - `_meta.inboxMessageId` → used as `id` if present
+ * - `meta.priority` → `importance`
+ */
+export function mapMessageToInbox(
+  mapMsg: MapMessage,
+  scope: string = "default"
+): Message {
+  const vendorMeta = mapMsg._meta ?? mapMsg.meta?._meta ?? {};
+  const recipients = resolveMapAddress(mapMsg.to, vendorMeta);
+
+  const priority = mapMsg.meta?.priority;
+  const importance: Importance =
+    priority === "urgent"
+      ? "urgent"
+      : priority === "high"
+        ? "high"
+        : priority === "low"
+          ? "low"
+          : "normal";
+
+  return {
+    id: (vendorMeta.inboxMessageId as string) ?? ulid(),
+    scope,
+    sender_id: mapMsg.from,
+    recipients,
+    content: normalizeContent(mapMsg.payload),
+    importance,
+    subject: vendorMeta.subject as string | undefined,
+    thread_tag:
+      (vendorMeta.threadTag as string) ?? mapMsg.meta?.correlationId,
+    in_reply_to: vendorMeta.inReplyTo as string | undefined,
+    conversation_id: vendorMeta.conversationId as string | undefined,
+    metadata: stripInboxKeys(vendorMeta),
+    created_at: new Date(mapMsg.timestamp).toISOString(),
+  };
+}
+
+/**
+ * Resolve a MAP Address into agent-inbox Recipients.
+ */
+function resolveMapAddress(
+  addr: MapAddress,
+  vendorMeta: Record<string, unknown>
+): Recipient[] {
+  const kind = (vendorMeta.recipientKind as RecipientKind) ?? "to";
+  const now = new Date().toISOString();
+
+  if (typeof addr === "string") {
+    return [{ agent_id: addr, kind, delivered_at: now }];
+  }
+
+  // Federated address must be checked before simple agent address
+  // since { system: "x", agent: "y" } also matches "agent" in addr
+  if (
+    "system" in addr &&
+    "agent" in addr &&
+    typeof addr.system === "string" &&
+    typeof addr.agent === "string"
+  ) {
+    return [
+      { agent_id: `${addr.agent}@${addr.system}`, kind, delivered_at: now },
+    ];
+  }
+
+  if ("agent" in addr && typeof addr.agent === "string") {
+    return [{ agent_id: addr.agent, kind, delivered_at: now }];
+  }
+
+  if ("agents" in addr && Array.isArray(addr.agents)) {
+    return addr.agents.map((agentId: string) => ({
+      agent_id: agentId,
+      kind,
+      delivered_at: now,
+    }));
+  }
+
+  if ("scope" in addr && typeof addr.scope === "string") {
+    return [{ agent_id: addr.scope, kind, delivered_at: now }];
+  }
+
+  if ("broadcast" in addr) {
+    return [{ agent_id: "*", kind, delivered_at: now }];
+  }
+
+  return [];
+}
+
+// Keys that belong to the inbox layer, not stored in metadata
+const INBOX_META_KEYS = new Set([
+  "subject",
+  "threadTag",
+  "inReplyTo",
+  "recipientKind",
+  "inboxMessageId",
+  "conversationId",
+  "importance",
+]);
+
+function stripInboxKeys(
+  meta: Record<string, unknown>
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(meta)) {
+    if (!INBOX_META_KEYS.has(k)) {
+      result[k] = v;
+    }
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Inbox → MAP
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert an agent-inbox Message into partial MAP message fields
+ * suitable for sending via `AgentConnection.send()` or `FederationGateway.route()`.
+ *
+ * Returns `to`, `payload`, and `meta` (including `_meta` for inbox fields).
+ */
+export function inboxMessageToMap(msg: Message): {
+  to: MapAddress;
+  payload: unknown;
+  meta: MapMessageMeta & { _meta: Record<string, unknown> };
+} {
+  // Build the MAP address from recipients
+  const primaryRecipients = msg.recipients.filter((r) => r.kind === "to");
+  const to = resolveRecipientsToAddress(primaryRecipients);
+
+  const priority: MapMessageMeta["priority"] =
+    msg.importance === "urgent"
+      ? "urgent"
+      : msg.importance === "high"
+        ? "high"
+        : msg.importance === "low"
+          ? "low"
+          : "normal";
+
+  return {
+    to,
+    payload: msg.content,
+    meta: {
+      priority,
+      correlationId: msg.thread_tag,
+      _meta: {
+        inboxMessageId: msg.id,
+        ...(msg.subject ? { subject: msg.subject } : {}),
+        ...(msg.thread_tag ? { threadTag: msg.thread_tag } : {}),
+        ...(msg.in_reply_to ? { inReplyTo: msg.in_reply_to } : {}),
+        ...(msg.conversation_id
+          ? { conversationId: msg.conversation_id }
+          : {}),
+        ...msg.metadata,
+      },
+    },
+  };
+}
+
+function resolveRecipientsToAddress(recipients: Recipient[]): MapAddress {
+  if (recipients.length === 0) {
+    return { broadcast: true };
+  }
+  if (recipients.length === 1) {
+    const agentId = recipients[0].agent_id;
+    // Check for federated address (agent@system)
+    const atIdx = agentId.indexOf("@");
+    if (atIdx > 0) {
+      return {
+        system: agentId.slice(atIdx + 1),
+        agent: agentId.slice(0, atIdx),
+      };
+    }
+    return { agent: agentId };
+  }
+  return { agents: recipients.map((r) => r.agent_id) };
+}

package/src/types.ts

@@ -140,6 +140,18 @@ export interface IpcCheckInboxCommand {
   clear?: boolean;
 }
 
+export interface IpcReadThreadCommand {
+  action: "read_thread";
+  threadTag: string;
+  scope?: string;
+}
+
+export interface IpcListAgentsCommand {
+  action: "list_agents";
+  scope?: string;
+  includeFederated?: boolean;
+}
+
 export interface IpcPingCommand {
   action: "ping";
 }
@@ -149,12 +161,26 @@ export type IpcCommand =
   | IpcEmitCommand
   | IpcNotifyCommand
   | IpcCheckInboxCommand
+  | IpcReadThreadCommand
+  | IpcListAgentsCommand
   | IpcPingCommand;
 
 export interface IpcResponse {
   ok: boolean;
   messageId?: string;
   messages?: Message[];
+  agents?: Array<{
+    agentId: string;
+    name?: string;
+    scope: string;
+    status: string;
+    program?: string;
+    lastActive?: string;
+    location: "local" | "federated";
+    peerId?: string;
+  }>;
+  count?: number;
+  threadTag?: string;
   error?: string;
   pid?: number;
 }
@@ -180,7 +206,10 @@ export interface FederatedAddress {
 
 export interface FederationPeerConfig {
   systemId: string;
-  url: string;
+  /** WebSocket URL for MAP SDK connections. */
+  url?: string;
+  /** Mesh peer ID for agentic-mesh transport connections. */
+  meshPeerId?: string;
   auth?: FederationAuth;
   exposure?: ExposurePolicy;
 }
@@ -199,12 +228,15 @@ export interface ExposurePolicy {
   events?: ExposureLevel;
 }
 
+export type FederationTransport = "websocket" | "mesh";
+
 export interface FederationLink {
   peerId: string;
   sessionId: string;
   status: "connected" | "disconnected" | "authenticating";
   exposure: ExposurePolicy;
   url: string;
+  transport: FederationTransport;
   connectedAt?: string;
 }
 

package/test/federation/integration.test.ts

@@ -185,7 +185,7 @@ describe("Federation Integration", () => {
       await hubFederation.destroy();
     });
 
-    it("should queue when system-qualified address has no peer link", async () => {
+    it("should relay via upstream hub when system-qualified address has no direct peer link", async () => {
       const hubFederation = new ConnectionManager(events, {
         systemId: "system-1",
         trust: {
@@ -204,7 +204,8 @@ describe("Federation Integration", () => {
         url: "ws://hub:3000",
       });
 
-      // Route to far-system which has no peer link — gets queued for far-system
+      // Route to far-system which has no direct peer link.
+      // With hierarchical strategy, falls through to upstream hub relay.
       const msg: Message = {
         id: "msg-hub-2",
         scope: "default",
@@ -217,11 +218,44 @@ describe("Federation Integration", () => {
       };
 
       const result = await hubFederation.route(msg);
+      // Hierarchical strategy delegates to upstream hub instead of queuing
+      expect(result.delivered).toBe(true);
+      expect(result.peerId).toBe("hub-system");
+
+      await hubFederation.destroy();
+    });
+
+    it("should queue when system-qualified address has no peer link (table strategy)", async () => {
+      const tableFederation = new ConnectionManager(events, {
+        systemId: "system-1",
+        trust: {
+          allowedServers: [],
+          scopePermissions: {},
+          requireAuth: false,
+        },
+        routing: {
+          strategy: "table",
+        },
+      });
+
+      // No peers connected — route to far-system queues immediately
+      const msg: Message = {
+        id: "msg-table-1",
+        scope: "default",
+        sender_id: "agent-a",
+        recipients: [{ agent_id: "agent-x@far-system", kind: "to" }],
+        content: { type: "text", text: "no direct link" },
+        importance: "normal",
+        metadata: {},
+        created_at: new Date().toISOString(),
+      };
+
+      const result = await tableFederation.route(msg);
       expect(result.delivered).toBe(false);
       expect(result.queued).toBe(true);
       expect(result.peerId).toBe("far-system");
 
-      await hubFederation.destroy();
+      await tableFederation.destroy();
     });
   });
 

package/test/federation/sdk-integration.test.ts

@@ -477,14 +477,10 @@ describe("Federation SDK Integration (two-system)", () => {
   });
 
   describe("broadcast strategy with real transport", () => {
-    // NOTE: In the current routing implementation, broadcast/hierarchical strategies
-    // are only reachable via handleUnknownRoute(), which requires resolveRoute()
-    // to return null. This only happens for agent-only addresses (no @system),
-    // but those are filtered out by isRemoteAddress() in route().
-    //
-    // System-qualified addresses like "bob@system-2" always resolve via addr.system,
-    // bypassing the strategy entirely. This is a known design gap documented in
-    // integration.test.ts.
+    // For system-qualified addresses (bob@system-2) where the target system IS a
+    // connected peer, delivery goes directly via transport (no broadcast needed).
+    // Broadcast/hierarchical strategies activate when the resolved peer has no
+    // active link — e.g., targeting a system we're not directly connected to.
     //
     // These tests verify broadcast transport by:
     // 1. Testing system-qualified delivery to multiple peers (direct transport)