macro-agent 0.0.10 → 0.0.12

package/src/router/message-router.ts

@@ -1,13 +1,42 @@
 /**
- * MessageRouter - High-level message routing service
+ * MessageRouter - Core Internal Message Routing Service
  *
- * Provides message routing between agents with support for:
- * - Direct agent-to-agent messaging
- * - Task-based routing (to assigned agent)
- * - Topic-based pub/sub
- * - Lineage routing (ancestors to descendants)
- * - Subtree routing (status events to parent subscribers)
- * - Message acknowledgment
+ * ## Routing Architecture
+ *
+ * MessageRouter is the **core internal routing authority** for macro-agent.
+ * It handles all message delivery between internal agents.
+ *
+ * ```
+ * External → MAPAdapter/TriggerRouter → MessageRouter → EventStore
+ *            (protocol translation)     (routing logic)   (persistence)
+ * ```
+ *
+ * **Three routing entry points exist:**
+ *
+ * 1. **MessageRouter** (this module)
+ *    - Internal routing for agent-to-agent communication
+ *    - Supports: send(), sendToAddress(), emitStatus()
+ *    - Used by: AgentManager, MCP tools, internal components
+ *
+ * 2. **MAPAdapter** (src/map/adapter/)
+ *    - External MAP protocol interface for clients/agents/gateways
+ *    - Translates MAP protocol → internal routing
+ *    - Delegates message delivery to MessageRouter
+ *
+ * 3. **TriggerRouter** (src/trigger/router/)
+ *    - External event routing (webhooks, cron, system events)
+ *    - Queues events for batch delivery
+ *    - Uses WakeManager for delivery scheduling
+ *
+ * ## Supported Routing Methods
+ *
+ * **Legacy Channel-based** (send, sendMessage):
+ * - Direct agent, task, topic, lineage, subtree, broadcast
+ *
+ * **MAP Address-based** (sendToAddress):
+ * - Agent, agents, task, scope, role, broadcast, hierarchical, federated
+ *
+ * @module router/message-router
  */
 
 import { nanoid } from "nanoid";
