@jackchen_me/open-multi-agent 1.0.0 → 1.0.1

package/src/team/messaging.ts

@@ -1,232 +0,0 @@
-/**
- * @fileoverview Inter-agent message bus.
- *
- * Provides a lightweight pub/sub system so agents can exchange typed messages
- * without direct references to each other. All messages are retained in memory
- * for replay and audit; read-state is tracked per recipient.
- */
-
-import { randomUUID } from 'node:crypto'
-
-// ---------------------------------------------------------------------------
-// Message type
-// ---------------------------------------------------------------------------
-
-/** A single message exchanged between agents (or broadcast to all). */
-export interface Message {
-  /** Stable UUID for this message. */
-  readonly id: string
-  /** Name of the sending agent. */
-  readonly from: string
-  /**
-   * Recipient agent name, or `'*'` when the message is a broadcast intended
-   * for every agent except the sender.
-   */
-  readonly to: string
-  readonly content: string
-  readonly timestamp: Date
-}
-
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-
-/** Returns true when `message` is addressed to `agentName`. */
-function isAddressedTo(message: Message, agentName: string): boolean {
-  if (message.to === '*') {
-    // Broadcasts are delivered to everyone except the sender.
-    return message.from !== agentName
-  }
-  return message.to === agentName
-}
-
-// ---------------------------------------------------------------------------
-// MessageBus
-// ---------------------------------------------------------------------------
-
-/**
- * In-memory message bus for inter-agent communication.
- *
- * Agents can send point-to-point messages or broadcasts. Subscribers are
- * notified synchronously (within the same microtask) when a new message
- * arrives addressed to them.
- *
- * @example
- * ```ts
- * const bus = new MessageBus()
- *
- * const unsubscribe = bus.subscribe('worker', (msg) => {
- *   console.log(`worker received: ${msg.content}`)
- * })
- *
- * bus.send('coordinator', 'worker', 'Start task A')
- * bus.broadcast('coordinator', 'All agents: stand by')
- *
- * unsubscribe()
- * ```
- */
-export class MessageBus {
-  /** All messages ever sent, in insertion order. */
-  private readonly messages: Message[] = []
-
-  /**
-   * Per-agent set of message IDs that have already been marked as read.
-   * A message absent from this set is considered unread.
-   */
-  private readonly readState = new Map<string, Set<string>>()
-
-  /**
-   * Active subscribers keyed by agent name. Each subscriber is a callback
-   * paired with a unique subscription ID used for unsubscription.
-   */
-  private readonly subscribers = new Map<
-    string,
-    Map<symbol, (message: Message) => void>
-  >()
-
-  // ---------------------------------------------------------------------------
-  // Write operations
-  // ---------------------------------------------------------------------------
-
-  /**
-   * Send a message from `from` to `to`.
-   *
-   * @returns The persisted {@link Message} including its generated ID and timestamp.
-   */
-  send(from: string, to: string, content: string): Message {
-    const message: Message = {
-      id: randomUUID(),
-      from,
-      to,
-      content,
-      timestamp: new Date(),
-    }
-    this.persist(message)
-    return message
-  }
-
-  /**
-   * Broadcast a message from `from` to all other agents (`to === '*'`).
-   *
-   * @returns The persisted broadcast {@link Message}.
-   */
-  broadcast(from: string, content: string): Message {
-    return this.send(from, '*', content)
-  }
-
-  // ---------------------------------------------------------------------------
-  // Read operations
-  // ---------------------------------------------------------------------------
-
-  /**
-   * Returns messages that have not yet been marked as read by `agentName`,
-   * including both direct messages and broadcasts addressed to them.
-   */
-  getUnread(agentName: string): Message[] {
-    const read = this.readState.get(agentName) ?? new Set<string>()
-    return this.messages.filter(
-      (m) => isAddressedTo(m, agentName) && !read.has(m.id),
-    )
-  }
-
-  /**
-   * Returns every message (read or unread) addressed to `agentName`,
-   * preserving insertion order.
-   */
-  getAll(agentName: string): Message[] {
-    return this.messages.filter((m) => isAddressedTo(m, agentName))
-  }
-
-  /**
-   * Mark a set of messages as read for `agentName`.
-   * Passing IDs that were already marked, or do not exist, is a no-op.
-   */
-  markRead(agentName: string, messageIds: string[]): void {
-    if (messageIds.length === 0) return
-    let read = this.readState.get(agentName)
-    if (!read) {
-      read = new Set<string>()
-      this.readState.set(agentName, read)
-    }
-    for (const id of messageIds) {
-      read.add(id)
-    }
-  }
-
-  /**
-   * Returns all messages exchanged between `agent1` and `agent2` (in either
-   * direction), sorted chronologically.
-   */
-  getConversation(agent1: string, agent2: string): Message[] {
-    return this.messages.filter(
-      (m) =>
-        (m.from === agent1 && m.to === agent2) ||
-        (m.from === agent2 && m.to === agent1),
-    )
-  }
-
-  // ---------------------------------------------------------------------------
-  // Subscriptions
-  // ---------------------------------------------------------------------------
-
-  /**
-   * Subscribe to new messages addressed to `agentName`.
-   *
-   * The `callback` is invoked synchronously after each matching message is
-   * persisted. Returns an unsubscribe function; calling it is idempotent.
-   *
-   * @example
-   * ```ts
-   * const off = bus.subscribe('agent-b', (msg) => handleMessage(msg))
-   * // Later…
-   * off()
-   * ```
-   */
-  subscribe(
-    agentName: string,
-    callback: (message: Message) => void,
-  ): () => void {
-    let agentSubs = this.subscribers.get(agentName)
-    if (!agentSubs) {
-      agentSubs = new Map()
-      this.subscribers.set(agentName, agentSubs)
-    }
-    const id = Symbol()
-    agentSubs.set(id, callback)
-    return () => {
-      agentSubs!.delete(id)
-    }
-  }
-
-  // ---------------------------------------------------------------------------
-  // Private helpers
-  // ---------------------------------------------------------------------------
-
-  private persist(message: Message): void {
-    this.messages.push(message)
-    this.notifySubscribers(message)
-  }
-
-  private notifySubscribers(message: Message): void {
-    // Notify direct subscribers of `message.to` (unless broadcast).
-    if (message.to !== '*') {
-      this.fireCallbacks(message.to, message)
-      return
-    }
-
-    // Broadcast: notify all subscribers except the sender.
-    for (const [agentName, subs] of this.subscribers) {
-      if (agentName !== message.from && subs.size > 0) {
-        this.fireCallbacks(agentName, message)
-      }
-    }
-  }
-
-  private fireCallbacks(agentName: string, message: Message): void {
-    const subs = this.subscribers.get(agentName)
-    if (!subs) return
-    for (const callback of subs.values()) {
-      callback(message)
-    }
-  }
-}

