@jackchen_me/open-multi-agent 0.1.0

package/src/task/queue.ts

@@ -0,0 +1,394 @@
+/**
+ * @fileoverview Dependency-aware task queue.
+ *
+ * {@link TaskQueue} owns the mutable lifecycle of every task it holds.
+ * Completing a task automatically unblocks dependents and fires events so
+ * orchestrators can react without polling.
+ */
+
+import type { Task, TaskStatus } from '../types.js'
+import { isTaskReady } from './task.js'
+
+// ---------------------------------------------------------------------------
+// Event types
+// ---------------------------------------------------------------------------
+
+/** Named event types emitted by {@link TaskQueue}. */
+export type TaskQueueEvent =
+  | 'task:ready'
+  | 'task:complete'
+  | 'task:failed'
+  | 'all:complete'
+
+/** Handler for `'task:ready' | 'task:complete' | 'task:failed'` events. */
+type TaskHandler = (task: Task) => void
+/** Handler for `'all:complete'` (no task argument). */
+type AllCompleteHandler = () => void
+
+type HandlerFor<E extends TaskQueueEvent> = E extends 'all:complete'
+  ? AllCompleteHandler
+  : TaskHandler
+
+// ---------------------------------------------------------------------------
+// TaskQueue
+// ---------------------------------------------------------------------------
+
+/**
+ * Mutable, event-driven queue with topological dependency resolution.
+ *
+ * Tasks enter in `'pending'` state. The queue promotes them to `'blocked'`
+ * when unresolved dependencies exist, and back to `'pending'` (firing
+ * `'task:ready'`) when those dependencies complete. Callers drive execution by
+ * calling {@link next} / {@link nextAvailable} and updating task state via
+ * {@link complete} or {@link fail}.
+ *
+ * @example
+ * ```ts
+ * const queue = new TaskQueue()
+ * queue.on('task:ready', (task) => scheduleExecution(task))
+ * queue.on('all:complete', () => shutdown())
+ *
+ * queue.addBatch(tasks)
+ * ```
+ */
+export class TaskQueue {
+  private readonly tasks = new Map<string, Task>()
+
+  /** Listeners keyed by event type, stored as symbol → handler pairs. */
+  private readonly listeners = new Map<
+    TaskQueueEvent,
+    Map<symbol, TaskHandler | AllCompleteHandler>
+  >()
+
+  // ---------------------------------------------------------------------------
+  // Mutation: add
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Adds a single task.
+   *
+   * If the task has unresolved dependencies it is immediately promoted to
+   * `'blocked'`; otherwise it stays `'pending'` and `'task:ready'` fires.
+   */
+  add(task: Task): void {
+    const resolved = this.resolveInitialStatus(task)
+    this.tasks.set(resolved.id, resolved)
+    if (resolved.status === 'pending') {
+      this.emit('task:ready', resolved)
+    }
+  }
+
+  /**
+   * Adds multiple tasks at once.
+   *
+   * Processing each task re-evaluates the current map state, so inserting a
+   * batch where some tasks satisfy others' dependencies produces correct initial
+   * statuses when the dependencies appear first in the array. Use
+   * {@link getTaskDependencyOrder} from `task.ts` to pre-sort if needed.
+   */
+  addBatch(tasks: Task[]): void {
+    for (const task of tasks) {
+      this.add(task)
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Mutation: update / complete / fail
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Applies a partial update to an existing task.
+   *
+   * Only `status`, `result`, and `assignee` are accepted to keep the update
+   * surface narrow. Use {@link complete} and {@link fail} for terminal states.
+   *
+   * @throws {Error} when `taskId` is not found.
+   */
+  update(
+    taskId: string,
+    update: Partial<Pick<Task, 'status' | 'result' | 'assignee'>>,
+  ): Task {
+    const task = this.requireTask(taskId)
+    const updated: Task = {
+      ...task,
+      ...update,
+      updatedAt: new Date(),
+    }
+    this.tasks.set(taskId, updated)
+    return updated
+  }
+
+  /**
+   * Marks `taskId` as `'completed'`, records an optional `result` string, and
+   * unblocks any dependents that are now ready to run.
+   *
+   * Fires `'task:complete'`, then `'task:ready'` for each newly-unblocked task,
+   * then `'all:complete'` when the queue is fully resolved.
+   *
+   * @throws {Error} when `taskId` is not found.
+   */
+  complete(taskId: string, result?: string): Task {
+    const completed = this.update(taskId, { status: 'completed', result })
+    this.emit('task:complete', completed)
+    this.unblockDependents(taskId)
+    if (this.isComplete()) {
+      this.emitAllComplete()
+    }
+    return completed
+  }
+
+  /**
+   * Marks `taskId` as `'failed'` and records `error` in the `result` field.
+   *
+   * Fires `'task:failed'` for the failed task and for every downstream task
+   * that transitively depended on it (cascade failure). This prevents blocked
+   * tasks from remaining stuck indefinitely when an upstream dependency fails.
+   *
+   * @throws {Error} when `taskId` is not found.
+   */
+  fail(taskId: string, error: string): Task {
+    const failed = this.update(taskId, { status: 'failed', result: error })
+    this.emit('task:failed', failed)
+    this.cascadeFailure(taskId)
+    if (this.isComplete()) {
+      this.emitAllComplete()
+    }
+    return failed
+  }
+
+  /**
+   * Recursively marks all tasks that (transitively) depend on `failedTaskId`
+   * as `'failed'` with an informative message, firing `'task:failed'` for each.
+   *
+   * Only tasks in `'blocked'` or `'pending'` state are affected; tasks already
+   * in a terminal state are left untouched.
+   */
+  private cascadeFailure(failedTaskId: string): void {
+    for (const task of this.tasks.values()) {
+      if (task.status !== 'blocked' && task.status !== 'pending') continue
+      if (!task.dependsOn?.includes(failedTaskId)) continue
+
+      const cascaded = this.update(task.id, {
+        status: 'failed',
+        result: `Cancelled: dependency "${failedTaskId}" failed.`,
+      })
+      this.emit('task:failed', cascaded)
+      // Recurse to handle transitive dependents.
+      this.cascadeFailure(task.id)
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Queries
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Returns the next `'pending'` task for `assignee` (matched against
+   * `task.assignee`), or `undefined` if none exists.
+   *
+   * If `assignee` is omitted, behaves like {@link nextAvailable}.
+   */
+  next(assignee?: string): Task | undefined {
+    if (assignee === undefined) return this.nextAvailable()
+
+    for (const task of this.tasks.values()) {
+      if (task.status === 'pending' && task.assignee === assignee) {
+        return task
+      }
+    }
+    return undefined
+  }
+
+  /**
+   * Returns the next `'pending'` task that has no `assignee` restriction, or
+   * the first `'pending'` task overall when all pending tasks have an assignee.
+   */
+  nextAvailable(): Task | undefined {
+    let fallback: Task | undefined
+
+    for (const task of this.tasks.values()) {
+      if (task.status !== 'pending') continue
+      if (!task.assignee) return task
+      if (!fallback) fallback = task
+    }
+
+    return fallback
+  }
+
+  /** Returns a snapshot array of all tasks (any status). */
+  list(): Task[] {
+    return Array.from(this.tasks.values())
+  }
+
+  /** Returns all tasks whose `status` matches `status`. */
+  getByStatus(status: TaskStatus): Task[] {
+    return this.list().filter((t) => t.status === status)
+  }
+
+  /**
+   * Returns `true` when every task in the queue has reached a terminal state
+   * (`'completed'` or `'failed'`), **or** the queue is empty.
+   */
+  isComplete(): boolean {
+    for (const task of this.tasks.values()) {
+      if (task.status !== 'completed' && task.status !== 'failed') return false
+    }
+    return true
+  }
+
+  /**
+   * Returns a progress snapshot.
+   *
+   * @example
+   * ```ts
+   * const { completed, total } = queue.getProgress()
+   * console.log(`${completed}/${total} tasks done`)
+   * ```
+   */
+  getProgress(): {
+    total: number
+    completed: number
+    failed: number
+    inProgress: number
+    pending: number
+    blocked: number
+  } {
+    let completed = 0
+    let failed = 0
+    let inProgress = 0
+    let pending = 0
+    let blocked = 0
+
+    for (const task of this.tasks.values()) {
+      switch (task.status) {
+        case 'completed':
+          completed++
+          break
+        case 'failed':
+          failed++
+          break
+        case 'in_progress':
+          inProgress++
+          break
+        case 'pending':
+          pending++
+          break
+        case 'blocked':
+          blocked++
+          break
+      }
+    }
+
+    return {
+      total: this.tasks.size,
+      completed,
+      failed,
+      inProgress,
+      pending,
+      blocked,
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Events
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Subscribes to a queue event.
+   *
+   * @returns An unsubscribe function. Calling it is idempotent.
+   *
+   * @example
+   * ```ts
+   * const off = queue.on('task:ready', (task) => execute(task))
+   * // later…
+   * off()
+   * ```
+   */
+  on<E extends TaskQueueEvent>(
+    event: E,
+    handler: HandlerFor<E>,
+  ): () => void {
+    let map = this.listeners.get(event)
+    if (!map) {
+      map = new Map()
+      this.listeners.set(event, map)
+    }
+    const id = Symbol()
+    map.set(id, handler as TaskHandler | AllCompleteHandler)
+    return () => {
+      map!.delete(id)
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Evaluates whether `task` should start as `'blocked'` based on the tasks
+   * already registered in the queue.
+   */
+  private resolveInitialStatus(task: Task): Task {
+    if (!task.dependsOn || task.dependsOn.length === 0) return task
+
+    const allCurrent = Array.from(this.tasks.values())
+    const ready = isTaskReady(task, allCurrent)
+    if (ready) return task
+
+    return { ...task, status: 'blocked', updatedAt: new Date() }
+  }
+
+  /**
+   * After a task completes, scan all `'blocked'` tasks and promote any that are
+   * now fully satisfied to `'pending'`, firing `'task:ready'` for each.
+   *
+   * The task array and lookup map are built once for the entire scan to keep
+   * the operation O(n) rather than O(n²).
+   */
+  private unblockDependents(completedId: string): void {
+    const allTasks = Array.from(this.tasks.values())
+    const taskById = new Map<string, Task>(allTasks.map((t) => [t.id, t]))
+
+    for (const task of allTasks) {
+      if (task.status !== 'blocked') continue
+      if (!task.dependsOn?.includes(completedId)) continue
+
+      // Re-check against the current state of the whole task set.
+      // Pass the pre-built map to avoid rebuilding it for every candidate task.
+      if (isTaskReady(task, allTasks, taskById)) {
+        const unblocked: Task = {
+          ...task,
+          status: 'pending',
+          updatedAt: new Date(),
+        }
+        this.tasks.set(task.id, unblocked)
+        // Update the map so subsequent iterations in the same call see the new status.
+        taskById.set(task.id, unblocked)
+        this.emit('task:ready', unblocked)
+      }
+    }
+  }
+
+  private emit(event: 'task:ready' | 'task:complete' | 'task:failed', task: Task): void {
+    const map = this.listeners.get(event)
+    if (!map) return
+    for (const handler of map.values()) {
+      ;(handler as TaskHandler)(task)
+    }
+  }
+
+  private emitAllComplete(): void {
+    const map = this.listeners.get('all:complete')
+    if (!map) return
+    for (const handler of map.values()) {
+      ;(handler as AllCompleteHandler)()
+    }
+  }
+
+  private requireTask(taskId: string): Task {
+    const task = this.tasks.get(taskId)
+    if (!task) throw new Error(`TaskQueue: task "${taskId}" not found.`)
+    return task
+  }
+}

package/src/task/task.ts

@@ -0,0 +1,232 @@
+/**
+ * @fileoverview Pure task utility functions.
+ *
+ * These helpers operate on plain {@link Task} values without any mutable
+ * state, making them safe to use in reducers, tests, and reactive pipelines.
+ * Stateful orchestration belongs in {@link TaskQueue}.
+ */
+
+import type { Task, TaskStatus } from '../types.js'
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a new {@link Task} with a generated UUID, `'pending'` status, and
+ * `createdAt`/`updatedAt` timestamps set to the current instant.
+ *
+ * @example
+ * ```ts
+ * const task = createTask({
+ *   title: 'Research competitors',
+ *   description: 'Identify the top 5 competitors and their pricing',
+ *   assignee: 'researcher',
+ * })
+ * ```
+ */
+export function createTask(input: {
+  title: string
+  description: string
+  assignee?: string
+  dependsOn?: string[]
+}): Task {
+  const now = new Date()
+  return {
+    id: crypto.randomUUID(),
+    title: input.title,
+    description: input.description,
+    status: 'pending' as TaskStatus,
+    assignee: input.assignee,
+    dependsOn: input.dependsOn ? [...input.dependsOn] : undefined,
+    result: undefined,
+    createdAt: now,
+    updatedAt: now,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Readiness
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns `true` when `task` can be started immediately.
+ *
+ * A task is considered ready when:
+ * 1. Its status is `'pending'`.
+ * 2. Every task listed in `task.dependsOn` has status `'completed'`.
+ *
+ * Tasks whose dependencies are missing from `allTasks` are treated as
+ * unresolvable and therefore **not** ready.
+ *
+ * @param task      - The task to evaluate.
+ * @param allTasks  - The full collection of tasks in the current queue/plan.
+ * @param taskById  - Optional pre-built id→task map. When provided the function
+ *                    skips rebuilding the map, reducing the complexity of
+ *                    call-sites that invoke `isTaskReady` inside a loop from
+ *                    O(n²) to O(n).
+ */
+export function isTaskReady(
+  task: Task,
+  allTasks: Task[],
+  taskById?: Map<string, Task>,
+): boolean {
+  if (task.status !== 'pending') return false
+  if (!task.dependsOn || task.dependsOn.length === 0) return true
+
+  const map = taskById ?? new Map<string, Task>(allTasks.map((t) => [t.id, t]))
+
+  for (const depId of task.dependsOn) {
+    const dep = map.get(depId)
+    if (!dep || dep.status !== 'completed') return false
+  }
+
+  return true
+}
+
+// ---------------------------------------------------------------------------
+// Topological sort
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns `tasks` sorted so that each task appears after all of its
+ * dependencies — a standard topological (Kahn's algorithm) ordering.
+ *
+ * Tasks with no dependencies come first. If the graph contains a cycle the
+ * function returns a partial result containing only the tasks that could be
+ * ordered; use {@link validateTaskDependencies} to detect cycles before calling
+ * this function in production paths.
+ *
+ * @example
+ * ```ts
+ * const ordered = getTaskDependencyOrder(tasks)
+ * for (const task of ordered) {
+ *   await run(task)
+ * }
+ * ```
+ */
+export function getTaskDependencyOrder(tasks: Task[]): Task[] {
+  if (tasks.length === 0) return []
+
+  const taskById = new Map<string, Task>(tasks.map((t) => [t.id, t]))
+
+  // Build adjacency: dependsOn edges become "predecessors" for in-degree count.
+  const inDegree = new Map<string, number>()
+  // successors[id] = list of task IDs that depend on `id`
+  const successors = new Map<string, string[]>()
+
+  for (const task of tasks) {
+    if (!inDegree.has(task.id)) inDegree.set(task.id, 0)
+    if (!successors.has(task.id)) successors.set(task.id, [])
+
+    for (const depId of task.dependsOn ?? []) {
+      // Only count dependencies that exist in this task set.
+      if (taskById.has(depId)) {
+        inDegree.set(task.id, (inDegree.get(task.id) ?? 0) + 1)
+        const deps = successors.get(depId) ?? []
+        deps.push(task.id)
+        successors.set(depId, deps)
+      }
+    }
+  }
+
+  // Kahn's algorithm: start with all nodes of in-degree 0.
+  const queue: string[] = []
+  for (const [id, degree] of inDegree) {
+    if (degree === 0) queue.push(id)
+  }
+
+  const ordered: Task[] = []
+  while (queue.length > 0) {
+    const id = queue.shift()!
+    const task = taskById.get(id)
+    if (task) ordered.push(task)
+
+    for (const successorId of successors.get(id) ?? []) {
+      const newDegree = (inDegree.get(successorId) ?? 0) - 1
+      inDegree.set(successorId, newDegree)
+      if (newDegree === 0) queue.push(successorId)
+    }
+  }
+
+  return ordered
+}
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validates the dependency graph of a task collection.
+ *
+ * Checks for:
+ * - References to unknown task IDs in `dependsOn`.
+ * - Cycles (a task depending on itself, directly or transitively).
+ * - Self-dependencies (`task.dependsOn` includes its own `id`).
+ *
+ * @returns An object with `valid: true` when no issues were found, or
+ *          `valid: false` with a non-empty `errors` array describing each
+ *          problem.
+ *
+ * @example
+ * ```ts
+ * const { valid, errors } = validateTaskDependencies(tasks)
+ * if (!valid) throw new Error(errors.join('\n'))
+ * ```
+ */
+export function validateTaskDependencies(tasks: Task[]): {
+  valid: boolean
+  errors: string[]
+} {
+  const errors: string[] = []
+  const taskById = new Map<string, Task>(tasks.map((t) => [t.id, t]))
+
+  // Pass 1: check for unknown references and self-dependencies.
+  for (const task of tasks) {
+    for (const depId of task.dependsOn ?? []) {
+      if (depId === task.id) {
+        errors.push(
+          `Task "${task.title}" (${task.id}) depends on itself.`,
+        )
+        continue
+      }
+      if (!taskById.has(depId)) {
+        errors.push(
+          `Task "${task.title}" (${task.id}) references unknown dependency "${depId}".`,
+        )
+      }
+    }
+  }
+
+  // Pass 2: cycle detection via DFS colouring (white=0, grey=1, black=2).
+  const colour = new Map<string, 0 | 1 | 2>()
+  for (const task of tasks) colour.set(task.id, 0)
+
+  const visit = (id: string, path: string[]): void => {
+    if (colour.get(id) === 2) return // Already fully explored.
+    if (colour.get(id) === 1) {
+      // Found a back-edge — cycle.
+      const cycleStart = path.indexOf(id)
+      const cycle = path.slice(cycleStart).concat(id)
+      errors.push(`Cyclic dependency detected: ${cycle.join(' -> ')}`)
+      return
+    }
+
+    colour.set(id, 1)
+    const task = taskById.get(id)
+    for (const depId of task?.dependsOn ?? []) {
+      if (taskById.has(depId)) {
+        visit(depId, [...path, id])
+      }
+    }
+    colour.set(id, 2)
+  }
+
+  for (const task of tasks) {
+    if (colour.get(task.id) === 0) {
+      visit(task.id, [])
+    }
+  }
+
+  return { valid: errors.length === 0, errors }
+}