@ronkovic/aad 0.3.0

package/src/modules/task-queue/dispatcher.ts

@@ -0,0 +1,372 @@
+import type { Logger } from "pino";
+import type { TaskId, WorkerId, TaskPlan, Task, ProgressState } from "@aad/shared/types";
+import type { EventBus } from "@aad/shared/events";
+import { TaskQueueError } from "@aad/shared/errors";
+import { getReadyTasks } from "./dependency-resolver";
+
+// Import from persistence module
+export interface TaskStore {
+  get(taskId: TaskId): Promise<Task | null>;
+  getAll(): Promise<Task[]>;
+  getByStatus(status: import("@aad/shared/types").TaskStatus): Promise<Task[]>;
+  save(task: Task): Promise<void>;
+  delete(taskId: TaskId): Promise<void>;
+}
+
+export interface WorkerStore {
+  get(workerId: WorkerId): Promise<import("@aad/shared/types").Worker | null>;
+  getAll(): Promise<Array<import("@aad/shared/types").Worker>>;
+  getIdle(): Promise<Array<import("@aad/shared/types").Worker>>;
+  save(worker: import("@aad/shared/types").Worker): Promise<void>;
+  delete(workerId: WorkerId): Promise<void>;
+}
+
+export interface RunStore {
+  get(runId: import("@aad/shared/types").RunId): Promise<import("@aad/shared/types").RunState | null>;
+  save(state: import("@aad/shared/types").RunState): Promise<void>;
+}
+
+export interface DispatcherConfig {
+  maxRetries?: number;
+  staleTaskCheckInterval?: number;
+  staleTaskThreshold?: number;
+}
+
+export interface DispatcherDeps {
+  taskStore: TaskStore;
+  workerStore: WorkerStore;
+  runStore: RunStore;
+  eventBus: EventBus;
+  config: DispatcherConfig;
+  logger: Logger;
+}
+
+/**
+ * Event-driven task dispatcher
+ * Manages task lifecycle and dependency resolution
+ */
+export class Dispatcher {
+  private deps: DispatcherDeps;
+  private staleCheckInterval?: Timer;
+  private taskMap: Map<string, Task> = new Map();
+  private initialized = false;
+  private runId?: import("@aad/shared/types").RunId;
+
+  constructor(deps: DispatcherDeps) {
+    this.deps = deps;
+  }
+
+  async initialize(taskPlan: TaskPlan): Promise<void> {
+    if (this.initialized) {
+      throw new TaskQueueError("Dispatcher already initialized");
+    }
+
+    // Store runId for later use
+    this.runId = taskPlan.runId;
+
+    // Save all tasks to store
+    for (const task of taskPlan.tasks) {
+      await this.deps.taskStore.save(task);
+      this.taskMap.set(task.taskId as string, task);
+    }
+
+    // Save run state
+    await this.deps.runStore.save({
+      runId: taskPlan.runId,
+      parentBranch: taskPlan.parentBranch,
+      totalTasks: taskPlan.tasks.length,
+      pending: taskPlan.tasks.length,
+      running: 0,
+      completed: 0,
+      failed: 0,
+      startTime: new Date().toISOString(),
+    });
+
+    this.initialized = true;
+
+    this.deps.eventBus.emit({
+      type: "queue:initialized",
+      totalTasks: taskPlan.tasks.length,
+    });
+
+    this.deps.logger.info(
+      { runId: taskPlan.runId, totalTasks: taskPlan.tasks.length },
+      "Dispatcher initialized"
+    );
+  }
+
+  start(): void {
+    if (!this.initialized) {
+      throw new TaskQueueError("Dispatcher not initialized");
+    }
+
+    // Listen to worker:idle events
+    this.deps.eventBus.on("worker:idle", (event) => {
+      if (event.type === "worker:idle") {
+        void this.handleWorkerIdle(event.workerId);
+      }
+    });
+
+    // Listen to task:completed events
+    this.deps.eventBus.on("task:completed", (event) => {
+      if (event.type === "task:completed") {
+        void this.handleTaskCompleted(event.taskId);
+      }
+    });
+
+    // Listen to task:failed events
+    this.deps.eventBus.on("task:failed", (event) => {
+      if (event.type === "task:failed") {
+        void this.handleTaskFailed(event.taskId, event.error);
+      }
+    });
+
+    // Start stale task detection
+    this.startStaleDetection();
+
+    this.deps.logger.info("Dispatcher started");
+
+    // Trigger initial dispatch (CRITICAL FIX #2)
+    void this.dispatchNext();
+  }
+
+  stop(): void {
+    if (this.staleCheckInterval) {
+      clearInterval(this.staleCheckInterval);
+      this.staleCheckInterval = undefined;
+    }
+
+    this.deps.logger.info("Dispatcher stopped");
+  }
+
+  async dispatchNext(): Promise<boolean> {
+    // Get ready tasks
+    const taskMapReadonly = new Map(
+      Array.from(this.taskMap.entries()).map(([k, v]) => [k as unknown as TaskId, v])
+    ) as ReadonlyMap<TaskId, Task>;
+    const readyTasks = getReadyTasks(taskMapReadonly);
+
+    if (readyTasks.length === 0) {
+      const pendingTasks = Array.from(this.taskMap.values()).filter(
+        (t) => t.status === "pending"
+      );
+
+      if (pendingTasks.length === 0) {
+        this.deps.eventBus.emit({ type: "queue:empty" });
+        return false;
+      }
+
+      // Tasks are waiting for dependencies
+      this.deps.logger.debug("No ready tasks, waiting for dependencies");
+      return false;
+    }
+
+    // Get idle workers
+    const idleWorkers = await this.deps.workerStore.getIdle();
+
+    if (idleWorkers.length === 0) {
+      this.deps.logger.debug("No idle workers available");
+      return false;
+    }
+
+    // Dispatch multiple tasks to available workers (FIX #2)
+    let dispatched = 0;
+    for (let i = 0; i < Math.min(readyTasks.length, idleWorkers.length); i++) {
+      const task = readyTasks[i];
+      const worker = idleWorkers[i];
+
+      if (!task || !worker) {
+        break;
+      }
+
+      // Update task status
+      task.status = "running";
+      task.workerId = worker.workerId;
+      task.startTime = new Date().toISOString();
+      await this.deps.taskStore.save(task);
+      this.taskMap.set(task.taskId as string, task);
+
+      // Emit dispatch event
+      this.deps.eventBus.emit({
+        type: "task:dispatched",
+        taskId: task.taskId,
+        workerId: worker.workerId,
+      });
+
+      this.deps.logger.info(
+        { taskId: task.taskId, workerId: worker.workerId },
+        "Task dispatched"
+      );
+
+      dispatched++;
+    }
+
+    this.updateProgress();
+
+    return dispatched > 0;
+  }
+
+  async handleTaskCompleted(taskId: TaskId): Promise<void> {
+    const task = this.taskMap.get(taskId as string);
+    if (!task) {
+      this.deps.logger.warn({ taskId }, "Task not found for completion");
+      return;
+    }
+
+    task.status = "completed";
+    task.endTime = new Date().toISOString();
+    await this.deps.taskStore.save(task);
+    this.taskMap.set(taskId as string, task);
+
+    this.updateProgress();
+
+    this.deps.logger.info({ taskId }, "Task completed");
+
+    // Try to dispatch next tasks
+    await this.dispatchNext();
+  }
+
+  async handleTaskFailed(taskId: TaskId, error: string): Promise<void> {
+    const task = this.taskMap.get(taskId as string);
+    if (!task) {
+      this.deps.logger.warn({ taskId }, "Task not found for failure");
+      return;
+    }
+
+    const maxRetries = this.deps.config.maxRetries ?? 2;
+
+    if (task.retryCount < maxRetries) {
+      // Retry
+      task.status = "pending";
+      task.retryCount += 1;
+      task.workerId = undefined;
+      task.failureReason = error;
+      await this.deps.taskStore.save(task);
+      this.taskMap.set(taskId as string, task);
+
+      this.deps.eventBus.emit({
+        type: "task:retry",
+        taskId,
+        retryCount: task.retryCount,
+      });
+
+      this.deps.logger.warn(
+        { taskId, retryCount: task.retryCount, error },
+        "Task failed, retrying"
+      );
+
+      // Try to dispatch
+      await this.dispatchNext();
+    } else {
+      // Failed permanently
+      task.status = "failed";
+      task.endTime = new Date().toISOString();
+      task.failureReason = error;
+      await this.deps.taskStore.save(task);
+      this.taskMap.set(taskId as string, task);
+
+      this.updateProgress();
+
+      this.deps.logger.error({ taskId, error }, "Task failed permanently");
+
+      // Cascade fail dependent tasks
+      await this.cascadeFailDependents(taskId);
+    }
+  }
+
+  getProgress(): ProgressState {
+    const tasks = Array.from(this.taskMap.values());
+    return {
+      total: tasks.length,
+      pending: tasks.filter((t) => t.status === "pending").length,
+      running: tasks.filter((t) => t.status === "running").length,
+      completed: tasks.filter((t) => t.status === "completed").length,
+      failed: tasks.filter((t) => t.status === "failed").length,
+    };
+  }
+
+  private async handleWorkerIdle(workerId: WorkerId): Promise<void> {
+    this.deps.logger.debug({ workerId: workerId as string }, "Worker idle, attempting dispatch");
+    await this.dispatchNext();
+  }
+
+  private async cascadeFailDependents(failedTaskId: TaskId): Promise<void> {
+    // Find all tasks that depend on the failed task
+    for (const task of this.taskMap.values()) {
+      if (task.dependsOn.includes(failedTaskId) && task.status === "pending") {
+        task.status = "failed";
+        task.failureReason = `Dependency ${failedTaskId as string} failed`;
+        task.endTime = new Date().toISOString();
+        await this.deps.taskStore.save(task);
+        this.taskMap.set(task.taskId as string, task);
+
+        this.deps.logger.warn(
+          { taskId: task.taskId, failedDep: failedTaskId },
+          "Task failed due to dependency failure"
+        );
+
+        // Recursively fail dependents
+        await this.cascadeFailDependents(task.taskId);
+      }
+    }
+
+    this.updateProgress();
+  }
+
+  private updateProgress(): void {
+    const progress = this.getProgress();
+
+    this.deps.eventBus.emit({
+      type: "progress:updated",
+      state: progress,
+    });
+
+    // Emit run:completed if all tasks are done (FIX #1)
+    if (progress.pending === 0 && progress.running === 0) {
+      if (this.runId) {
+        this.deps.eventBus.emit({
+          type: "run:completed",
+          runId: this.runId,
+        });
+
+        this.deps.logger.info(
+          { runId: this.runId, completed: progress.completed, failed: progress.failed },
+          "Run completed"
+        );
+      }
+    }
+  }
+
+  private startStaleDetection(): void {
+    const interval = this.deps.config.staleTaskCheckInterval ?? 60000; // 60s default
+
+    this.staleCheckInterval = setInterval(() => {
+      this.detectStaleTasks();
+    }, interval);
+  }
+
+  private detectStaleTasks(): void {
+    const staleThreshold = this.deps.config.staleTaskThreshold ?? 300000; // 5 minutes
+    const now = Date.now();
+
+    for (const task of this.taskMap.values()) {
+      if (task.status === "running" && task.startTime) {
+        const startTime = new Date(task.startTime).getTime();
+        const elapsed = now - startTime;
+
+        if (elapsed > staleThreshold) {
+          this.deps.eventBus.emit({
+            type: "task:stale",
+            taskId: task.taskId,
+            elapsed,
+          });
+
+          this.deps.logger.warn(
+            { taskId: task.taskId, elapsed },
+            "Stale task detected"
+          );
+        }
+      }
+    }
+  }
+}