package/src/team/team.ts

@@ -1,334 +0,0 @@
-/**
- * @fileoverview Team — the central coordination object for a named group of agents.
- *
- * A {@link Team} owns the agent roster, the inter-agent {@link MessageBus},
- * the {@link TaskQueue}, and (optionally) a {@link SharedMemory} instance.
- * It also exposes a typed event bus so orchestrators can react to lifecycle
- * events without polling.
- */
-
-import type {
-  AgentConfig,
-  MemoryStore,
-  OrchestratorEvent,
-  Task,
-  TaskStatus,
-  TeamConfig,
-} from '../types.js'
-import { SharedMemory } from '../memory/shared.js'
-import { MessageBus } from './messaging.js'
-import type { Message } from './messaging.js'
-import { TaskQueue } from '../task/queue.js'
-import { createTask } from '../task/task.js'
-
-export type { Message }
-
-// ---------------------------------------------------------------------------
-// Internal event bus
-// ---------------------------------------------------------------------------
-
-type EventHandler = (data: unknown) => void
-
-/** Minimal synchronous event emitter. */
-class EventBus {
-  private readonly listeners = new Map<string, Map<symbol, EventHandler>>()
-
-  on(event: string, handler: EventHandler): () => void {
-    let map = this.listeners.get(event)
-    if (!map) {
-      map = new Map()
-      this.listeners.set(event, map)
-    }
-    const id = Symbol()
-    map.set(id, handler)
-    return () => {
-      map!.delete(id)
-    }
-  }
-
-  emit(event: string, data: unknown): void {
-    const map = this.listeners.get(event)
-    if (!map) return
-    for (const handler of map.values()) {
-      handler(data)
-    }
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Team
-// ---------------------------------------------------------------------------
-
-/**
- * Coordinates a named group of agents with shared messaging, task queuing,
- * and optional shared memory.
- *
- * @example
- * ```ts
- * const team = new Team({
- *   name: 'research-team',
- *   agents: [researcherConfig, writerConfig],
- *   sharedMemory: true,
- *   maxConcurrency: 2,
- * })
- *
- * team.on('task:complete', (data) => {
- *   const event = data as OrchestratorEvent
- *   console.log(`Task done: ${event.task}`)
- * })
- *
- * const task = team.addTask({
- *   title: 'Research topic',
- *   description: 'Gather background on quantum computing',
- *   status: 'pending',
- *   assignee: 'researcher',
- * })
- * ```
- */
-export class Team {
-  readonly name: string
-  readonly config: TeamConfig
-
-  private readonly agentMap: ReadonlyMap<string, AgentConfig>
-  private readonly bus: MessageBus
-  private readonly queue: TaskQueue
-  private readonly memory: SharedMemory | undefined
-  private readonly events: EventBus
-
-  constructor(config: TeamConfig) {
-    this.config = config
-    this.name = config.name
-
-    // Index agents by name for O(1) lookup.
-    this.agentMap = new Map(config.agents.map((a) => [a.name, a]))
-    this.bus = new MessageBus()
-    this.queue = new TaskQueue()
-    this.memory = config.sharedMemory ? new SharedMemory() : undefined
-    this.events = new EventBus()
-
-    // Bridge queue events onto the team's event bus.
-    this.queue.on('task:ready', (task) => {
-      const event: OrchestratorEvent = {
-        type: 'task_start',
-        task: task.id,
-        data: task,
-      }
-      this.events.emit('task:ready', event)
-    })
-
-    this.queue.on('task:complete', (task) => {
-      const event: OrchestratorEvent = {
-        type: 'task_complete',
-        task: task.id,
-        data: task,
-      }
-      this.events.emit('task:complete', event)
-    })
-
-    this.queue.on('task:failed', (task) => {
-      const event: OrchestratorEvent = {
-        type: 'error',
-        task: task.id,
-        data: task,
-      }
-      this.events.emit('task:failed', event)
-    })
-
-    this.queue.on('all:complete', () => {
-      this.events.emit('all:complete', undefined)
-    })
-  }
-
-  // ---------------------------------------------------------------------------
-  // Agent roster
-  // ---------------------------------------------------------------------------
-
-  /** Returns a shallow copy of the agent configs in registration order. */
-  getAgents(): AgentConfig[] {
-    return Array.from(this.agentMap.values())
-  }
-
-  /**
-   * Looks up an agent by name.
-   *
-   * @returns The {@link AgentConfig} or `undefined` when the name is not known.
-   */
-  getAgent(name: string): AgentConfig | undefined {
-    return this.agentMap.get(name)
-  }
-
-  // ---------------------------------------------------------------------------
-  // Messaging
-  // ---------------------------------------------------------------------------
-
-  /**
-   * Sends a point-to-point message from `from` to `to`.
-   *
-   * The message is persisted on the bus and any active subscribers for `to`
-   * are notified synchronously.
-   */
-  sendMessage(from: string, to: string, content: string): void {
-    const message = this.bus.send(from, to, content)
-    const event: OrchestratorEvent = {
-      type: 'message',
-      agent: from,
-      data: message,
-    }
-    this.events.emit('message', event)
-  }
-
-  /**
-   * Returns all messages (read or unread) addressed to `agentName`, in
-   * chronological order.
-   */
-  getMessages(agentName: string): Message[] {
-    return this.bus.getAll(agentName)
-  }
-
-  /**
-   * Broadcasts `content` from `from` to every other agent.
-   *
-   * The `to` field of the resulting message is `'*'`.
-   */
-  broadcast(from: string, content: string): void {
-    const message = this.bus.broadcast(from, content)
-    const event: OrchestratorEvent = {
-      type: 'message',
-      agent: from,
-      data: message,
-    }
-    this.events.emit('broadcast', event)
-  }
-
-  // ---------------------------------------------------------------------------
-  // Task management
-  // ---------------------------------------------------------------------------
-
-  /**
-   * Creates a new task, adds it to the queue, and returns the persisted
-   * {@link Task} (with generated `id`, `createdAt`, and `updatedAt`).
-   *
-   * @param task - Everything except the generated fields.
-   */
-  addTask(
-    task: Omit<Task, 'id' | 'createdAt' | 'updatedAt'>,
-  ): Task {
-    const created = createTask({
-      title: task.title,
-      description: task.description,
-      assignee: task.assignee,
-      dependsOn: task.dependsOn ? [...task.dependsOn] : undefined,
-    })
-
-    // Preserve any non-default status (e.g. 'blocked') supplied by the caller.
-    const finalTask: Task =
-      task.status !== 'pending'
-        ? { ...created, status: task.status as TaskStatus, result: task.result }
-        : created
-
-    this.queue.add(finalTask)
-    return finalTask
-  }
-
-  /** Returns a snapshot of all tasks in the queue (any status). */
-  getTasks(): Task[] {
-    return this.queue.list()
-  }
-
-  /** Returns all tasks whose `assignee` is `agentName`. */
-  getTasksByAssignee(agentName: string): Task[] {
-    return this.queue.list().filter((t) => t.assignee === agentName)
-  }
-
-  /**
-   * Applies a partial update to the task identified by `taskId`.
-   *
-   * @throws {Error} when the task is not found.
-   */
-  updateTask(taskId: string, update: Partial<Task>): Task {
-    // Extract only mutable fields accepted by the queue.
-    const { status, result, assignee } = update
-    return this.queue.update(taskId, {
-      ...(status !== undefined && { status }),
-      ...(result !== undefined && { result }),
-      ...(assignee !== undefined && { assignee }),
-    })
-  }
-
-  /**
-   * Returns the next `'pending'` task for `agentName`, respecting dependencies.
-   *
-   * Tries to find a task explicitly assigned to the agent first; falls back to
-   * the first unassigned pending task.
-   *
-   * @returns `undefined` when no ready task exists for this agent.
-   */
-  getNextTask(agentName: string): Task | undefined {
-    // Prefer a task explicitly assigned to this agent.
-    const assigned = this.queue.next(agentName)
-    if (assigned) return assigned
-
-    // Fall back to any unassigned pending task.
-    return this.queue.nextAvailable()
-  }
-
-  // ---------------------------------------------------------------------------
-  // Memory
-  // ---------------------------------------------------------------------------
-
-  /**
-   * Returns the shared {@link MemoryStore} for this team, or `undefined` if
-   * `sharedMemory` was not enabled in {@link TeamConfig}.
-   *
-   * Note: the returned value satisfies the {@link MemoryStore} interface.
-   * Callers that need the full {@link SharedMemory} API can use the
-   * `as SharedMemory` cast, but depending on the concrete type is discouraged.
-   */
-  getSharedMemory(): MemoryStore | undefined {
-    return this.memory?.getStore()
-  }
-
-  /**
-   * Returns the raw {@link SharedMemory} instance (team-internal accessor).
-   * Use this when you need the namespacing / `getSummary` features.
-   *
-   * @internal
-   */
-  getSharedMemoryInstance(): SharedMemory | undefined {
-    return this.memory
-  }
-
-  // ---------------------------------------------------------------------------
-  // Events
-  // ---------------------------------------------------------------------------
-
-  /**
-   * Subscribes to a team event.
-   *
-   * Built-in events:
-   * - `'task:ready'`   — emitted when a task becomes runnable.
-   * - `'task:complete'` — emitted when a task completes successfully.
-   * - `'task:failed'`  — emitted when a task fails.
-   * - `'all:complete'` — emitted when every task in the queue has terminated.
-   * - `'message'`      — emitted on point-to-point messages.
-   * - `'broadcast'`    — emitted on broadcast messages.
-   *
-   * `data` is typed as `unknown`; cast to {@link OrchestratorEvent} for
-   * structured access.
-   *
-   * @returns An unsubscribe function.
-   */
-  on(event: string, handler: (data: unknown) => void): () => void {
-    return this.events.on(event, handler)
-  }
-
-  /**
-   * Emits a custom event on the team's event bus.
-   *
-   * Orchestrators can use this to signal domain-specific lifecycle milestones
-   * (e.g. `'phase:research:complete'`) without modifying the Team class.
-   */
-  emit(event: string, data: unknown): void {
-    this.events.emit(event, data)
-  }
-}