macro-agent 0.0.10 → 0.0.12

package/src/mail/stores/eventstore-turn-store.ts

@@ -0,0 +1,173 @@
+/**
+ * EventStore-backed TurnStore adapter.
+ *
+ * Implements the MAP-compatible TurnStore interface by:
+ * - append() → emits a `turn` event with action `recorded`
+ * - get()/list() → reads from EventStore materialized views
+ * - count() → counts turns in materialized view
+ *
+ * Supports cursor-based pagination and timestamp range queries
+ * by post-filtering EventStore results.
+ */
+
+import type { EventStore } from "../../store/event-store.js";
+import type { TurnStore, ServerTurn, MAPTurnFilter } from "./types.js";
+import type { ConversationTurn, TurnFilter } from "../../store/types/index.js";
+
+/**
+ * Convert internal ConversationTurn to MAP ServerTurn.
+ */
+function toServerTurn(turn: ConversationTurn): ServerTurn {
+  return {
+    id: turn.id,
+    conversationId: turn.conversationId,
+    participant: turn.participant,
+    timestamp: turn.timestamp,
+    contentType: turn.contentType,
+    content: turn.content,
+    threadId: turn.threadId,
+    inReplyTo: turn.inReplyTo,
+    source:
+      turn.sourceType === "intercepted" && turn.sourceMessageId
+        ? { type: "intercepted", messageId: turn.sourceMessageId }
+        : { type: "explicit", method: "mail/turn" },
+    metadata: turn.metadata ?? {},
+  };
+}
+
+export class EventStoreTurnStore implements TurnStore {
+  constructor(private readonly eventStore: EventStore) {}
+
+  /**
+   * Append a turn by emitting a turn event.
+   */
+  append(turn: ServerTurn): void {
+    this.eventStore.emit({
+      type: "turn",
+      source: { agent_id: turn.participant },
+      payload: {
+        action: "recorded",
+        turn_id: turn.id,
+        conversation_id: turn.conversationId,
+        participant: turn.participant,
+        content_type: turn.contentType,
+        content: turn.content,
+        thread_id: turn.threadId,
+        in_reply_to: turn.inReplyTo,
+        source_type: turn.source.type,
+        source_message_id:
+          turn.source.type === "intercepted"
+            ? turn.source.messageId
+            : undefined,
+        metadata: turn.metadata,
+      },
+    });
+  }
+
+  /**
+   * Get a specific turn by ID.
+   * Searches across all conversations since we only have the turn ID.
+   */
+  get(id: string): ServerTurn | undefined {
+    // EventStore's listTurns requires a conversationId.
+    // For ID-based lookup, we scan all turns. In practice this is
+    // called rarely — most access is via list() with a conversationId.
+    //
+    // A more efficient approach would be adding a getTurn(id) method
+    // to EventStore, but for now this works with the existing interface.
+    const allConvIds = this.eventStore
+      .listConversations()
+      .map((c) => c.id);
+
+    for (const convId of allConvIds) {
+      const turns = this.eventStore.listTurns({ conversationId: convId });
+      const turn = turns.find((t) => t.id === id);
+      if (turn) return toServerTurn(turn);
+    }
+
+    return undefined;
+  }
+
+  /**
+   * List turns matching filter criteria with pagination.
+   */
+  list(filter: MAPTurnFilter): ServerTurn[] {
+    // Get all turns for the conversation with basic filters
+    const internalFilter: TurnFilter = {
+      conversationId: filter.conversationId,
+      threadId: filter.threadId,
+      contentType: filter.contentTypes?.[0],
+      participantId: filter.participantId,
+      order: filter.order,
+    };
+
+    let turns = this.eventStore
+      .listTurns(internalFilter)
+      .map(toServerTurn);
+
+    // Apply multi-value content type filter
+    if (filter.contentTypes && filter.contentTypes.length > 1) {
+      turns = turns.filter((t) =>
+        filter.contentTypes!.includes(t.contentType)
+      );
+    }
+
+    // Apply timestamp range filters
+    if (filter.afterTimestamp !== undefined) {
+      turns = turns.filter((t) => t.timestamp > filter.afterTimestamp!);
+    }
+    if (filter.beforeTimestamp !== undefined) {
+      turns = turns.filter((t) => t.timestamp < filter.beforeTimestamp!);
+    }
+
+    // Apply cursor-based pagination
+    if (filter.afterTurnId) {
+      const idx = turns.findIndex((t) => t.id === filter.afterTurnId);
+      if (idx !== -1) {
+        turns = turns.slice(idx + 1);
+      }
+    }
+    if (filter.beforeTurnId) {
+      const idx = turns.findIndex((t) => t.id === filter.beforeTurnId);
+      if (idx !== -1) {
+        turns = turns.slice(0, idx);
+      }
+    }
+
+    // Apply limit
+    if (filter.limit !== undefined) {
+      turns = turns.slice(0, filter.limit);
+    }
+
+    return turns;
+  }
+
+  /**
+   * Delete a specific turn. Not supported — EventStore is append-only.
+   */
+  delete(_id: string): boolean {
+    return false;
+  }
+
+  /**
+   * Delete all turns for a conversation. Not supported.
+   */
+  deleteByConversation(_conversationId: string): number {
+    return 0;
+  }
+
+  /**
+   * Count turns in a conversation.
+   */
+  count(conversationId: string, threadId?: string): number {
+    const filter: TurnFilter = { conversationId, threadId };
+    return this.eventStore.listTurns(filter).length;
+  }
+
+  /**
+   * Clear all turns. Not supported — EventStore is append-only.
+   */
+  clear(): void {
+    // No-op
+  }
+}

