macro-agent 0.0.10 → 0.0.12

package/src/store/types/conversations.ts

@@ -0,0 +1,129 @@
+/**
+ * Conversation-related type definitions for mail integration.
+ *
+ * These types define the materialized views for conversations, turns,
+ * and threads stored in the EventStore.
+ */
+
+import type { AgentId, Timestamp } from "./primitives.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Conversation Types (aligned with MAP SDK)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type ConversationType = "session" | "task" | "peer";
+
+export type ConversationStatus = "active" | "completed" | "failed" | "archived";
+
+export type ParticipantRole =
+  | "initiator"
+  | "assistant"
+  | "worker"
+  | "observer";
+
+export type TurnSourceType = "explicit" | "intercepted";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Materialized View Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * A conversation groups related interactions between participants.
+ * Materialized from `conversation` events.
+ */
+export interface Conversation {
+  id: string;
+  type: ConversationType;
+  status: ConversationStatus;
+  subject?: string;
+  parentConversationId?: string;
+  createdBy: string;
+  createdAt: Timestamp;
+  updatedAt: Timestamp;
+  closedAt?: Timestamp;
+  closedBy?: string;
+  closeReason?: string;
+  participantCount: number;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * A turn is a single message or event recorded within a conversation.
+ * Materialized from `turn` events.
+ */
+export interface ConversationTurn {
+  id: string;
+  conversationId: string;
+  participant: string;
+  timestamp: Timestamp;
+  contentType: string;
+  content: unknown;
+  threadId?: string;
+  inReplyTo?: string;
+  sourceType: TurnSourceType;
+  sourceMessageId?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * A thread is a sub-conversation within a conversation, rooted at a specific turn.
+ * Materialized from `thread` events.
+ */
+export interface ConversationThread {
+  id: string;
+  conversationId: string;
+  rootTurnId: string;
+  subject?: string;
+  parentThreadId?: string;
+  createdBy: string;
+  createdAt: Timestamp;
+  turnCount: number;
+}
+
+/**
+ * A participant is a member of a conversation with a role and join/leave tracking.
+ * Materialized from conversation `participant_joined` / `participant_left` events.
+ */
+export interface ConversationParticipant {
+  id: string;
+  conversationId: string;
+  type: "user" | "agent" | "system";
+  role: ParticipantRole;
+  joinedAt: Timestamp;
+  leftAt?: Timestamp;
+  agentId?: AgentId;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Filter Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ConversationFilter {
+  type?: ConversationType;
+  status?: ConversationStatus;
+  participantId?: string;
+  parentConversationId?: string;
+}
+
+export interface TurnFilter {
+  conversationId: string;
+  threadId?: string;
+  contentType?: string;
+  participantId?: string;
+  limit?: number;
+  order?: "asc" | "desc";
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Callback Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type ConversationChangeCallback = (
+  conversationId: string,
+  conversation: Conversation | null
+) => void;
+
+export type TurnChangeCallback = (
+  conversationId: string,
+  turn: ConversationTurn
+) => void;

package/src/store/types/events.ts

@@ -17,7 +17,11 @@ export type EventType =
   | "task"
   | "subscription"
   | "peer_message"
-  | "peer_request";
+  | "peer_request"
+  | "conversation"
+  | "turn"
+  | "thread"
+  | "session";
 
 // Status types for status events
 export type StatusType =

package/src/store/types/index.ts

@@ -8,3 +8,5 @@ export * from "./agents.js";
 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[];
 }

package/src/task/backend/memory.ts

@@ -27,6 +27,7 @@ import type {
   TaskError,
   SubtaskStatus,
   AssignOptions,
+  ClaimFilter,
   TaskChangeCallback,
   TaskChangeEvent,
   Unsubscribe,
@@ -96,6 +97,7 @@ export class InMemoryTaskBackend implements TaskBackend {
         details: {
           description: options.description,
           parent_task: options.parent_task,
+          tags: options.tags,
         },
       },
     });
@@ -421,6 +423,13 @@ export class InMemoryTaskBackend implements TaskBackend {
       if (filter.rootTasksOnly) {
         tasks = tasks.filter((t) => !t.parent_task);
       }
+
+      if (filter.tags && filter.tags.length > 0) {
+        const filterTags = new Set(filter.tags);
+        tasks = tasks.filter(
+          (t) => t.tags?.some((tag) => filterTags.has(tag))
+        );
+      }
     }
 
     // Convert to ExtendedTask and filter blocked if needed
@@ -618,6 +627,113 @@ export class InMemoryTaskBackend implements TaskBackend {
     return task.agent_history ?? [];
   }
 
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Pull Model (Claim/Unclaim)
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  async claim(
+    agentId: AgentId,
+    filter?: ClaimFilter
+  ): Promise<ExtendedTask | null> {
+    // Find claimable tasks: pending, not blocked, not assigned
+    const candidates = await this.listClaimable(filter);
+
+    if (candidates.length === 0) {
+      return null;
+    }
+
+    // Take the first candidate (oldest pending task by creation time)
+    const task = candidates[0];
+
+    // Atomically assign (within the same process, EventStore is synchronous)
+    // Re-check status to handle contention
+    const current = this.eventStore.getTask(task.id);
+    if (!current || current.status !== "pending" || current.assigned_agent) {
+      // Task was claimed by another agent between our check and assignment
+      return null;
+    }
+
+    // Assign to the claiming agent
+    this.eventStore.emit({
+      type: "task",
+      source: { agent_id: agentId },
+      payload: {
+        task_id: task.id,
+        action: "assigned",
+        details: {
+          agent_id: agentId,
+        },
+      },
+    });
+
+    const assigned = this.eventStore.getTask(task.id)!;
+    return this.toExtendedTask(assigned);
+  }
+
+  async unclaim(taskId: TaskId): Promise<void> {
+    const task = this.eventStore.getTask(taskId);
+    if (!task) {
+      throw new TaskBackendError(
+        `Task not found: ${taskId}`,
+        "TASK_NOT_FOUND",
+        taskId
+      );
+    }
+
+    if (!task.assigned_agent) {
+      throw new TaskBackendError(
+        `Task is not assigned: ${taskId}`,
+        "TASK_NOT_ASSIGNED",
+        taskId
+      );
+    }
+
+    // Return to pending status
+    this.eventStore.emit({
+      type: "task",
+      source: { agent_id: task.assigned_agent },
+      payload: {
+        task_id: taskId,
+        action: "unassigned",
+        details: {
+          agent_id: task.assigned_agent,
+        },
+      },
+    });
+  }
+
+  async listClaimable(filter?: ClaimFilter): Promise<ExtendedTask[]> {
+    let tasks = this.eventStore.listTasks();
+
+    // Only pending tasks (not assigned, not in_progress, etc.)
+    tasks = tasks.filter(
+      (t) => t.status === "pending" && !t.assigned_agent
+    );
+
+    // Apply claim filter
+    if (filter) {
+      if (filter.tags && filter.tags.length > 0) {
+        const filterTags = new Set(filter.tags);
+        tasks = tasks.filter(
+          (t) => t.tags?.some((tag) => filterTags.has(tag))
+        );
+      }
+
+      if (filter.rootTasksOnly) {
+        tasks = tasks.filter((t) => !t.parent_task);
+      }
+
+      if (filter.created_by) {
+        tasks = tasks.filter((t) => t.created_by === filter.created_by);
+      }
+    }
+
+    // Filter out blocked tasks
+    return tasks
+      .map((t) => this.toExtendedTask(t))
+      .filter((t) => !t.isBlocked);
+  }
+
   // ─────────────────────────────────────────────────────────────────────────────
   // Event Subscriptions
   // ─────────────────────────────────────────────────────────────────────────────

package/src/task/backend/types.ts

@@ -56,6 +56,9 @@ export interface CreateTaskOptions {
 
   /** Optional binding to external system (e.g., sudocode issue ID) */
   external_id?: string;
+
+  /** Optional tags for classification and filtering (pull model) */
+  tags?: string[];
 }
 
 /**
@@ -131,6 +134,9 @@ export interface TaskFilter {
 
   /** Filter tasks assigned before this timestamp (for stale assignment detection) */
   assignedBefore?: Timestamp;
+
+  /** Filter by tags (task must have at least one matching tag) */
+  tags?: string[];
 }
 
 /**
@@ -162,6 +168,25 @@ export interface AssignOptions {
   leaseMs?: number;
 }
 
+// =============================================================================
+// Claim Filter (Pull Model)
+// =============================================================================
+
+/**
+ * Filter options for claiming tasks.
+ * Used by the pull model to find eligible tasks for an agent.
+ */
+export interface ClaimFilter {
+  /** Only claim tasks with at least one matching tag */
+  tags?: string[];
+
+  /** Only claim root tasks (no parent) */
+  rootTasksOnly?: boolean;
+
+  /** Only claim tasks created by a specific agent */
+  created_by?: AgentId;
+}
+
 // =============================================================================
 // Event Types
 // =============================================================================
@@ -284,6 +309,24 @@ export interface TaskBackend {
   /** Get tasks that this task blocks */
   getBlocking(taskId: TaskId): Promise<ExtendedTask[]>;
 
+  // ─── Pull Model (Claim/Unclaim) ──────────────────────────────
+  /**
+   * Claim the next available task matching the filter.
+   * Atomically assigns the task to the agent. Returns null if no matching task
+   * is available or if another agent claimed it first (contention).
+   */
+  claim?(agentId: AgentId, filter?: ClaimFilter): Promise<ExtendedTask | null>;
+
+  /**
+   * Release a claimed task back to pending status.
+   */
+  unclaim?(taskId: TaskId): Promise<void>;
+
+  /**
+   * List tasks available for claiming (pending, not blocked, not assigned).
+   */
+  listClaimable?(filter?: ClaimFilter): Promise<ExtendedTask[]>;
+
   // ─── History ─────────────────────────────────────────────────
   /** Get agent assignment history for a task */
   getAgentHistory(taskId: TaskId): Promise<AgentHistoryEntry[]>;