macro-agent 0.0.11 → 0.0.12

package/src/router/message-router.ts

@@ -204,8 +204,61 @@ export interface MessageRouter {
    * 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
  */
@@ -264,6 +317,12 @@ export function createMessageRouter(
   // 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>>();
 
@@ -929,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",
@@ -943,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);
   }
 
   // ─────────────────────────────────────────────────────────────────
@@ -1088,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:
@@ -1128,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,
@@ -1151,6 +1255,109 @@ 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
+        }
+      }
     }
   }
 
@@ -1158,6 +1365,14 @@ export function createMessageRouter(
     turnRecorder = recorder;
   }
 
+  function setSignalFilter(filter: SignalFilter): void {
+    signalFilter = filter;
+  }
+
+  function setEmissionValidator(validator: EmissionValidator): void {
+    emissionValidator = validator;
+  }
+
   return {
     sendToAddress,
     emitStatus,
@@ -1171,5 +1386,7 @@ export function createMessageRouter(
     getSubscribers,
     setupDefaultSubscriptions,
     setTurnRecorder,
+    setSignalFilter,
+    setEmissionValidator,
   };
 }

package/src/store/event-store.ts

@@ -42,6 +42,8 @@ import type {
   TurnChangeCallback,
   ConversationType,
   ConversationStatus,
+  Session,
+  SessionState,
 } from './types/index.js';
 import { CURRENT_EVENT_VERSION } from './types/events.js';
 import { migrateEvent } from './migrations.js';
@@ -102,6 +104,7 @@ function createBetterSqlite3Persister(
 export type AgentChangeCallback = (agentId: AgentId, agent: Agent | null) => void;
 export type TaskChangeCallback = (taskId: TaskId, task: Task | null) => void;
 export type MessageCallback = (agentId: AgentId, messages: QueuedMessage[]) => void;
+export type SessionChangeCallback = (sessionId: string, session: Session | null) => void;
 
 // Unsubscribe function type
 export type Unsubscribe = () => void;
@@ -173,6 +176,10 @@ export interface EventStore {
   getSubscriptions(agentId: AgentId): Subscription[];
   getSubscribers(subscription: Subscription): AgentId[];
 
+  // Session views
+  getSession(sessionId: string): Session | null;
+  listSessions(filter?: { state?: SessionState; agent_id?: AgentId }): Session[];
+
   // Conversation views
   getConversation(conversationId: string): Conversation | null;
   listConversations(filter?: ConversationFilter): Conversation[];
@@ -184,6 +191,7 @@ export interface EventStore {
   onAgentChange(agentId: AgentId, callback: AgentChangeCallback): Unsubscribe;
   onTaskChange(callback: TaskChangeCallback): Unsubscribe;
   onMessageChange(agentId: AgentId, callback: MessageCallback): Unsubscribe;
+  onSessionChange(callback: SessionChangeCallback): Unsubscribe;
   onConversationChange(callback: ConversationChangeCallback): Unsubscribe;
   onTurnChange(callback: TurnChangeCallback): Unsubscribe;
 
@@ -325,6 +333,7 @@ export async function createEventStore(config: StoreConfig = {}): Promise<EventS
   const agentListeners = new Set<AgentChangeCallback>();
   const agentIdListeners = new Map<AgentId, Set<AgentChangeCallback>>();
   const taskListeners = new Set<TaskChangeCallback>();
+  const sessionListeners = new Set<SessionChangeCallback>();
   const messageListeners = new Map<AgentId, Set<MessageCallback>>();
   const conversationListeners = new Set<ConversationChangeCallback>();
   const turnListeners = new Set<TurnChangeCallback>();
@@ -354,7 +363,7 @@ export async function createEventStore(config: StoreConfig = {}): Promise<EventS
     });
 
     // Update materialized views
-    applyEventToViews(store, event, notifyAgentChange, notifyTaskChange, notifyMessageChange, notifyConversationChange, notifyTurnChange);
+    applyEventToViews(store, event, notifyAgentChange, notifyTaskChange, notifyMessageChange, notifySessionChange, notifyConversationChange, notifyTurnChange);
 
     return event;
   }
@@ -694,6 +703,52 @@ export async function createEventStore(config: StoreConfig = {}): Promise<EventS
     return () => turnListeners.delete(callback);
   }
 