package/src/mail/stores/index.ts

@@ -0,0 +1,12 @@
+/**
+ * EventStore-backed mail store adapters.
+ *
+ * These implement MAP-compatible store interfaces backed by
+ * the EventStore's append-only event log and materialized views.
+ */
+
+export * from "./types.js";
+export { EventStoreConversationStore } from "./eventstore-conversation-store.js";
+export { EventStoreTurnStore } from "./eventstore-turn-store.js";
+export { EventStoreThreadStore } from "./eventstore-thread-store.js";
+export { EventStoreParticipantStore } from "./eventstore-participant-store.js";

package/src/mail/stores/types.ts

@@ -0,0 +1,160 @@
+/**
+ * MAP-compatible store interfaces for mail.
+ *
+ * These mirror the store interfaces from the MAP SDK server module
+ * (ConversationStore, TurnStore, ThreadStore, ParticipantStore) so that
+ * our EventStore-backed implementations can be plugged into MAP handlers.
+ *
+ * The MAP SDK server module is not exported from the installed package,
+ * so we define the interfaces locally. They match the SDK's shapes so
+ * swapping to SDK imports is a single-line change per type.
+ */
+
+// =============================================================================
+// Server-side record types (match MAP SDK ServerConversation, etc.)
+// =============================================================================
+
+export interface ServerConversation {
+  id: string;
+  type: string;
+  status: string;
+  subject?: string;
+  participantCount: number;
+  parentConversationId?: string;
+  parentTurnId?: string;
+  createdAt: number;
+  updatedAt: number;
+  closedAt?: number;
+  createdBy: string;
+  metadata: Record<string, unknown>;
+}
+
+export interface ServerParticipant {
+  id: string;
+  conversationId: string;
+  type: "user" | "agent" | "system";
+  role: string;
+  joinedAt: number;
+  leftAt?: number;
+  permissions: {
+    canSend: boolean;
+    canObserve: boolean;
+    canInvite: boolean;
+    canRemove: boolean;
+    canCreateThreads: boolean;
+    historyAccess: "none" | "from-join" | "full";
+    canSeeInternal: boolean;
+  };
+  agentInfo?: {
+    agentId: string;
+    name?: string;
+    role?: string;
+  };
+}
+
+export interface ServerTurn {
+  id: string;
+  conversationId: string;
+  participant: string;
+  timestamp: number;
+  contentType: string;
+  content: unknown;
+  threadId?: string;
+  inReplyTo?: string;
+  source: { type: "explicit"; method: "mail/turn" } | { type: "intercepted"; messageId: string };
+  visibility?: { type: string; [key: string]: unknown };
+  status?: string;
+  metadata: Record<string, unknown>;
+}
+
+export interface ServerThread {
+  id: string;
+  conversationId: string;
+  parentThreadId?: string;
+  subject?: string;
+  rootTurnId: string;
+  turnCount: number;
+  participantCount: number;
+  createdAt: number;
+  updatedAt: number;
+  createdBy: string;
+}
+
+// =============================================================================
+// Filter types (match MAP SDK ConversationFilter, TurnFilter, etc.)
+// =============================================================================
+
+export interface MAPConversationFilter {
+  type?: string[];
+  status?: string[];
+  participantId?: string;
+  createdAfter?: number;
+  createdBefore?: number;
+  parentConversationId?: string;
+}
+
+export interface MAPTurnFilter {
+  conversationId: string;
+  threadId?: string;
+  contentTypes?: string[];
+  participantId?: string;
+  afterTurnId?: string;
+  beforeTurnId?: string;
+  afterTimestamp?: number;
+  beforeTimestamp?: number;
+  limit?: number;
+  order?: "asc" | "desc";
+}
+
+export interface MAPThreadFilter {
+  conversationId: string;
+  parentThreadId?: string;
+}
+
+export interface MAPParticipantFilter {
+  conversationId?: string;
+  participantId?: string;
+  role?: string;
+  active?: boolean;
+}
+
+// =============================================================================
+// Store interfaces (match MAP SDK ConversationStore, TurnStore, etc.)
+// =============================================================================
+
+export interface ConversationStore {
+  save(conversation: ServerConversation): void;
+  get(id: string): ServerConversation | undefined;
+  list(filter?: MAPConversationFilter): ServerConversation[];
+  delete(id: string): boolean;
+  clear(): void;
+}
+
+export interface TurnStore {
+  append(turn: ServerTurn): void;
+  get(id: string): ServerTurn | undefined;
+  list(filter: MAPTurnFilter): ServerTurn[];
+  delete(id: string): boolean;
+  deleteByConversation(conversationId: string): number;
+  count(conversationId: string, threadId?: string): number;
+  clear(): void;
+}
+
+export interface ThreadStore {
+  save(thread: ServerThread): void;
+  get(id: string): ServerThread | undefined;
+  list(filter: MAPThreadFilter): ServerThread[];
+  delete(id: string): boolean;
+  deleteByConversation(conversationId: string): number;
+  clear(): void;
+}
+
+export interface ParticipantStore {
+  save(participant: ServerParticipant): void;
+  get(conversationId: string, participantId: string): ServerParticipant | undefined;
+  list(filter: MAPParticipantFilter): ServerParticipant[];
+  delete(conversationId: string, participantId: string): boolean;
+  deleteByConversation(conversationId: string): number;
+  getConversationsForParticipant(participantId: string, active?: boolean): string[];
+  clear(): void;
+}