@@ -35,6 +64,7 @@ import type {
   SendToAddressRequest,
   AddressSendResult,
   Address,
+  TurnRecorderCallback,
 } from "./types.js";
 import { RoutingError, AddressRoutingError, DEFAULT_TRUNCATION_CONFIG } from "./types.js";
 import {
@@ -62,6 +92,7 @@ import {
   isFederatedAddress,
   describeAddress,
 } from "../map/types.js";
+import type { DeliveryHint, HierarchicalAddress } from "../map/types.js";
 import type { FederationHandler } from "../map/federation/types.js";
 import { getSystemFromAddress } from "../map/federation/federation-handler.js";
 import {
@@ -166,8 +197,68 @@ export interface MessageRouter {
    * - Optionally subscribes parent to agent's subtree
    */
   setupDefaultSubscriptions(options: DefaultSubscriptionOptions): void;
+
+  /**
+   * Set turn recorder for conversation tracking.
+   * Called after direct message (agent/task address) delivery.
+   * Supports late binding since mail services may be created after router.
+   */
+  setTurnRecorder(recorder: TurnRecorderCallback): void;
+
+  /**
+   * Set signal filter for status notification delivery.
+   * Called before delivering each status notification — return false to suppress.
+   * Supports late binding since TeamRuntime is created after router.
+   */
+  setSignalFilter(filter: SignalFilter): void;
+
+  /**
+   * Set emission validator for outbound status events.
+   * Called before emitting a status event — can reject, warn, or audit.
+   * Supports late binding since TeamRuntime is created after router.
+   */
+  setEmissionValidator(validator: EmissionValidator): void;
 }
 
+/**
+ * Signal filter callback for status notification delivery.
+ * Return true to deliver, false to suppress.
+ *
+ * @param from - Agent emitting the status
+ * @param to - Agent that would receive the notification
+ * @param signal - Signal name from details.signal (undefined if not tagged)
+ */
+export type SignalFilter = (
+  from: AgentId,
+  to: AgentId,
+  signal: string | undefined
+) => boolean;
+
+/**
+ * Emission validator result.
+ * - "allow": emit normally
+ * - "reject": block the emission (strict mode)
+ * - "warn": log warning but allow (permissive mode)
+ * - "audit": record audit event but allow (audit mode)
+ */
+export type EmissionValidatorResult = {
+  action: "allow" | "reject" | "warn" | "audit";
+  message?: string;
+};
+
+/**
+ * Emission validator callback for outbound status events.
+ * Called with the emitting agent's ID and the signal name.
+ * Returns an action to take (allow, reject, warn, audit).
+ *
+ * @param agentId - Agent emitting the status
+ * @param signal - Signal name from details.signal (undefined if not tagged)
+ */
+export type EmissionValidator = (
+  agentId: AgentId,
+  signal: string | undefined
+) => EmissionValidatorResult;
+
 /**
  * Callback invoked when a message determines a wake action
  */
@@ -223,6 +314,15 @@ export function createMessageRouter(
   const wakeHandler = config.wakeHandler;
   const federationHandler = config.federationHandler;
 
+  // Turn recorder for conversation tracking (late-bound)
+  let turnRecorder: TurnRecorderCallback | undefined;
+
+  // Signal filter for status notification delivery (late-bound)
+  let signalFilter: SignalFilter | undefined;
+
+  // Emission validator for outbound status events (late-bound)
+  let emissionValidator: EmissionValidator | undefined;
+
   // Track acknowledged messages: Map<agentId, Set<messageId>>
   const acknowledgedMessages = new Map<AgentId, Set<EventId>>();
 
@@ -323,7 +423,7 @@ export function createMessageRouter(
       if (sessionChecker && wakeHandler) {
         const decision = getWakeDecisionWithHint(
           to.agent,
-          { priority: priority as MessagePriority, deliveryHint: delivery as import("../map/types.js").DeliveryHint | undefined },
+          { priority: priority as MessagePriority, deliveryHint: delivery as DeliveryHint | undefined },
           sessionChecker
         );
         if (decision.shouldWake || decision.shouldInterrupt) {
@@ -333,6 +433,15 @@ export function createMessageRouter(
 
       delivered.push(to.agent);
 
+      // Record turn for conversation tracking
+      if (turnRecorder) {
+        try {
+          turnRecorder({ from, toAgent: to.agent, content, messageId: event.id, addressType: "agent" });
+        } catch {
+          // Never fail delivery due to turn recording
+        }
+      }
+
       return {
         id: event.id,
         from,
@@ -392,7 +501,7 @@ export function createMessageRouter(
       if (sessionChecker && wakeHandler) {
         const decision = getWakeDecisionWithHint(
           targetAgentId,
-          { priority: priority as MessagePriority, deliveryHint: delivery as import("../map/types.js").DeliveryHint | undefined },
+          { priority: priority as MessagePriority, deliveryHint: delivery as DeliveryHint | undefined },
           sessionChecker
         );
         if (decision.shouldWake || decision.shouldInterrupt) {
@@ -402,6 +511,15 @@ export function createMessageRouter(
 
       delivered.push(targetAgentId);
 
+      // Record turn for conversation tracking
+      if (turnRecorder) {
+        try {
+          turnRecorder({ from, toAgent: targetAgentId, content, messageId: event.id, addressType: "task" });
+        } catch {
+          // Never fail delivery due to turn recording
+        }
+      }
+
       return {
         id: event.id,
         from,
@@ -451,7 +569,7 @@ export function createMessageRouter(
         if (sessionChecker && wakeHandler) {
           const decision = getWakeDecisionWithHint(
             subscriberId,
-            { priority: priority as MessagePriority, deliveryHint: delivery as import("../map/types.js").DeliveryHint | undefined },
+            { priority: priority as MessagePriority, deliveryHint: delivery as DeliveryHint | undefined },
             sessionChecker
           );
           if (decision.shouldWake || decision.shouldInterrupt) {
@@ -478,11 +596,16 @@ export function createMessageRouter(
       const agentSource: RoleAgentSource = {
         listAgents: () => eventStore.listAgents(),
         getAgent: (id) => eventStore.getAgent(id),
+        // Get agents subscribed to a scope/topic
+        getScopeMembers: (scope) => {
+          return eventStore.getSubscribers({ type: "topic", target: scope });
+        },
       };
 
       const recipientIds = resolveRoleTarget(agentSource, {
         role: to.role,
-        coordinatorId: to.within,
+        // RoleAddress.within is a ScopeId (subscription-based), not a coordinatorId (hierarchy-based)
+        scope: to.within,
       });
 
       if (recipientIds.length === 0) {
@@ -537,7 +660,7 @@ export function createMessageRouter(
         if (sessionChecker && wakeHandler) {
           const decision = getWakeDecisionWithHint(
             recipientId,
-            { priority: priority as MessagePriority, deliveryHint: delivery as import("../map/types.js").DeliveryHint | undefined },
+            { priority: priority as MessagePriority, deliveryHint: delivery as DeliveryHint | undefined },
             sessionChecker
           );
           if (decision.shouldWake || decision.shouldInterrupt) {
@@ -610,7 +733,7 @@ export function createMessageRouter(
         if (sessionChecker && wakeHandler) {
           const decision = getWakeDecisionWithHint(
             recipientId,
-            { priority: priority as MessagePriority, deliveryHint: delivery as import("../map/types.js").DeliveryHint | undefined },
+            { priority: priority as MessagePriority, deliveryHint: delivery as DeliveryHint | undefined },
             sessionChecker
           );
           if (decision.shouldWake || decision.shouldInterrupt) {
@@ -676,7 +799,7 @@ export function createMessageRouter(
 
     // Resolve the hierarchical address
     const resolved = resolveHierarchicalAddress(
-      to as import("../map/types.js").HierarchicalAddress,
+      to as HierarchicalAddress,
       from,
       hierarchySource
     );
@@ -735,7 +858,7 @@ export function createMessageRouter(
           recipientId,
           {
             priority: priority as MessagePriority,
-            deliveryHint: delivery as import("../map/types.js").DeliveryHint | undefined,
+            deliveryHint: delivery as DeliveryHint | undefined,
           },
           sessionChecker
         );
@@ -865,6 +988,36 @@ export function createMessageRouter(
   function emitStatus(request: EmitStatusRequest): void {
     const { from, status_type, summary, details } = request;
 
+    // Check emission restrictions if validator installed
+    if (emissionValidator) {
+      const signal = (details as Record<string, unknown> | undefined)?.signal as string | undefined;
+      const result = emissionValidator(from.agent_id, signal);
+
+      if (result.action === "reject") {
+        // Strict mode: block the emission entirely
+        return;
+      }
+
+      if (result.action === "audit") {
+        // Audit mode: record audit event, then continue with emission
+        eventStore.emit({
+          type: "status",
+          source: { agent_id: "system" },
+          payload: {
+            status_type: "discovery",
+            summary: result.message ?? `Emission audit: agent ${from.agent_id} emitted signal '${signal}'`,
+            audit: {
+              type: "emission_violation",
+              agent_id: from.agent_id,
+              signal,
+              status_type,
+            },
+          },
+        });
+      }
+      // "warn" and "allow" proceed normally (warning is logged by the validator installer)
+    }
+
     // Emit status event to event store
     const event = eventStore.emit({
       type: "status",
@@ -879,15 +1032,20 @@ export function createMessageRouter(
       },
     });
 
-    // Route to subtree subscribers
-    routeStatusToSubtreeSubscribers(from.agent_id, {
+    const statusNotification: StatusNotification = {
       agent_id: from.agent_id,
       task_id: from.task_id,
       status_type,
       summary,
       details,
       timestamp: event.timestamp,
-    });
+    };
+
+    // Route to subtree subscribers (hierarchical: parents/ancestors)
+    const subtreeRecipients = routeStatusToSubtreeSubscribers(from.agent_id, statusNotification);
+
+    // Route to topic co-subscribers (non-hierarchical: peers sharing topics)
+    routeStatusToTopicSubscribers(from.agent_id, statusNotification, subtreeRecipients);
   }
 
   // ─────────────────────────────────────────────────────────────────
@@ -1024,13 +1182,15 @@ export function createMessageRouter(
   /**
    * Route status event to subtree subscribers.
    * Parents who have subscribed to an agent's subtree receive status notifications.
+   * Returns the set of agents that were notified (for dedup with topic routing).
    */
   function routeStatusToSubtreeSubscribers(
     agentId: AgentId,
     status: StatusNotification
-  ): void {
+  ): Set<AgentId> {
+    const notified = new Set<AgentId>();
     const agent = eventStore.getAgent(agentId);
-    if (!agent) return;
+    if (!agent) return notified;
 
     // Find all agents with subtree subscription that includes this agent
     // This includes:
@@ -1064,17 +1224,25 @@ export function createMessageRouter(
       }
     }
 
+    // Extract signal name from details (if tagged)
+    const statusSignal = (status.details as Record<string, unknown> | undefined)?.signal as string | undefined;
+
     // Send status notification to each subscriber
     for (const subscriberId of agentsToNotify) {
       // Skip self-notification
       if (subscriberId === agentId) continue;
 
+      // Apply signal filter if installed
+      if (signalFilter && !signalFilter(agentId, subscriberId, statusSignal)) {
+        continue;
+      }
+
       const statusContent = JSON.stringify({
         type: "status_notification",
         ...status,
       });
 
-      eventStore.emit({
+      const event = eventStore.emit({
         type: "message",
         source: {
           agent_id: agentId,
@@ -1087,7 +1255,122 @@ export function createMessageRouter(
           via: "subtree",
         },
       });
+
+      // Wake sleeping agents on status notifications
+      if (sessionChecker && wakeHandler) {
+        try {
+          const decision = getWakeDecisionWithHint(
+            subscriberId,
+            { priority: "normal" as MessagePriority },
+            sessionChecker
+          );
+          if (decision.shouldWake || decision.shouldInterrupt) {
+            wakeHandler(subscriberId, decision, event.id);
+          }
+        } catch {
+          // Never fail status delivery due to wake errors
+        }
+      }
+
+      notified.add(subscriberId);
+    }
+
+    return notified;
+  }
+
+  /**
+   * Route status event to topic co-subscribers.
+   * Agents sharing topic subscriptions with the emitting agent receive status notifications.
+   * This enables non-hierarchical visibility: peers on the same topic see each other's status.
+   * Skips agents already notified via subtree routing to avoid duplicates.
+   */
+  function routeStatusToTopicSubscribers(
+    agentId: AgentId,
+    status: StatusNotification,
+    alreadyNotified: Set<AgentId>
+  ): void {
+    // Find all topics the emitting agent is subscribed to
+    const subscriptions = eventStore.getSubscriptions(agentId);
+    const topicSubscriptions = subscriptions.filter(
+      (s) => s.type === "topic"
+    );
+
+    if (topicSubscriptions.length === 0) return;
+
+    // Collect unique recipients across all shared topics
+    const topicRecipients = new Set<AgentId>();
+    for (const sub of topicSubscriptions) {
+      const subscribers = eventStore.getSubscribers({
+        type: "topic",
+        target: sub.target,
+      });
+      for (const subscriberId of subscribers) {
+        // Skip self and already-notified (from subtree routing)
+        if (subscriberId !== agentId && !alreadyNotified.has(subscriberId)) {
+          topicRecipients.add(subscriberId);
+        }
+      }
     }
+
+    if (topicRecipients.size === 0) return;
+
+    // Extract signal name from details (if tagged)
+    const statusSignal = (status.details as Record<string, unknown> | undefined)?.signal as string | undefined;
+
+    const statusContent = JSON.stringify({
+      type: "status_notification",
+      ...status,
+    });
+
+    // Deliver to each topic co-subscriber
+    for (const recipientId of topicRecipients) {
+      // Apply signal filter if installed
+      if (signalFilter && !signalFilter(agentId, recipientId, statusSignal)) {
+        continue;
+      }
+
+      const event = eventStore.emit({
+        type: "message",
+        source: {
+          agent_id: agentId,
+        },
+        target: {
+          agent_id: recipientId,
+        },
+        payload: {
+          content: statusContent,
+          via: "topic",
+        },
+      });
+
+      // Wake sleeping agents on status notifications
+      if (sessionChecker && wakeHandler) {
+        try {
+          const decision = getWakeDecisionWithHint(
+            recipientId,
+            { priority: "normal" as MessagePriority },
+            sessionChecker
+          );
+          if (decision.shouldWake || decision.shouldInterrupt) {
+            wakeHandler(recipientId, decision, event.id);
+          }
+        } catch {
+          // Never fail status delivery due to wake errors
+        }
+      }
+    }
+  }
+
+  function setTurnRecorder(recorder: TurnRecorderCallback): void {
+    turnRecorder = recorder;
+  }
+
+  function setSignalFilter(filter: SignalFilter): void {
+    signalFilter = filter;
+  }
+
+  function setEmissionValidator(validator: EmissionValidator): void {
+    emissionValidator = validator;
   }
 
   return {
@@ -1102,5 +1385,8 @@ export function createMessageRouter(
     getSubscriptions,
     getSubscribers,
     setupDefaultSubscriptions,
+    setTurnRecorder,
+    setSignalFilter,
+    setEmissionValidator,
   };
 }

package/src/router/role-resolver.ts

@@ -31,6 +31,11 @@ export interface RoleAgentInfo {
 export interface RoleAgentSource {
   listAgents(): RoleAgentInfo[];
   getAgent(agentId: AgentId): RoleAgentInfo | null;
+  /**
+   * Optional: Get agents subscribed to a scope/topic.
+   * Used when filtering by scope membership.
+   */
+  getScopeMembers?(scope: string): AgentId[];
 }
 
 // =============================================================================
@@ -90,8 +95,12 @@ export function getSubtreeIds(
 /**
  * Resolve a role channel to recipient agent IDs.
  *
+ * Supports two filtering mechanisms (can be combined):
+ * - coordinatorId: Filter to agents within a coordinator's subtree (hierarchy-based)
+ * - scope: Filter to agents that are members of a scope (subscription-based)
+ *
  * @param agentSource - Source for listing/getting agents
- * @param target - Role target with role name and optional coordinator scope
+ * @param target - Role target with role name and optional filters
  * @returns Array of agent IDs for fan-out delivery
  */
 export function resolveRoleTarget(
@@ -106,6 +115,13 @@ export function resolveRoleTarget(
     subtreeIds = getSubtreeIds(target.coordinatorId, agentSource);
   }
 
+  // Get scope member IDs if scope filtering is requested
+  let scopeMemberIds: Set<AgentId> | null = null;
+  if (target.scope && agentSource.getScopeMembers) {
+    const members = agentSource.getScopeMembers(target.scope);
+    scopeMemberIds = new Set(members);
+  }
+
   return agents
     .filter((agent) => {
       // Only include running agents
@@ -123,6 +139,11 @@ export function resolveRoleTarget(
         return false;
       }
 
+      // If scope filtering, check if agent is a scope member
+      if (scopeMemberIds && !scopeMemberIds.has(agent.id)) {
+        return false;
+      }
+
       return true;
     })
     .map((agent) => agent.id);

package/src/router/types.ts

@@ -39,8 +39,16 @@ export type BroadcastScope = "all" | "coordinators" | "workers" | "monitors";
 export interface RoleTarget {
   /** Role name to target (e.g., "worker", "integrator", "monitor") */
   role: string;
-  /** Optional: scope to specific coordinator's agents */
+  /**
+   * Optional: Filter to agents within a coordinator's subtree (hierarchy-based).
+   * Agents must be descendants of the specified coordinator.
+   */
   coordinatorId?: AgentId;
+  /**
+   * Optional: Filter to agents that are members of a scope (subscription-based).
+   * Requires EventStore scope/topic membership lookup.
+   */
+  scope?: string;
 }
 
 // Message sender identification
@@ -266,6 +274,33 @@ export class AddressRoutingError extends Error {
   }
 }
 
+// =============================================================================
+// Turn Recording
+// =============================================================================
+
+/**
+ * Information passed to a turn recorder callback.
+ * Only agent and task addresses produce turns.
+ */
+export interface TurnRecordInfo {
+  /** Sending agent ID */
+  from: AgentId;
+  /** Receiving agent ID (resolved for task addresses) */
+  toAgent: AgentId;
+  /** Message content */
+  content: string;
+  /** Event ID of the emitted message event */
+  messageId: EventId;
+  /** Type of address that was sent to */
+  addressType: "agent" | "task";
+}
+
+/**
+ * Callback invoked when a direct message (agent or task address) is sent.
+ * Used to record the message as a conversation turn.
+ */
+export type TurnRecorderCallback = (info: TurnRecordInfo) => void;
+
 // Re-export Address and related types for convenience
 export type { Address, SendOptions, DeliveryHint };
 export { MAPMessagePriority };

package/src/server/combined-server.ts

@@ -31,6 +31,9 @@ import {
 } from "../map/adapter/index.js";
 import type { Agent, AgentId } from "../store/types/index.js";
 import type { Address, SendOptions } from "../map/types.js";
+import { createMailService, type MailService } from "../mail/mail-service.js";
+import { createConversationMap, type ConversationMap } from "../mail/conversation-map.js";
+import { createTurnRecorder } from "../mail/turn-recorder.js";
 
 // ─────────────────────────────────────────────────────────────────
 // Types
@@ -91,6 +94,12 @@ export interface CombinedServer {
 
   /** MAP adapter (for testing) */
   readonly mapAdapter?: MAPAdapter;
+
+  /** Mail service (for conversation tracking) */
+  readonly mailService?: MailService;
+
+  /** Conversation map (for agent-to-conversation tracking) */
+  readonly conversationMap?: ConversationMap;
 }
 
 // ─────────────────────────────────────────────────────────────────
@@ -179,8 +188,30 @@ export function createCombinedServer(
     disableMap = false,
   } = config;
 
-  // Create Express app with API routes
-  const app = createAPIApp(services, { cors });
+  // Set up mail service and conversation map (always created, independent of MAP)
+  const mailService = createMailService({ eventStore: services.eventStore });
+  const conversationMap = createConversationMap();
+
+  // Wire mail services into AgentManager for conversation lifecycle
+  if (services.agentManager.setMailServices) {
+    services.agentManager.setMailServices(mailService, conversationMap);
+  }
+
+  // Wire turn recorder into MessageRouter for automatic turn tracking
+  if (services.messageRouter.setTurnRecorder) {
+    const turnRecorder = createTurnRecorder({
+      mailService,
+      conversationMap,
+      eventStore: services.eventStore,
+    });
+    services.messageRouter.setTurnRecorder(turnRecorder);
+  }
+
+  // Create Express app with API routes (include mail services)
+  const app = createAPIApp(
+    { ...services, mailService, conversationMap },
+    { cors }
+  );
 
   // Create HTTP server with Express
   const httpServer = http.createServer(app);
@@ -203,6 +234,7 @@ export function createCombinedServer(
     const mapServices = {
       ...createMAPServices(services),
       defaultCwd,
+      mailService,
     };
     mapAdapter = createMAPAdapter(
       { name: "macro-agent", version: "1.0.0" },
@@ -326,5 +358,7 @@ export function createCombinedServer(
     httpServer,
     app,
     mapAdapter,
+    mailService,
+    conversationMap,
   };
 }