macro-agent 0.0.10 → 0.0.12

package/src/mail/mail-service.ts

@@ -0,0 +1,257 @@
+/**
+ * MailService — Central facade for mail conversation tracking.
+ *
+ * Provides conversation lifecycle management, turn recording,
+ * and participant tracking backed by EventStore materialized views.
+ *
+ * Since the MAP SDK server module is not importable, this implements
+ * the business logic directly rather than delegating to SDK managers.
+ */
+
+import { nanoid } from "nanoid";
+import type { EventStore } from "../store/event-store.js";
+import type {
+  Conversation,
+  ConversationTurn,
+  ConversationParticipant,
+  ConversationFilter,
+  TurnFilter,
+  ConversationType,
+  ConversationStatus,
+  ConversationChangeCallback,
+  TurnChangeCallback,
+} from "../store/types/index.js";
+import type { Unsubscribe } from "../store/event-store.js";
+import {
+  EventStoreConversationStore,
+  EventStoreTurnStore,
+  EventStoreThreadStore,
+  EventStoreParticipantStore,
+  type ConversationStore,
+  type TurnStore,
+  type ThreadStore,
+  type ParticipantStore,
+} from "./stores/index.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface CreateConversationOptions {
+  type: ConversationType;
+  subject?: string;
+  createdBy: string;
+  parentConversationId?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface RecordTurnOptions {
+  conversationId: string;
+  participant: string;
+  contentType: string;
+  content: unknown;
+  threadId?: string;
+  inReplyTo?: string;
+  sourceType?: "explicit" | "intercepted";
+  sourceMessageId?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface CloseConversationOptions {
+  conversationId: string;
+  closedBy: string;
+  reason?: string;
+}
+
+export interface JoinConversationOptions {
+  conversationId: string;
+  participantId: string;
+  participantType?: "user" | "agent" | "system";
+  role?: string;
+  agentId?: string;
+}
+
+export interface MailServiceConfig {
+  eventStore: EventStore;
+}
+
+// =============================================================================
+// MailService Interface
+// =============================================================================
+
+export interface MailService {
+  /** Create a new conversation. */
+  createConversation(opts: CreateConversationOptions): { conversationId: string };
+
+  /** Record a turn in a conversation. */
+  recordTurn(opts: RecordTurnOptions): { turnId: string };
+
+  /** Close a conversation. */
+  closeConversation(opts: CloseConversationOptions): void;
+
+  /** Join a participant to a conversation. */
+  joinConversation(opts: JoinConversationOptions): void;
+
+  /** Remove a participant from a conversation. */
+  leaveConversation(conversationId: string, participantId: string): void;
+
+  /** Get a conversation by ID. */
+  getConversation(id: string): Conversation | null;
+
+  /** List conversations with optional filter. */
+  listConversations(filter?: ConversationFilter): Conversation[];
+
+  /** List turns for a conversation. */
+  listTurns(filter: TurnFilter): ConversationTurn[];
+
+  /** List participants for a conversation. */
+  listParticipants(conversationId: string, active?: boolean): ConversationParticipant[];
+
+  /** Count turns in a conversation. */
+  countTurns(conversationId: string, threadId?: string): number;
+
+  /** Subscribe to conversation changes. */
+  onConversationChange(callback: ConversationChangeCallback): Unsubscribe;
+
+  /** Subscribe to turn changes. */
+  onTurnChange(callback: TurnChangeCallback): Unsubscribe;
+
+  /** Access to underlying stores for MAP handler integration. */
+  readonly stores: {
+    conversations: ConversationStore;
+    turns: TurnStore;
+    threads: ThreadStore;
+    participants: ParticipantStore;
+  };
+}
+
+// =============================================================================
+// Implementation
+// =============================================================================
+
+export function createMailService(config: MailServiceConfig): MailService {
+  const { eventStore } = config;
+
+  // Create EventStore-backed stores
+  const conversationStore = new EventStoreConversationStore(eventStore);
+  const turnStore = new EventStoreTurnStore(eventStore);
+  const threadStore = new EventStoreThreadStore(eventStore);
+  const participantStore = new EventStoreParticipantStore(eventStore);
+
+  function createConversation(
+    opts: CreateConversationOptions
+  ): { conversationId: string } {
+    const conversationId = `conv_${nanoid(12)}`;
+
+    eventStore.emit({
+      type: "conversation",
+      source: { agent_id: opts.createdBy },
+      payload: {
+        action: "created",
+        conversation_id: conversationId,
+        conversation_type: opts.type,
+        subject: opts.subject,
+        parent_conversation_id: opts.parentConversationId,
+        metadata: opts.metadata,
+      },
+    });
+
+    return { conversationId };
+  }
+
+  function recordTurn(opts: RecordTurnOptions): { turnId: string } {
+    const conv = eventStore.getConversation(opts.conversationId);
+    if (!conv) {
+      throw new Error(`Cannot record turn: conversation not found: ${opts.conversationId}`);
+    }
+
+    const turnId = `turn_${nanoid(12)}`;
+
+    eventStore.emit({
+      type: "turn",
+      source: { agent_id: opts.participant },
+      payload: {
+        action: "recorded",
+        turn_id: turnId,
+        conversation_id: opts.conversationId,
+        participant: opts.participant,
+        content_type: opts.contentType,
+        content: opts.content,
+        thread_id: opts.threadId,
+        in_reply_to: opts.inReplyTo,
+        source_type: opts.sourceType ?? "explicit",
+        source_message_id: opts.sourceMessageId,
+        metadata: opts.metadata,
+      },
+    });
+
+    return { turnId };
+  }
+
+  function closeConversation(opts: CloseConversationOptions): void {
+    eventStore.emit({
+      type: "conversation",
+      source: { agent_id: opts.closedBy },
+      payload: {
+        action: "closed",
+        conversation_id: opts.conversationId,
+        closed_by: opts.closedBy,
+        close_reason: opts.reason ?? "completed",
+      },
+    });
+  }
+
+  function joinConversation(opts: JoinConversationOptions): void {
+    eventStore.emit({
+      type: "conversation",
+      source: { agent_id: opts.participantId },
+      payload: {
+        action: "participant_joined",
+        conversation_id: opts.conversationId,
+        participant_id: opts.participantId,
+        participant_type: opts.participantType ?? "agent",
+        participant_role: opts.role ?? "worker",
+        agent_id: opts.agentId,
+      },
+    });
+  }
+
+  function leaveConversation(
+    conversationId: string,
+    participantId: string
+  ): void {
+    eventStore.emit({
+      type: "conversation",
+      source: { agent_id: participantId },
+      payload: {
+        action: "participant_left",
+        conversation_id: conversationId,
+        participant_id: participantId,
+      },
+    });
+  }
+
+  return {
+    createConversation,
+    recordTurn,
+    closeConversation,
+    joinConversation,
+    leaveConversation,
+    getConversation: (id) => eventStore.getConversation(id),
+    listConversations: (filter) => eventStore.listConversations(filter),
+    listTurns: (filter) => eventStore.listTurns(filter),
+    listParticipants: (conversationId, active) =>
+      eventStore.listParticipants(conversationId, active),
+    countTurns: (conversationId, threadId) =>
+      turnStore.count(conversationId, threadId),
+    onConversationChange: (callback) =>
+      eventStore.onConversationChange(callback),
+    onTurnChange: (callback) => eventStore.onTurnChange(callback),
+    stores: {
+      conversations: conversationStore,
+      turns: turnStore,
+      threads: threadStore,
+      participants: participantStore,
+    },
+  };
+}

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

@@ -0,0 +1,146 @@
+/**
+ * EventStore-backed ConversationStore adapter.
+ *
+ * Implements the MAP-compatible ConversationStore interface by:
+ * - save() → emits a `conversation` event with action `created` or `updated`
+ * - get()/list() → reads from EventStore materialized views
+ * - delete() → not supported (conversations are closed, not deleted)
+ *
+ * All state is derived from the EventStore event log — this adapter
+ * is a thin translation layer between MAP server types and EventStore.
+ */
+
+import type { EventStore } from "../../store/event-store.js";
+import type {
+  ConversationStore,
+  ServerConversation,
+  MAPConversationFilter,
+} from "./types.js";
+import type { Conversation, ConversationFilter } from "../../store/types/index.js";
+
+/**
+ * Convert internal Conversation to MAP ServerConversation.
+ */
+function toServerConversation(conv: Conversation): ServerConversation {
+  return {
+    id: conv.id,
+    type: conv.type,
+    status: conv.status,
+    subject: conv.subject,
+    participantCount: conv.participantCount,
+    parentConversationId: conv.parentConversationId,
+    createdAt: conv.createdAt,
+    updatedAt: conv.updatedAt,
+    closedAt: conv.closedAt,
+    createdBy: conv.createdBy,
+    metadata: conv.metadata ?? {},
+  };
+}
+
+export class EventStoreConversationStore implements ConversationStore {
+  constructor(private readonly eventStore: EventStore) {}
+
+  /**
+   * Save a conversation by emitting a conversation event.
+   * If the conversation already exists, emits an update.
+   */
+  save(conversation: ServerConversation): void {
+    const existing = this.eventStore.getConversation(conversation.id);
+
+    if (existing) {
+      // Update: emit a conversation event with action "updated"
+      // For now we handle status changes (e.g., closing)
+      if (existing.status !== conversation.status && (conversation.status === "completed" || conversation.status === "failed")) {
+        this.eventStore.emit({
+          type: "conversation",
+          source: { agent_id: conversation.createdBy },
+          payload: {
+            action: "closed",
+            conversation_id: conversation.id,
+            closed_by: conversation.createdBy,
+            close_reason: conversation.status,
+          },
+        });
+      }
+    } else {
+      // Create: emit conversation created event
+      this.eventStore.emit({
+        type: "conversation",
+        source: { agent_id: conversation.createdBy },
+        payload: {
+          action: "created",
+          conversation_id: conversation.id,
+          conversation_type: conversation.type,
+          subject: conversation.subject,
+          parent_conversation_id: conversation.parentConversationId,
+          metadata: conversation.metadata,
+        },
+      });
+    }
+  }
+
+  /**
+   * Get a conversation by ID.
+   */
+  get(id: string): ServerConversation | undefined {
+    const conv = this.eventStore.getConversation(id);
+    return conv ? toServerConversation(conv) : undefined;
+  }
+
+  /**
+   * List conversations matching filter criteria.
+   */
+  list(filter?: MAPConversationFilter): ServerConversation[] {
+    // Translate MAP filter to internal filter
+    const internalFilter: ConversationFilter | undefined = filter
+      ? {
+          // MAP uses arrays for type/status, internal uses single values
+          // Use first value if provided
+          type: filter.type?.[0] as Conversation["type"] | undefined,
+          status: filter.status?.[0] as Conversation["status"] | undefined,
+          participantId: filter.participantId,
+          parentConversationId: filter.parentConversationId,
+        }
+      : undefined;
+
+    const conversations = this.eventStore.listConversations(internalFilter);
+
+    // Apply additional MAP-specific filters not in internal filter
+    let results = conversations.map(toServerConversation);
+
+    if (filter) {
+      // Multi-value type filter
+      if (filter.type && filter.type.length > 1) {
+        results = results.filter((c) => filter.type!.includes(c.type));
+      }
+      // Multi-value status filter
+      if (filter.status && filter.status.length > 1) {
+        results = results.filter((c) => filter.status!.includes(c.status));
+      }
+      // Timestamp range filters
+      if (filter.createdAfter !== undefined) {
+        results = results.filter((c) => c.createdAt > filter.createdAfter!);
+      }
+      if (filter.createdBefore !== undefined) {
+        results = results.filter((c) => c.createdAt < filter.createdBefore!);
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Delete a conversation. Not supported — conversations are closed, not deleted.
+   * Returns false as no deletion occurs.
+   */
+  delete(_id: string): boolean {
+    return false;
+  }
+
+  /**
+   * Clear all conversations. Not supported — EventStore is append-only.
+   */
+  clear(): void {
+    // No-op: EventStore is append-only, views are rebuilt on replay
+  }
+}

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

@@ -0,0 +1,172 @@
+/**
+ * EventStore-backed ParticipantStore adapter.
+ *
+ * Implements the MAP-compatible ParticipantStore interface by:
+ * - save() → emits conversation events with action `participant_joined`
+ * - get()/list() → reads from EventStore materialized views
+ * - Bidirectional lookup: conversation→participants and participant→conversations
+ */
+
+import type { EventStore } from "../../store/event-store.js";
+import type {
+  ParticipantStore,
+  ServerParticipant,
+  MAPParticipantFilter,
+} from "./types.js";
+import type { ConversationParticipant } from "../../store/types/index.js";
+
+/** Default permissions for participants. */
+const DEFAULT_PERMISSIONS: ServerParticipant["permissions"] = {
+  canSend: true,
+  canObserve: true,
+  canInvite: false,
+  canRemove: false,
+  canCreateThreads: true,
+  historyAccess: "full",
+  canSeeInternal: false,
+};
+
+/**
+ * Convert internal ConversationParticipant to MAP ServerParticipant.
+ */
+function toServerParticipant(p: ConversationParticipant): ServerParticipant {
+  return {
+    id: p.id,
+    conversationId: p.conversationId,
+    type: p.type,
+    role: p.role,
+    joinedAt: p.joinedAt,
+    leftAt: p.leftAt,
+    permissions: DEFAULT_PERMISSIONS,
+    agentInfo: p.agentId ? { agentId: p.agentId } : undefined,
+  };
+}
+
+export class EventStoreParticipantStore implements ParticipantStore {
+  constructor(private readonly eventStore: EventStore) {}
+
+  /**
+   * Save a participant by emitting a conversation participant_joined event.
+   */
+  save(participant: ServerParticipant): void {
+    this.eventStore.emit({
+      type: "conversation",
+      source: { agent_id: participant.id },
+      payload: {
+        action: "participant_joined",
+        conversation_id: participant.conversationId,
+        participant_id: participant.id,
+        participant_type: participant.type,
+        participant_role: participant.role,
+        agent_id: participant.agentInfo?.agentId,
+      },
+    });
+  }
+
+  /**
+   * Get a specific participant in a conversation.
+   */
+  get(
+    conversationId: string,
+    participantId: string
+  ): ServerParticipant | undefined {
+    const participants = this.eventStore.listParticipants(conversationId);
+    const found = participants.find((p) => p.id === participantId);
+    return found ? toServerParticipant(found) : undefined;
+  }
+
+  /**
+   * List participants matching filter criteria.
+   */
+  list(filter: MAPParticipantFilter): ServerParticipant[] {
+    if (filter.conversationId) {
+      const participants = this.eventStore
+        .listParticipants(filter.conversationId, filter.active)
+        .map(toServerParticipant);
+
+      return participants.filter((p) => {
+        if (filter.participantId && p.id !== filter.participantId) return false;
+        if (filter.role && p.role !== filter.role) return false;
+        return true;
+      });
+    }
+
+    // Without conversationId, we need to scan all conversations
+    if (filter.participantId) {
+      const convIds = this.getConversationsForParticipant(
+        filter.participantId,
+        filter.active
+      );
+      const results: ServerParticipant[] = [];
+      for (const convId of convIds) {
+        const participants = this.eventStore.listParticipants(convId);
+        const found = participants.find((p) => p.id === filter.participantId);
+        if (found) {
+          const sp = toServerParticipant(found);
+          if (!filter.role || sp.role === filter.role) {
+            results.push(sp);
+          }
+        }
+      }
+      return results;
+    }
+
+    // No conversationId and no participantId — return empty
+    // (listing all participants across all conversations is expensive and rarely needed)
+    return [];
+  }
+
+  /**
+   * Remove a participant from a conversation by emitting a participant_left event.
+   */
+  delete(conversationId: string, participantId: string): boolean {
+    const existing = this.get(conversationId, participantId);
+    if (!existing) return false;
+
+    this.eventStore.emit({
+      type: "conversation",
+      source: { agent_id: participantId },
+      payload: {
+        action: "participant_left",
+        conversation_id: conversationId,
+        participant_id: participantId,
+      },
+    });
+
+    return true;
+  }
+
+  /**
+   * Delete all participants for a conversation. Not supported.
+   */
+  deleteByConversation(_conversationId: string): number {
+    return 0;
+  }
+
+  /**
+   * Get all conversation IDs a participant belongs to.
+   */
+  getConversationsForParticipant(
+    participantId: string,
+    active?: boolean
+  ): string[] {
+    const conversations = this.eventStore.listConversations();
+    const result: string[] = [];
+
+    for (const conv of conversations) {
+      const participants = this.eventStore.listParticipants(conv.id, active);
+      if (participants.some((p) => p.id === participantId)) {
+        result.push(conv.id);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Clear all participants. Not supported — EventStore is append-only.
+   */
+  clear(): void {
+    // No-op
+  }
+}

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

@@ -0,0 +1,129 @@
+/**
+ * EventStore-backed ThreadStore adapter.
+ *
+ * Minimal implementation — threads are a secondary feature.
+ * Implements the MAP-compatible ThreadStore interface by:
+ * - save() → emits a `thread` event with action `created`
+ * - get()/list() → reads from EventStore materialized views
+ * - turnCount computed from actual turns with matching threadId
+ */
+
+import type { EventStore } from "../../store/event-store.js";
+import type { ThreadStore, ServerThread, MAPThreadFilter } from "./types.js";
+
+export class EventStoreThreadStore implements ThreadStore {
+  constructor(private readonly eventStore: EventStore) {}
+
+  /**
+   * Save a thread by emitting a thread event.
+   */
+  save(thread: ServerThread): void {
+    this.eventStore.emit({
+      type: "thread",
+      source: { agent_id: thread.createdBy },
+      payload: {
+        action: "created",
+        thread_id: thread.id,
+        conversation_id: thread.conversationId,
+        root_turn_id: thread.rootTurnId,
+        subject: thread.subject,
+        parent_thread_id: thread.parentThreadId,
+      },
+    });
+  }
+
+  /**
+   * Get a thread by ID.
+   * Scans the EventStore events since threads don't have a dedicated
+   * lookup-by-ID query method on EventStore.
+   */
+  get(id: string): ServerThread | undefined {
+    // Query thread events and find the matching one
+    const events = this.eventStore.query({ type: "thread" });
+    for (const event of events) {
+      if (event.payload.thread_id === id) {
+        const conversationId = event.payload.conversation_id as string;
+        const turnCount = this.countTurnsForThread(conversationId, id);
+        return {
+          id: event.payload.thread_id as string,
+          conversationId,
+          parentThreadId: event.payload.parent_thread_id as string | undefined,
+          subject: event.payload.subject as string | undefined,
+          rootTurnId: event.payload.root_turn_id as string,
+          turnCount,
+          participantCount: 0,
+          createdAt: event.timestamp,
+          updatedAt: event.timestamp,
+          createdBy: event.source.agent_id ?? "unknown",
+        };
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * List threads matching filter criteria.
+   */
+  list(filter: MAPThreadFilter): ServerThread[] {
+    const events = this.eventStore.query({ type: "thread" });
+    const threads: ServerThread[] = [];
+
+    for (const event of events) {
+      if (event.payload.action !== "created") continue;
+      if (event.payload.conversation_id !== filter.conversationId) continue;
+      if (
+        filter.parentThreadId !== undefined &&
+        event.payload.parent_thread_id !== filter.parentThreadId
+      )
+        continue;
+
+      const threadId = event.payload.thread_id as string;
+      const conversationId = event.payload.conversation_id as string;
+      const turnCount = this.countTurnsForThread(conversationId, threadId);
+
+      threads.push({
+        id: threadId,
+        conversationId,
+        parentThreadId: event.payload.parent_thread_id as string | undefined,
+        subject: event.payload.subject as string | undefined,
+        rootTurnId: event.payload.root_turn_id as string,
+        turnCount,
+        participantCount: 0,
+        createdAt: event.timestamp,
+        updatedAt: event.timestamp,
+        createdBy: event.source.agent_id ?? "unknown",
+      });
+    }
+
+    return threads;
+  }
+
+  /**
+   * Count turns that belong to a specific thread.
+   */
+  private countTurnsForThread(conversationId: string, threadId: string): number {
+    const turns = this.eventStore.listTurns({ conversationId, threadId });
+    return turns.length;
+  }
+
+  /**
+   * Delete a thread. Not supported — EventStore is append-only.
+   */
+  delete(_id: string): boolean {
+    return false;
+  }
+
+  /**
+   * Delete all threads for a conversation. Not supported.
+   */
+  deleteByConversation(_conversationId: string): number {
+    return 0;
+  }
+
+  /**
+   * Clear all threads. Not supported.
+   */
+  clear(): void {
+    // No-op
+  }
+}