package/src/mail/turn-recorder.ts

@@ -0,0 +1,124 @@
+/**
+ * TurnRecorder — Hierarchy-aware conversation resolution and turn recording.
+ *
+ * Resolves which conversation a message belongs to based on the
+ * relationship between sender and receiver:
+ * - Parent→child or child→parent: child's task conversation
+ * - Peers (no parent/child relationship): auto-created peer conversation
+ *
+ * @module mail/turn-recorder
+ */
+
+import type { AgentId } from "../store/types/index.js";
+import type { EventStore } from "../store/event-store.js";
+import type { MailService } from "./mail-service.js";
+import type { ConversationMap } from "./conversation-map.js";
+import type { TurnRecordInfo, TurnRecorderCallback } from "../router/types.js";
+
+export interface TurnRecorderDeps {
+  mailService: MailService;
+  conversationMap: ConversationMap;
+  eventStore: EventStore;
+}
+
+/**
+ * Create a TurnRecorderCallback for use with MessageRouter.setTurnRecorder().
+ *
+ * Resolution algorithm:
+ * 1. Get both agents from EventStore
+ * 2. If parent→child or child→parent: use child's task conversation
+ * 3. If peers: getOrCreatePeerConversation()
+ * 4. Record turn with sourceType: 'intercepted'
+ */
+export function createTurnRecorder(deps: TurnRecorderDeps): TurnRecorderCallback {
+  const { mailService, conversationMap, eventStore } = deps;
+
+  return (info: TurnRecordInfo): void => {
+    const { from, toAgent, content, messageId } = info;
+
+    // Resolve conversation based on agent relationship
+    const conversationId = resolveConversation(from, toAgent);
+    if (!conversationId) return;
+
+    // Record the turn — never fail core message routing
+    try {
+      mailService.recordTurn({
+        conversationId,
+        participant: from,
+        contentType: "text",
+        content,
+        sourceType: "intercepted",
+        sourceMessageId: messageId,
+      });
+    } catch (err) {
+      console.warn(`[TurnRecorder] Failed to record turn: ${err}`);
+    }
+  };
+
+  /**
+   * Find the nearest common ancestor of two agents and return its conversation ID.
+   * Lineage arrays are ordered root-to-parent: [grandparent, parent].
+   */
+  function findNearestCommonAncestorConversation(
+    lineageA: AgentId[],
+    lineageB: AgentId[]
+  ): string | undefined {
+    // Walk lineages from the end (nearest ancestor) to find the deepest shared ancestor
+    const setB = new Set(lineageB);
+    for (let i = lineageA.length - 1; i >= 0; i--) {
+      if (setB.has(lineageA[i])) {
+        // Found nearest common ancestor — look up its conversation
+        return (
+          conversationMap.getAgentConversation(lineageA[i]) ??
+          conversationMap.getSessionConversation(lineageA[i])
+        );
+      }
+    }
+    return undefined;
+  }
+
+  function resolveConversation(from: AgentId, to: AgentId): string | null {
+    const fromAgent = eventStore.getAgent(from);
+    const toAgent = eventStore.getAgent(to);
+
+    // If either agent doesn't exist, skip
+    if (!fromAgent || !toAgent) return null;
+
+    // Check parent→child relationship
+    if (fromAgent.parent === to) {
+      // from is a child of to — use from's task conversation
+      return conversationMap.getAgentConversation(from) ?? null;
+    }
+    if (toAgent.parent === from) {
+      // to is a child of from — use to's task conversation
+      return conversationMap.getAgentConversation(to) ?? null;
+    }
+
+    // Peers — get or create peer conversation
+    return conversationMap.getOrCreatePeerConversation(from, to, () => {
+      // Find nearest common ancestor's conversation for tree structure
+      const parentConversationId = findNearestCommonAncestorConversation(
+        fromAgent.lineage,
+        toAgent.lineage
+      );
+
+      const { conversationId } = mailService.createConversation({
+        type: "peer",
+        subject: `Peer: ${from} ↔ ${to}`,
+        createdBy: from,
+        parentConversationId,
+      });
+      mailService.joinConversation({
+        conversationId,
+        participantId: from,
+        role: "worker",
+      });
+      mailService.joinConversation({
+        conversationId,
+        participantId: to,
+        role: "worker",
+      });
+      return conversationId;
+    });
+  }
+}