+  // ─── Session View Queries ───
+
+  function getSession(sessionId: string): Session | null {
+    const row = store.getRow('sessions', sessionId);
+    if (!row.id) return null;
+    return rowToSession(row);
+  }
+
+  function listSessions(filter?: { state?: SessionState; agent_id?: AgentId }): Session[] {
+    const sessions: Session[] = [];
+    const rowIds = store.getRowIds('sessions');
+
+    for (const rowId of rowIds) {
+      const row = store.getRow('sessions', rowId);
+      if (!row.id) continue;
+
+      const session = rowToSession(row);
+
+      if (filter) {
+        if (filter.state && session.state !== filter.state) continue;
+        if (filter.agent_id && session.current_agent_id !== filter.agent_id && session.head_manager_id !== filter.agent_id) continue;
+      }
+
+      sessions.push(session);
+    }
+
+    return sessions;
+  }
+
+  /**
+   * Notify session change listeners
+   */
+  function notifySessionChange(sessionId: string, session: Session | null): void {
+    for (const callback of sessionListeners) {
+      callback(sessionId, session);
+    }
+  }
+
+  /**
+   * Subscribe to session changes
+   */
+  function onSessionChange(callback: SessionChangeCallback): Unsubscribe {
+    sessionListeners.add(callback);
+    return () => sessionListeners.delete(callback);
+  }
+
   // ─── Conversation View Queries ───
 
   function getConversation(conversationId: string): Conversation | null {
@@ -1048,7 +1103,7 @@ export async function createEventStore(config: StoreConfig = {}): Promise<EventS
       });
 
       // Update materialized views
-      applyEventToViews(store, event, notifyAgentChange, notifyTaskChange, notifyMessageChange, notifyConversationChange, notifyTurnChange);
+      applyEventToViews(store, event, notifyAgentChange, notifyTaskChange, notifyMessageChange, notifySessionChange, notifyConversationChange, notifyTurnChange);
     }
   }
 
@@ -1094,6 +1149,8 @@ export async function createEventStore(config: StoreConfig = {}): Promise<EventS
     listTasks,
     getMessages,
     getFullMessage,
+    getSession,
+    listSessions,
     getConversation,
     listConversations,
     listTurns,
@@ -1109,6 +1166,7 @@ export async function createEventStore(config: StoreConfig = {}): Promise<EventS
     onAgentChange,
     onTaskChange,
     onMessageChange,
+    onSessionChange,
     onConversationChange,
     onTurnChange,
 