package/src/modules/task-queue/index.ts

@@ -0,0 +1,16 @@
+export { parseTask, serializeTask, TaskJsonSchema } from "./task";
+export type { TaskJson } from "./task";
+
+export { parseTaskPlan, loadTaskPlan } from "./task-plan";
+export type { TaskPlanJson } from "./task-plan";
+
+export {
+  checkDependencies,
+  detectCircularDependencies,
+  getReadyTasks,
+  validateTaskPlan,
+} from "./dependency-resolver";
+export type { DependencyStatus, DependencyResult } from "./dependency-resolver";
+
+export { Dispatcher } from "./dispatcher";
+export type { DispatcherDeps, TaskStore, WorkerStore, RunStore } from "./dispatcher";

package/src/modules/task-queue/task-plan.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { createRunId, type TaskPlan } from "@aad/shared/types";
+import { parseTask, TaskJsonSchema } from "./task";
+
+/**
+ * TaskPlan JSON schema (snake_case from Bash scripts)
+ */
+const TaskPlanJsonSchema = z.object({
+  run_id: z.string().transform((id) => createRunId(id)),
+  parent_branch: z.string(),
+  title: z.string().optional(),
+  description: z.string().optional(),
+  tasks: z.array(TaskJsonSchema),
+});
+
+export type TaskPlanJson = z.input<typeof TaskPlanJsonSchema>;
+
+/**
+ * Parse task_plan.json to TaskPlan domain model
+ */
+export function parseTaskPlan(json: unknown): TaskPlan {
+  const parsed = TaskPlanJsonSchema.parse(json);
+
+  return {
+    runId: parsed.run_id,
+    parentBranch: parsed.parent_branch,
+    title: parsed.title,
+    description: parsed.description,
+    tasks: parsed.tasks.map((taskJson) => parseTask(taskJson)),
+  };
+}
+
+/**
+ * Load and parse task_plan.json from file
+ */
+export async function loadTaskPlan(filePath: string): Promise<TaskPlan> {
+  const content = await Bun.file(filePath).text();
+  const json = JSON.parse(content);
+  return parseTaskPlan(json);
+}

