mcp-codex-worker 0.1.11 → 0.1.13

package/src/task/task-manager.ts

@@ -0,0 +1,328 @@
+import {
+  uniqueNamesGenerator,
+  adjectives,
+  animals,
+} from 'unique-names-generator';
+
+import { TaskStatus, isTerminalStatus } from './task-state.js';
+import type {
+  TaskState,
+  TaskTypeName,
+  Provider,
+  PendingQuestion,
+} from './task-state.js';
+import { TaskStore } from './task-store.js';
+import type { TaskHandle } from './task-handle.js';
+import type { TaskResult, SessionMetrics } from './task-handle.js';
+import { createTaskHandle } from './task-handle-impl.js';
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+/** Maximum lines retained in the in-memory output ring buffer. */
+const OUTPUT_RING_BUFFER_MAX = 500;
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface TaskManagerOptions {
+  /**
+   * Root directory for persistence files.
+   * `undefined` means persistence is disabled (in-memory only).
+   */
+  persistenceRoot: string | undefined;
+}
+
+export interface CreateTaskInput {
+  prompt: string;
+  cwd: string;
+  provider: Provider;
+  taskType: TaskTypeName;
+  model?: string;
+  timeoutMs?: number;
+  dependsOn?: string[];
+  labels?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Event listener types
+// ---------------------------------------------------------------------------
+
+export type StatusChangeListener = (
+  task: TaskState,
+  previousStatus: TaskStatus,
+) => void;
+
+export type OutputListener = (taskId: string, line: string) => void;
+
+// ---------------------------------------------------------------------------
+// TaskManager
+// ---------------------------------------------------------------------------
+
+/**
+ * Central orchestrator for task lifecycle management.
+ *
+ * Wraps {@link TaskStore} with:
+ * - Human-readable ID generation (adjective-animal-number)
+ * - {@link TaskHandle} creation for provider adapters
+ * - Event bus (status changes, output lines)
+ * - Output ring buffer capping
+ *
+ * Spec reference: §3.1 (layer model), §3.2 (TaskHandle)
+ */
+export class TaskManager {
+  private readonly store = new TaskStore();
+  private readonly handles = new Map<string, TaskHandle>();
+  private readonly abortControllers = new Map<string, AbortController>();
+  private readonly abortListeners = new Map<string, Set<() => void>>();
+
+  private readonly statusListeners = new Set<StatusChangeListener>();
+  private readonly outputListeners = new Set<OutputListener>();
+
+  readonly persistenceRoot: string | undefined;
+
+  constructor(options: TaskManagerOptions) {
+    this.persistenceRoot = options.persistenceRoot;
+  }
+
+  // -------------------------------------------------------------------------
+  // Task creation
+  // -------------------------------------------------------------------------
+
+  /**
+   * Create a new task with a human-readable ID, store it, and return
+   * the initial {@link TaskState}.
+   */
+  createTask(input: CreateTaskInput): TaskState {
+    const id = this.generateId();
+    const now = new Date().toISOString();
+
+    const task: TaskState = {
+      id,
+      status: TaskStatus.PENDING,
+      provider: input.provider,
+      taskType: input.taskType,
+      prompt: input.prompt,
+      cwd: input.cwd,
+      createdAt: now,
+      updatedAt: now,
+      labels: input.labels ?? [],
+      output: [],
+      pendingQuestions: [],
+    };
+
+    // Only set optional properties when defined (exactOptionalPropertyTypes)
+    if (input.model !== undefined) task.model = input.model;
+    if (input.timeoutMs !== undefined) task.timeoutMs = input.timeoutMs;
+    if (input.dependsOn !== undefined) task.dependsOn = input.dependsOn;
+
+    this.store.create(task);
+
+    // Pre-create the handle so getHandle never returns undefined for a known task
+    const handle = createTaskHandle(this, id);
+    this.handles.set(id, handle);
+
+    return task;
+  }
+
+  // -------------------------------------------------------------------------
+  // Lookups
+  // -------------------------------------------------------------------------
+
+  getTask(id: string): TaskState | undefined {
+    return this.store.get(id);
+  }
+
+  getBySessionId(sessionId: string): TaskState | undefined {
+    return this.store.getBySessionId(sessionId);
+  }
+
+  getHandle(id: string): TaskHandle | undefined {
+    return this.handles.get(id);
+  }
+
+  getAllTasks(): TaskState[] {
+    return this.store.getAll();
+  }
+
+  // -------------------------------------------------------------------------
+  // Mutations (called by TaskHandle implementation)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Apply a partial update to a task.
+   *
+   * If the update includes a status change, the FSM is validated by the store.
+   * On successful status change the event bus is notified.
+   */
+  updateTask(id: string, updates: Partial<TaskState>): TaskState | undefined {
+    const prev = this.store.get(id);
+    if (!prev) return undefined;
+
+    const previousStatus = prev.status;
+    const result = this.store.update(id, updates);
+
+    if (result && result.status !== previousStatus) {
+      this.emitStatusChange(result, previousStatus);
+    }
+
+    return result;
+  }
+
+  /**
+   * Append a line to the task's in-memory output ring buffer.
+   * Caps at {@link OUTPUT_RING_BUFFER_MAX} lines (oldest lines evicted).
+   */
+  appendOutput(id: string, line: string): void {
+    const task = this.store.get(id);
+    if (!task) return;
+
+    task.output.push(line);
+    if (task.output.length > OUTPUT_RING_BUFFER_MAX) {
+      task.output.splice(0, task.output.length - OUTPUT_RING_BUFFER_MAX);
+    }
+    task.lastOutputAt = new Date().toISOString();
+    task.updatedAt = task.lastOutputAt;
+
+    for (const listener of this.outputListeners) {
+      listener(id, line);
+    }
+  }
+
+  /**
+   * Record a verbose-only output line.
+   * Updates lastOutputAt and fires the output listener with a prefix,
+   * but does NOT push to the in-memory ring buffer.
+   */
+  appendOutputFileOnly(id: string, line: string): void {
+    const task = this.store.get(id);
+    if (!task) return;
+
+    task.lastOutputAt = new Date().toISOString();
+    task.updatedAt = task.lastOutputAt;
+
+    for (const listener of this.outputListeners) {
+      listener(id, `[verbose-only] ${line}`);
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Abort management
+  // -------------------------------------------------------------------------
+
+  registerAbort(id: string, controller: AbortController): void {
+    this.abortControllers.set(id, controller);
+  }
+
+  unregisterAbort(id: string): void {
+    this.abortControllers.delete(id);
+  }
+
+  getAbortController(id: string): AbortController | undefined {
+    return this.abortControllers.get(id);
+  }
+
+  /**
+   * Register a callback for when a task's abort controller fires.
+   * Returns an unsubscribe function.
+   */
+  onAborted(id: string, cb: () => void): () => void {
+    let listeners = this.abortListeners.get(id);
+    if (!listeners) {
+      listeners = new Set();
+      this.abortListeners.set(id, listeners);
+    }
+    listeners.add(cb);
+    return () => {
+      listeners!.delete(cb);
+    };
+  }
+
+  /** Fire abort listeners for a task. Called when AbortController signals. */
+  fireAbortListeners(id: string): void {
+    const listeners = this.abortListeners.get(id);
+    if (!listeners) return;
+    for (const cb of listeners) {
+      cb();
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Pending question queue
+  // -------------------------------------------------------------------------
+
+  queuePendingQuestion(id: string, q: PendingQuestion): void {
+    const task = this.store.get(id);
+    if (!task) return;
+    task.pendingQuestions.push(q);
+    task.updatedAt = new Date().toISOString();
+  }
+
+  dequeuePendingQuestion(id: string): PendingQuestion | undefined {
+    const task = this.store.get(id);
+    if (!task) return undefined;
+    const q = task.pendingQuestions.shift();
+    if (q !== undefined) {
+      task.updatedAt = new Date().toISOString();
+    }
+    return q;
+  }
+
+  getPendingQuestions(id: string): readonly PendingQuestion[] {
+    const task = this.store.get(id);
+    if (!task) return [];
+    return task.pendingQuestions;
+  }
+
+  // -------------------------------------------------------------------------
+  // Event bus
+  // -------------------------------------------------------------------------
+
+  /**
+   * Subscribe to status change events.
+   * Returns an unsubscribe function.
+   */
+  onStatusChange(cb: StatusChangeListener): () => void {
+    this.statusListeners.add(cb);
+    return () => {
+      this.statusListeners.delete(cb);
+    };
+  }
+
+  /**
+   * Subscribe to output line events.
+   * Returns an unsubscribe function.
+   */
+  onOutput(cb: OutputListener): () => void {
+    this.outputListeners.add(cb);
+    return () => {
+      this.outputListeners.delete(cb);
+    };
+  }
+
+  /**
+   * Emit a status change event to all listeners.
+   * Public so that the TaskHandle implementation can call it directly.
+   */
+  emitStatusChange(task: TaskState, previousStatus: TaskStatus): void {
+    for (const listener of this.statusListeners) {
+      listener(task, previousStatus);
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Internal helpers
+  // -------------------------------------------------------------------------
+
+  private generateId(): string {
+    const name = uniqueNamesGenerator({
+      dictionaries: [adjectives, animals],
+      separator: '-',
+      length: 2,
+    });
+    const num = Math.floor(Math.random() * 900) + 100; // 100-999
+    return `${name}-${num}`;
+  }
+}

package/src/task/task-persistence.ts

@@ -0,0 +1,95 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { TaskStatus, isTerminalStatus } from './task-state.js';
+import type { TaskState } from './task-state.js';
+
+// ---------------------------------------------------------------------------
+// Persisted profile state — cooldown / failure tracking for provider profiles
+// Spec reference: §8.1
+// ---------------------------------------------------------------------------
+
+export interface PersistedProfileState {
+  id: string;
+  configDir: string;
+  cooldownUntil?: number;
+  failureCount: number;
+  lastFailureReason?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Top-level persisted state envelope
+// ---------------------------------------------------------------------------
+
+export interface PersistedState {
+  version: 1;
+  tasks: TaskState[];
+  profiles: PersistedProfileState[];
+  lastSavedAt: string;
+}
+
+// ---------------------------------------------------------------------------
+// persistenceDir — deterministic per-workspace directory
+// ---------------------------------------------------------------------------
+
+export function persistenceDir(root: string, cwd: string): string {
+  const hash = createHash('md5').update(cwd).digest('hex');
+  return join(root, hash);
+}
+
+// ---------------------------------------------------------------------------
+// saveState — atomic write: write tmp → rename
+// ---------------------------------------------------------------------------
+
+export async function saveState(dir: string, state: PersistedState): Promise<void> {
+  await mkdir(dir, { recursive: true });
+  const target = join(dir, 'state.json');
+  const tmp = join(dir, `state.json.tmp.${process.pid}`);
+  await writeFile(tmp, JSON.stringify(state, null, 2), 'utf-8');
+  await rename(tmp, target);
+}
+
+// ---------------------------------------------------------------------------
+// loadState — read + parse, null on missing or corrupt
+// ---------------------------------------------------------------------------
+
+export async function loadState(dir: string): Promise<PersistedState | null> {
+  try {
+    const raw = await readFile(join(dir, 'state.json'), 'utf-8');
+    return JSON.parse(raw) as PersistedState;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// applyRecovery — per-task recovery on server restart
+// Spec reference: §9.2 steps 1–2
+// ---------------------------------------------------------------------------
+
+export function applyRecovery(task: TaskState, hasCrashRecovery: boolean): TaskState {
+  // 1. Terminal states restore as-is
+  if (isTerminalStatus(task.status)) {
+    return task;
+  }
+
+  // 2. Adapters without crash recovery → UNKNOWN
+  if (!hasCrashRecovery) {
+    const now = new Date().toISOString();
+    return {
+      ...task,
+      status: TaskStatus.UNKNOWN,
+      error: `Server restarted; ${task.provider} sessions don't survive restarts`,
+      completedAt: now,
+      output: [
+        ...task.output,
+        `[recovery] Task was ${task.status} when server restarted; marked UNKNOWN`,
+      ],
+      recovered: true,
+    };
+  }
+
+  // 3. Has crash recovery (e.g. Codex) — return as-is; adapter handles externally
+  return task;
+}

package/src/task/task-state.ts

@@ -0,0 +1,121 @@
+export enum TaskStatus {
+  WAITING = 'waiting',
+  PENDING = 'pending',
+  RUNNING = 'running',
+  RATE_LIMITED = 'rate_limited',
+  WAITING_ANSWER = 'waiting_answer',
+  COMPLETED = 'completed',
+  FAILED = 'failed',
+  TIMED_OUT = 'timed_out',
+  CANCELLED = 'cancelled',
+  UNKNOWN = 'unknown',
+}
+
+export const TERMINAL_STATUSES: ReadonlySet<TaskStatus> = new Set([
+  TaskStatus.COMPLETED,
+  TaskStatus.FAILED,
+  TaskStatus.CANCELLED,
+  TaskStatus.TIMED_OUT,
+  TaskStatus.UNKNOWN,
+]);
+
+export function isTerminalStatus(status: TaskStatus): boolean {
+  return TERMINAL_STATUSES.has(status);
+}
+
+export type TaskTypeName = 'coder' | 'planner' | 'tester' | 'researcher' | 'general';
+
+export type Provider = 'codex' | 'copilot' | 'claude-cli';
+
+// ---------------------------------------------------------------------------
+// PendingQuestion — discriminated union for 5 pause-flow question variants
+// Spec reference: §3.3
+// ---------------------------------------------------------------------------
+
+export type PendingQuestion =
+  | {
+      type: 'user_input';
+      requestId: string;
+      questions: Array<{
+        id: string;
+        text: string;
+        options?: string[];
+        allowFreeform?: boolean;
+      }>;
+    }
+  | {
+      type: 'command_approval';
+      requestId: string;
+      command: string;
+      sandboxPolicy?: string;
+    }
+  | {
+      type: 'file_approval';
+      requestId: string;
+      fileChanges: Array<{ path: string; patch: string }>;
+    }
+  | {
+      type: 'elicitation';
+      requestId: string;
+      serverName?: string;
+      message: string;
+      schema?: unknown;
+    }
+  | {
+      type: 'dynamic_tool';
+      requestId: string;
+      toolName: string;
+      arguments: string;
+    };
+
+export type PendingQuestionType = PendingQuestion['type'];
+
+// ---------------------------------------------------------------------------
+// TaskState — complete in-memory representation of a task
+// Spec reference: §3.2 (data model), §4.1 (FSM states)
+// ---------------------------------------------------------------------------
+
+export interface TaskState {
+  // Identity
+  id: string;
+  status: TaskStatus;
+  provider: Provider;
+  taskType: TaskTypeName;
+
+  // Execution
+  prompt: string;
+  cwd: string;
+  model?: string;
+  sessionId?: string;
+  operationId?: string;
+
+  // Lifecycle timestamps
+  createdAt: string;
+  updatedAt: string;
+  startedAt?: string;
+  completedAt?: string;
+  lastOutputAt?: string;
+  timeoutMs?: number;
+  timeoutAt?: string;
+  keepAlive?: number;
+
+  // Output
+  output: string[];
+  outputFilePath?: string;
+
+  // Dependencies & labels
+  dependsOn?: string[];
+  labels: string[];
+
+  // Pause state
+  pendingQuestions: PendingQuestion[];
+
+  // Error tracking
+  error?: string;
+  exitCode?: number;
+  result?: unknown;
+
+  // Recovery markers
+  recovered?: boolean;
+  degraded?: boolean;
+}

package/src/task/task-store.ts

@@ -0,0 +1,121 @@
+import { isTerminalStatus } from './task-state.js';
+import type { TaskState, TaskStatus } from './task-state.js';
+import { isValidTransition } from './fsm-transitions.js';
+
+/**
+ * In-memory task store with FSM-validated state transitions.
+ *
+ * This is the single source of truth for task state. It enforces the FSM at
+ * the data layer — illegal transitions are rejected before any mutation occurs.
+ *
+ * Terminal tasks can be evicted by age to prevent unbounded memory growth.
+ */
+export class TaskStore {
+  private readonly tasks = new Map<string, TaskState>();
+
+  /** Store a new task. Overwrites if the ID already exists. */
+  create(task: TaskState): void {
+    this.tasks.set(task.id, task);
+  }
+
+  /** Retrieve a task by its unique ID. */
+  get(id: string): TaskState | undefined {
+    return this.tasks.get(id);
+  }
+
+  /** Linear scan for a task matching the given session ID. */
+  getBySessionId(sessionId: string): TaskState | undefined {
+    for (const task of this.tasks.values()) {
+      if (task.sessionId === sessionId) return task;
+    }
+    return undefined;
+  }
+
+  /** Return all tasks as an array. */
+  getAll(): TaskState[] {
+    return [...this.tasks.values()];
+  }
+
+  /**
+   * Transition a task to a new status.
+   *
+   * Returns `true` if the transition was valid and applied, `false` if the
+   * task was not found or the transition is illegal per the FSM.
+   */
+  updateStatus(id: string, next: TaskStatus): boolean {
+    const task = this.tasks.get(id);
+    if (!task) return false;
+
+    if (!isValidTransition(task.status, next)) return false;
+
+    const now = new Date().toISOString();
+    task.status = next;
+    task.updatedAt = now;
+
+    if (isTerminalStatus(next)) {
+      task.completedAt = now;
+    }
+
+    return true;
+  }
+
+  /**
+   * Apply a partial update to a task. If the update includes a `status`
+   * change, the FSM is validated first — an illegal transition causes the
+   * entire update to be rejected (returns `undefined`).
+   */
+  update(id: string, updates: Partial<TaskState>): TaskState | undefined {
+    const task = this.tasks.get(id);
+    if (!task) return undefined;
+
+    // Validate status transition if status is being changed
+    if (updates.status !== undefined && updates.status !== task.status) {
+      if (!isValidTransition(task.status, updates.status)) return undefined;
+    }
+
+    const now = new Date().toISOString();
+
+    Object.assign(task, updates, { updatedAt: now });
+
+    if (updates.status !== undefined && isTerminalStatus(updates.status)) {
+      task.completedAt = now;
+    }
+
+    return task;
+  }
+
+  /** Remove a task by ID. Returns `true` if it existed. */
+  delete(id: string): boolean {
+    return this.tasks.delete(id);
+  }
+
+  /**
+   * Remove terminal tasks whose `updatedAt` timestamp is older than
+   * `maxAgeMs` milliseconds from now.
+   *
+   * Returns the number of tasks evicted.
+   */
+  evict(maxAgeMs: number): number {
+    const cutoff = Date.now() - maxAgeMs;
+    let count = 0;
+
+    for (const [id, task] of this.tasks) {
+      if (isTerminalStatus(task.status) && new Date(task.updatedAt).getTime() < cutoff) {
+        this.tasks.delete(id);
+        count++;
+      }
+    }
+
+    return count;
+  }
+
+  /** Remove all tasks. */
+  clear(): void {
+    this.tasks.clear();
+  }
+
+  /** Return the number of stored tasks. */
+  size(): number {
+    return this.tasks.size;
+  }
+}