@@ -1142,6 +1200,7 @@ function initializeTables(store: Store): void {
   store.getRowIds('tasks');
   store.getRowIds('messages');
   store.getRowIds('subscriptions');
+  store.getRowIds('sessions');
   store.getRowIds('conversations');
   store.getRowIds('turns');
   store.getRowIds('threads');
@@ -1162,6 +1221,9 @@ function rebuildViews(store: Store): void {
   for (const rowId of store.getRowIds('messages')) {
     store.delRow('messages', rowId);
   }
+  for (const rowId of store.getRowIds('sessions')) {
+    store.delRow('sessions', rowId);
+  }
   for (const rowId of store.getRowIds('conversations')) {
     store.delRow('conversations', rowId);
   }
@@ -1202,7 +1264,7 @@ function rebuildViews(store: Store): void {
   // Apply each event (no-op callbacks since we're rebuilding)
   const noop = () => {};
   for (const event of events) {
-    applyEventToViews(store, event, noop, noop, noop, noop, noop);
+    applyEventToViews(store, event, noop, noop, noop, noop, noop, noop);
   }
 }
 
@@ -1215,6 +1277,7 @@ function applyEventToViews(
   notifyAgentChange: (agentId: AgentId, agent: Agent | null) => void,
   notifyTaskChange: (taskId: TaskId, task: Task | null) => void,
   notifyMessageChange: (agentId: AgentId) => void,
+  notifySessionChange: (sessionId: string, session: Session | null) => void,
   notifyConversationChange: (conversationId: string, conversation: Conversation | null) => void,
   notifyTurnChange: (conversationId: string, turn: ConversationTurn) => void,
 ): void {
@@ -1234,6 +1297,9 @@ function applyEventToViews(
     case 'task':
       applyTaskEvent(store, event, notifyTaskChange);
       break;
+    case 'session':
+      applySessionEvent(store, event, notifySessionChange);
+      break;
     case 'conversation':
       applyConversationEvent(store, event, notifyConversationChange);
       break;
@@ -1671,6 +1737,88 @@ function rowToTask(row: Record<string, unknown>): Task {
   };
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Session Event Handlers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Apply session event to sessions view
+ */
+function applySessionEvent(
+  store: Store,
+  event: Event,
+  notify: (sessionId: string, session: Session | null) => void,
+): void {
+  const payload = event.payload as {
+    action: string;
+    session_id: string;
+    head_manager_id?: AgentId;
+    agent_id?: AgentId;
+    target_agent_id?: AgentId;
+    previous_agent_id?: AgentId;
+  };
+
+  const sessionId = payload.session_id;
+
+  switch (payload.action) {
+    case 'created': {
+      store.setRow('sessions', sessionId, {
+        id: sessionId,
+        head_manager_id: payload.head_manager_id ?? '',
+        current_agent_id: payload.head_manager_id ?? '',
+        state: 'active',
+        created_at: event.timestamp,
+        updated_at: event.timestamp,
+        closed_at: 0,
+      });
+      break;
+    }
+    case 'mounted': {
+      store.setPartialRow('sessions', sessionId, {
+        current_agent_id: payload.target_agent_id ?? '',
+        state: 'mounted',
+        updated_at: event.timestamp,
+      });
+      break;
+    }
+    case 'unmounted': {
+      const existing = store.getRow('sessions', sessionId);
+      store.setPartialRow('sessions', sessionId, {
+        current_agent_id: existing.head_manager_id as string,
+        state: 'active',
+        updated_at: event.timestamp,
+      });
+      break;
+    }
+    case 'closed': {
+      store.setPartialRow('sessions', sessionId, {
+        state: 'closed',
+        updated_at: event.timestamp,
+        closed_at: event.timestamp,
+      });
+      break;
+    }
+  }
+
+  const session = rowToSession(store.getRow('sessions', sessionId));
+  notify(sessionId, session);
+}
+
+/**
+ * Convert a TinyBase row to a Session object
+ */
+function rowToSession(row: Record<string, unknown>): Session {
+  return {
+    id: row.id as string,
+    head_manager_id: row.head_manager_id as AgentId,
+    current_agent_id: row.current_agent_id as AgentId,
+    state: row.state as SessionState,
+    created_at: row.created_at as Timestamp,
+    updated_at: row.updated_at as Timestamp,
+    closed_at: (row.closed_at as number) || undefined,
+  };
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Conversation Event Handlers
 // ─────────────────────────────────────────────────────────────────────────────

package/src/store/types/agents.ts

@@ -5,7 +5,7 @@
 import type { AgentId, SessionId, TaskId, Timestamp } from "./primitives.js";
 
 // Agent states
-export type AgentState = "spawning" | "running" | "stopped";
+export type AgentState = "spawning" | "running" | "stopped" | "failed";
 
 export type StopReason =
   | "completed"

package/src/store/types/events.ts

@@ -20,7 +20,8 @@ export type EventType =
   | "peer_request"
   | "conversation"
   | "turn"
-  | "thread";
+  | "thread"
+  | "session";
 
 // Status types for status events
 export type StatusType =

package/src/store/types/index.ts

@@ -9,3 +9,4 @@ export * from "./tasks.js";
 export * from "./messages.js";
 export * from "./config.js";
 export * from "./conversations.js";
+export * from "./sessions.js";

package/src/store/types/sessions.ts

@@ -0,0 +1,53 @@
+/**
+ * Session-related type definitions
+ *
+ * Sessions track the mapping between ACP protocol sessions and
+ * macro-agent agents. Unlike the in-memory SessionMapper, these
+ * records are persisted in the EventStore for recovery after restart.
+ */
+
+import type { AgentId, Timestamp } from "./primitives.js";
+
+/**
+ * Session state enum — tracks the lifecycle of an ACP session.
+ *
+ * State transitions:
+ *   active → mounted → active (via unmount)
+ *   active → closed
+ *   mounted → closed
+ */
+export type SessionState = "active" | "mounted" | "closed";
+
+/**
+ * Persistent session record in the EventStore materialized view.
+ *
+ * Maps an ACP session ID to its head manager agent, current agent
+ * target (which may differ when mounted), and lifecycle state.
+ */
+export interface Session {
+  /** ACP session ID (primary key) */
+  id: string;
+
+  /** Head manager agent ID — the original agent for this session */
+  head_manager_id: AgentId;
+
+  /** Currently targeted agent ID (may differ from head_manager_id when mounted) */
+  current_agent_id: AgentId;
+
+  /** Current session state */
+  state: SessionState;
+
+  /** When the session was created */
+  created_at: Timestamp;
+
+  /** When the session state last changed */
+  updated_at: Timestamp;
+
+  /** When the session was closed (if applicable) */
+  closed_at?: Timestamp;
+}
+
+/**
+ * Session event actions used in the event payload.
+ */
+export type SessionAction = "created" | "mounted" | "unmounted" | "closed";

package/src/store/types/tasks.ts

@@ -118,4 +118,7 @@ export interface Task {
 
   /** Current retry state */
   retryState?: RetryState;
+
+  /** Tags for task classification and filtering (used by pull model) */
+  tags?: string[];
 }