package/src/modules/task-queue/task.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+import { createTaskId, createWorkerId, type Task, type TaskStatus } from "@aad/shared/types";
+
+/**
+ * Task schema for JSON deserialization
+ * Handles snake_case to camelCase conversion
+ */
+const TaskStatusSchema = z.enum(["pending", "running", "completed", "failed"]);
+
+export const TaskJsonSchema = z.object({
+  task_id: z.string().transform((id) => createTaskId(id)),
+  title: z.string(),
+  description: z.string(),
+  files_to_modify: z.array(z.string()),
+  depends_on: z.array(z.string()).transform((ids) => ids.map((id) => createTaskId(id))),
+  priority: z.number(),
+  status: TaskStatusSchema.optional().default("pending"),
+  worker_id: z.string().optional(),
+  start_time: z.string().optional(),
+  end_time: z.string().optional(),
+  retry_count: z.number().optional().default(0),
+  failure_reason: z.string().optional(),
+});
+
+export type TaskJson = z.input<typeof TaskJsonSchema>;
+
+/**
+ * Parse task from snake_case JSON to Task domain model
+ */
+export function parseTask(json: unknown): Task {
+  const parsed = TaskJsonSchema.parse(json);
+
+  return {
+    taskId: parsed.task_id,
+    title: parsed.title,
+    description: parsed.description,
+    filesToModify: parsed.files_to_modify,
+    dependsOn: parsed.depends_on,
+    priority: parsed.priority,
+    status: parsed.status as TaskStatus,
+    workerId: parsed.worker_id ? createWorkerId(parsed.worker_id) : undefined,
+    startTime: parsed.start_time,
+    endTime: parsed.end_time,
+    retryCount: parsed.retry_count,
+    failureReason: parsed.failure_reason,
+  };
+}
+
+/**
+ * Serialize Task to snake_case JSON
+ */
+export function serializeTask(task: Task): Record<string, unknown> {
+  return {
+    task_id: task.taskId,
+    title: task.title,
+    description: task.description,
+    files_to_modify: task.filesToModify,
+    depends_on: task.dependsOn,
+    priority: task.priority,
+    status: task.status,
+    worker_id: task.workerId,
+    start_time: task.startTime,
+    end_time: task.endTime,
+    retry_count: task.retryCount,
+    failure_reason: task.failureReason,
+  };
+}

