agent-inbox 0.1.8 → 0.1.9

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)

package/test/ipc-new-commands.test.ts

@@ -0,0 +1,200 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as net from "node:net";
+import * as os from "node:os";
+import * as path from "node:path";
+import { EventEmitter } from "node:events";
+import { InMemoryStorage } from "../src/storage/memory.js";
+import { MessageRouter } from "../src/router/message-router.js";
+import { IpcServer } from "../src/ipc/ipc-server.js";
+
+function tmpSocketPath(): string {
+  return path.join(os.tmpdir(), `inbox-test-${Date.now()}-${Math.random().toString(36).slice(2)}.sock`);
+}
+
+function sendCommand(socketPath: string, command: object): Promise<Record<string, unknown>> {
+  return new Promise((resolve, reject) => {
+    const client = net.createConnection(socketPath, () => {
+      client.write(JSON.stringify(command) + "\n");
+    });
+    let buffer = "";
+    client.on("data", (data) => {
+      buffer += data.toString();
+      const idx = buffer.indexOf("\n");
+      if (idx !== -1) {
+        const line = buffer.slice(0, idx);
+        client.end();
+        resolve(JSON.parse(line));
+      }
+    });
+    client.on("error", reject);
+  });
+}
+
+describe("IPC read_thread command", () => {
+  let storage: InMemoryStorage;
+  let events: EventEmitter;
+  let router: MessageRouter;
+  let server: IpcServer;
+  let socketPath: string;
+
+  beforeEach(async () => {
+    storage = new InMemoryStorage();
+    events = new EventEmitter();
+    router = new MessageRouter(storage, events, "default");
+    socketPath = tmpSocketPath();
+    server = new IpcServer(socketPath, router, storage);
+    await server.start();
+  });
+
+  afterEach(async () => {
+    await server.stop();
+  });
+
+  it("should return empty thread for unknown tag", async () => {
+    const resp = await sendCommand(socketPath, {
+      action: "read_thread",
+      threadTag: "nonexistent",
+    });
+    expect(resp.ok).toBe(true);
+    expect(resp.threadTag).toBe("nonexistent");
+    expect(resp.count).toBe(0);
+    expect(resp.messages).toEqual([]);
+  });
+
+  it("should return messages in a thread", async () => {
+    // Send messages with same threadTag
+    await sendCommand(socketPath, {
+      action: "send",
+      from: "alice",
+      to: "bob",
+      payload: "first message",
+      threadTag: "task-42",
+    });
+    await sendCommand(socketPath, {
+      action: "send",
+      from: "bob",
+      to: "alice",
+      payload: "reply to first",
+      threadTag: "task-42",
+    });
+    // Different thread
+    await sendCommand(socketPath, {
+      action: "send",
+      from: "alice",
+      to: "charlie",
+      payload: "unrelated",
+      threadTag: "task-99",
+    });
+
+    const resp = await sendCommand(socketPath, {
+      action: "read_thread",
+      threadTag: "task-42",
+      scope: "default",
+    });
+
+    expect(resp.ok).toBe(true);
+    expect(resp.count).toBe(2);
+    const messages = resp.messages as Array<{ sender_id: string }>;
+    expect(messages).toHaveLength(2);
+    const senders = messages.map((m) => m.sender_id);
+    expect(senders).toContain("alice");
+    expect(senders).toContain("bob");
+  });
+});
+
+describe("IPC list_agents command", () => {
+  let storage: InMemoryStorage;
+  let events: EventEmitter;
+  let router: MessageRouter;
+  let server: IpcServer;
+  let socketPath: string;
+
+  beforeEach(async () => {
+    storage = new InMemoryStorage();
+    events = new EventEmitter();
+    router = new MessageRouter(storage, events, "default");
+    socketPath = tmpSocketPath();
+    server = new IpcServer(socketPath, router, storage);
+    await server.start();
+  });
+
+  afterEach(async () => {
+    await server.stop();
+  });
+
+  it("should return empty list with no agents", async () => {
+    const resp = await sendCommand(socketPath, {
+      action: "list_agents",
+    });
+    expect(resp.ok).toBe(true);
+    expect(resp.count).toBe(0);
+    expect(resp.agents).toEqual([]);
+  });
+
+  it("should list registered agents", async () => {
+    // Register agents via notify
+    await sendCommand(socketPath, {
+      action: "notify",
+      event: {
+        type: "agent.spawn",
+        agent: {
+          agentId: "gsd-executor",
+          name: "executor",
+          scopes: ["swarm:gsd"],
+          metadata: { role: "executor" },
+        },
+      },
+    });
+    await sendCommand(socketPath, {
+      action: "notify",
+      event: {
+        type: "agent.spawn",
+        agent: {
+          agentId: "gsd-verifier",
+          name: "verifier",
+          scopes: ["swarm:gsd"],
+        },
+      },
+    });
+
+    const resp = await sendCommand(socketPath, {
+      action: "list_agents",
+    });
+
+    expect(resp.ok).toBe(true);
+    expect(resp.count).toBe(2);
+    const agents = resp.agents as Array<{ agentId: string; location: string }>;
+    expect(agents).toHaveLength(2);
+    const ids = agents.map((a) => a.agentId);
+    expect(ids).toContain("gsd-executor");
+    expect(ids).toContain("gsd-verifier");
+    expect(agents[0].location).toBe("local");
+  });
+
+  it("should filter agents by scope", async () => {
+    await sendCommand(socketPath, {
+      action: "notify",
+      event: {
+        type: "agent.spawn",
+        agent: { agentId: "team1-a", name: "a", scopes: ["team1"] },
+      },
+    });
+    await sendCommand(socketPath, {
+      action: "notify",
+      event: {
+        type: "agent.spawn",
+        agent: { agentId: "team2-b", name: "b", scopes: ["team2"] },
+      },
+    });
+
+    const resp = await sendCommand(socketPath, {
+      action: "list_agents",
+      scope: "team1",
+    });
+
+    expect(resp.ok).toBe(true);
+    expect(resp.count).toBe(1);
+    const agents = resp.agents as Array<{ agentId: string }>;
+    expect(agents[0].agentId).toBe("team1-a");
+  });
+});