package/src/map/README.md

@@ -0,0 +1,79 @@
+# MAP Integration Module
+
+Multi-Agent Protocol (MAP) integration for macro-agent, enabling standardized communication with external clients, agents, and gateways.
+
+## Architecture
+
+```
+External Clients → MAPAdapter → MessageRouter → EventStore
+(MAP protocol)     (translation)  (routing)      (persistence)
+```
+
+## Components
+
+### Core Types (`types.ts`)
+
+Defines MAP-compliant address types for message routing:
+
+- **AgentAddress** - `{ agent: AgentId }` - Direct to agent
+- **AgentsAddress** - `{ agents: AgentId[] }` - Multi-agent delivery
+- **TaskAddress** - `{ task: TaskId }` - Route to assigned agent
+- **ScopeAddress** - `{ scope: ScopeId }` - Scope-based pub/sub
+- **RoleAddress** - `{ role: string, within?: ScopeId }` - Role-based fan-out
+- **BroadcastAddress** - `{ broadcast: scope }` - System-wide broadcast
+- **HierarchicalAddress** - Parent/children/ancestors/descendants/siblings
+- **FederatedAddress** - Cross-system routing
+
+### Adapter (`adapter/`)
+
+The `MAPAdapter` handles external connections:
+
+- **Connection Management** - Accept/disconnect participants
+- **Authentication** - Validate credentials, assign capabilities
+- **RPC Handling** - JSON-RPC 2.0 request/response
+- **Subscriptions** - Event streaming to participants
+- **Extensions** - Pluggable method handlers (spawn, wake, tasks)
+
+Key files:
+- `map-adapter.ts` - Core adapter implementation
+- `connection-manager.ts` - Participant lifecycle
+- `subscription-manager.ts` - Event subscriptions
+- `rpc-handler.ts` - JSON-RPC processing
+- `extensions/` - Extension method handlers
+
+### Federation (`federation/`)
+
+Cross-system communication:
+
+- **FederationHandler** - Routes messages between MAP systems
+- **PeerManager** - Manages connections to peer systems
+- **SystemId** - Unique system identification (domain/system/instance)
+
+## Usage
+
+```typescript
+import { createMAPAdapter } from "./map/adapter/index.js";
+
+const adapter = createMAPAdapter({
+  name: "my-system",
+  authenticate: async (type, credentials) => {
+    // Validate credentials
+    return { allowed: true, capabilities: { canQuery: true } };
+  },
+});
+
+await adapter.start();
+
+// Accept WebSocket connection
+const participant = await adapter.acceptConnection(stream);
+```
+
+## ID Naming Convention
+
+MAP types use clean field names (`agent`, `task`) while internal types use explicit names (`agent_id`, `task_id`). See CLAUDE.md for details.
+
+## Related Modules
+
+- `router/` - Internal message routing (MessageRouter)
+- `store/` - Event persistence (EventStore)
+- `trigger/` - External event routing (TriggerRouter)