package/src/shared/__tests__/config.test.ts

@@ -0,0 +1,204 @@
+import { describe, test, expect } from "bun:test";
+import { loadConfig } from "../config";
+import { ConfigError } from "../errors";
+
+describe("loadConfig", () => {
+  test("loads config with default values when no env vars set", () => {
+    const config = loadConfig({});
+
+    expect(config.workers.num).toBe(2);
+    expect(config.workers.max).toBe(8);
+    expect(config.models.default).toBeUndefined();
+    expect(config.models.splitter).toBeUndefined();
+    expect(config.models.tester).toBeUndefined();
+    expect(config.models.implementer).toBeUndefined();
+    expect(config.models.reviewer).toBeUndefined();
+    expect(config.models.mergeResolver).toBeUndefined();
+    expect(config.models.branchName).toBeUndefined();
+    expect(config.timeouts.claude).toBe(1200);
+    expect(config.timeouts.test).toBe(600);
+    expect(config.timeouts.staleTask).toBe(5400);
+    expect(config.retry.maxRetries).toBe(2);
+    expect(config.debug).toBe(false);
+    expect(config.adaptiveEffort).toBe(false);
+    expect(config.teams.splitter).toBe(false);
+    expect(config.teams.reviewer).toBe(false);
+    expect(config.memorySync).toBe(true);
+    expect(config.dashboard.enabled).toBe(true);
+    expect(config.dashboard.port).toBe(7333);
+    expect(config.dashboard.host).toBe("localhost");
+  });
+
+  test("loads config from env vars", () => {
+    const config = loadConfig({
+      AAD_NUM_WORKERS: "4",
+      AAD_MAX_WORKERS: "16",
+      AAD_MODEL: "opus",
+      AAD_MODEL_SPLITTER: "sonnet",
+      AAD_MODEL_TESTER: "sonnet",
+      AAD_MODEL_IMPLEMENTER: "sonnet",
+      AAD_MODEL_REVIEWER: "opus",
+      AAD_MODEL_MERGE: "haiku",
+      AAD_MODEL_BRANCH_NAME: "haiku",
+      CLAUDE_TIMEOUT: "1800",
+      TEST_TIMEOUT: "900",
+      AAD_STALE_TASK_TIMEOUT: "7200",
+      MAX_PHASE_RETRIES: "3",
+      DEBUG: "1",
+      AAD_ADAPTIVE_EFFORT: "1",
+      AAD_USE_TEAMS_FOR_SPLITTER: "1",
+      AAD_USE_TEAMS_FOR_REVIEW: "1",
+      AAD_MEMORY_SYNC_ENABLED: "0",
+    });
+
+    expect(config.workers.num).toBe(4);
+    expect(config.workers.max).toBe(16);
+    expect(config.models.default).toBe("opus");
+    expect(config.models.splitter).toBe("sonnet");
+    expect(config.models.tester).toBe("sonnet");
+    expect(config.models.implementer).toBe("sonnet");
+    expect(config.models.reviewer).toBe("opus");
+    expect(config.models.mergeResolver).toBe("haiku");
+    expect(config.models.branchName).toBe("haiku");
+    expect(config.timeouts.claude).toBe(1800);
+    expect(config.timeouts.test).toBe(900);
+    expect(config.timeouts.staleTask).toBe(7200);
+    expect(config.retry.maxRetries).toBe(3);
+    expect(config.debug).toBe(true);
+    expect(config.adaptiveEffort).toBe(true);
+    expect(config.teams.splitter).toBe(true);
+    expect(config.teams.reviewer).toBe(true);
+    expect(config.memorySync).toBe(false);
+  });
+
+  test("throws ConfigError when AAD_NUM_WORKERS exceeds AAD_MAX_WORKERS", () => {
+    expect(() => {
+      loadConfig({
+        AAD_NUM_WORKERS: "10",
+        AAD_MAX_WORKERS: "8",
+      });
+    }).toThrow(ConfigError);
+  });
+
+  test("throws ConfigError for invalid AAD_NUM_WORKERS", () => {
+    expect(() => {
+      loadConfig({
+        AAD_NUM_WORKERS: "invalid",
+      });
+    }).toThrow(ConfigError);
+  });
+
+  test("throws ConfigError for negative AAD_NUM_WORKERS", () => {
+    expect(() => {
+      loadConfig({
+        AAD_NUM_WORKERS: "-1",
+      });
+    }).toThrow(ConfigError);
+  });
+
+  test("throws ConfigError for invalid CLAUDE_TIMEOUT", () => {
+    expect(() => {
+      loadConfig({
+        CLAUDE_TIMEOUT: "not-a-number",
+      });
+    }).toThrow(ConfigError);
+  });
+
+  test("uses process.env when no env parameter provided", () => {
+    const originalNumWorkers = process.env.AAD_NUM_WORKERS;
+    const originalMaxWorkers = process.env.AAD_MAX_WORKERS;
+    process.env.AAD_NUM_WORKERS = "3";
+    process.env.AAD_MAX_WORKERS = "8";
+
+    const config = loadConfig();
+    expect(config.workers.num).toBe(3);
+
+    if (originalNumWorkers !== undefined) {
+      process.env.AAD_NUM_WORKERS = originalNumWorkers;
+    } else {
+      delete process.env.AAD_NUM_WORKERS;
+    }
+    if (originalMaxWorkers !== undefined) {
+      process.env.AAD_MAX_WORKERS = originalMaxWorkers;
+    } else {
+      delete process.env.AAD_MAX_WORKERS;
+    }
+  });
+
+  test("accepts valid model names", () => {
+    const config = loadConfig({
+      AAD_MODEL: "claude-sonnet-4-5-20250929",
+      AAD_MODEL_SPLITTER: "claude-opus-4-6",
+      AAD_MODEL_MERGE: "claude-haiku-4-5-20251001",
+    });
+
+    expect(config.models.default).toBe("claude-sonnet-4-5-20250929");
+    expect(config.models.splitter).toBe("claude-opus-4-6");
+    expect(config.models.mergeResolver).toBe("claude-haiku-4-5-20251001");
+  });
+
+  test("accepts short model names", () => {
+    const config = loadConfig({
+      AAD_MODEL: "sonnet",
+      AAD_MODEL_SPLITTER: "opus",
+      AAD_MODEL_MERGE: "haiku",
+    });
+
+    expect(config.models.default).toBe("sonnet");
+    expect(config.models.splitter).toBe("opus");
+    expect(config.models.mergeResolver).toBe("haiku");
+  });
+
+  test("loads dashboard config from env vars", () => {
+    const config = loadConfig({
+      AAD_DASHBOARD_PORT: "4444",
+      AAD_DASHBOARD_ENABLED: "0",
+      AAD_DASHBOARD_HOST: "0.0.0.0",
+    });
+
+    expect(config.dashboard.port).toBe(4444);
+    expect(config.dashboard.enabled).toBe(false);
+    expect(config.dashboard.host).toBe("0.0.0.0");
+  });
+
+  test("uses dashboard defaults when env vars not set", () => {
+    const config = loadConfig({});
+
+    expect(config.dashboard.enabled).toBe(true);
+    expect(config.dashboard.port).toBe(7333);
+    expect(config.dashboard.host).toBe("localhost");
+  });
+
+  test("loads repos from AAD_REPOS env var", () => {
+    const config = loadConfig({ AAD_REPOS: "/tmp/repo-a, /tmp/repo-b" });
+
+    expect(config.repos).toHaveLength(2);
+    expect(config.repos![0]!.path).toBe("/tmp/repo-a");
+    expect(config.repos![1]!.path).toBe("/tmp/repo-b");
+  });
+
+  test("repos is undefined when AAD_REPOS not set", () => {
+    const config = loadConfig({});
+    expect(config.repos).toBeUndefined();
+  });
+
+  test("loads multiRepoStrategy from env", () => {
+    const config = loadConfig({ AAD_MULTI_REPO_STRATEGY: "coordinated" });
+    expect(config.multiRepoStrategy).toBe("coordinated");
+  });
+
+  test("multiRepoStrategy is undefined when not set", () => {
+    const config = loadConfig({});
+    expect(config.multiRepoStrategy).toBeUndefined();
+  });
+
+  test("loads plugins from AAD_PLUGINS env var", () => {
+    const config = loadConfig({ AAD_PLUGINS: "./my-plugin.ts, /abs/plugin.ts" });
+    expect(config.plugins).toEqual(["./my-plugin.ts", "/abs/plugin.ts"]);
+  });
+
+  test("plugins is undefined when AAD_PLUGINS not set", () => {
+    const config = loadConfig({});
+    expect(config.plugins).toBeUndefined();
+  });
+});