ndomo 0.1.0 → 0.2.1

package/src/lib.ts

@@ -1,65 +0,0 @@
-/**
- * ndomo — OpenCode multi-agent orchestrator.
- *
- * Entry point that re-exports all public APIs.
- *
- * @example
- * ```ts
- * import { routeTask, BackgroundDispatcher, cavemanCompress } from "ndomo";
- * ```
- */
-
-// Memory: scoped tag helpers
-export {
-  getAllTags,
-  getProjectTag,
-  getUserTag,
-  memoryAddOptions,
-  memorySearchOptions,
-} from "./mem/scoped.ts";
-
-// Orchestrator: background dispatcher
-export {
-  BackgroundDispatcher,
-  type BackgroundTask,
-  type DispatchOptions,
-} from "./orchestrator/background.ts";
-// Orchestrator: memory hooks
-export {
-  cavemanCompress,
-  type MemoryEntry,
-  prepareForMemory,
-  shouldStoreMemory,
-} from "./orchestrator/memory-hook.ts";
-// Orchestrator: result reconciliation
-export {
-  type ReconciliationReport,
-  reconcileResults,
-  type TaskResult,
-} from "./orchestrator/reconciler.ts";
-// Orchestrator: scheduler
-export {
-  canRunParallel,
-  type RoutingDecision,
-  routeTask,
-  type TaskRequest,
-} from "./orchestrator/scheduler.ts";
-
-// Worktrees: git worktree manager
-export {
-  cleanup,
-  createWorktree,
-  getWorktree,
-  listActive,
-  loadState,
-  removeWorktree,
-  saveState,
-  type Worktree,
-  type WorktreeState,
-} from "./worktrees/manager.ts";
-
-// Worktrees: integrity verification
-export {
-  type IntegrityReport,
-  verifyIntegrity,
-} from "./worktrees/state.ts";

package/src/mem/scoped.ts

@@ -1,65 +0,0 @@
-/**
- * Project-scoped memory helpers wrapping opencode-mem/tags.
- * Provides convenience functions for tag resolution and memory operations.
- */
-
-import { getProjectTagInfo, getTags, getUserTagInfo } from "opencode-mem/tags";
-
-/**
- * Get the project tag for the current (or specified) working directory.
- *
- * @param cwd - Working directory. Defaults to process.cwd().
- * @returns Project tag string (e.g. "project:ndomo:abc123").
- */
-export function getProjectTag(cwd?: string): string {
-  return getProjectTagInfo(cwd ?? process.cwd()).tag;
-}
-
-/**
- * Get the user tag for the current system user.
- *
- * @returns User tag string (e.g. "user:nico:xyz789").
- */
-export function getUserTag(): string {
-  return getUserTagInfo().tag;
-}
-
-/**
- * Get both user and project tags for a directory.
- *
- * @param cwd - Working directory. Defaults to process.cwd().
- * @returns Object with user and project TagInfo.
- */
-export function getAllTags(cwd?: string) {
-  return getTags(cwd ?? process.cwd());
-}
-
-/**
- * Build options object for a memory search operation.
- *
- * @param query - Search query text.
- * @param scope - Search scope: "project" (default) or "all-projects".
- * @returns Options object for the opencode-mem search API.
- */
-export function memorySearchOptions(query: string, scope: "project" | "all-projects" = "project") {
-  return {
-    mode: "search" as const,
-    query,
-    scope,
-  };
-}
-
-/**
- * Build options object for a memory add operation.
- *
- * @param content - Content to store in memory.
- * @param topic - Topic/category for the memory entry.
- * @returns Options object for the opencode-mem add API.
- */
-export function memoryAddOptions(content: string, topic: string) {
-  return {
-    mode: "add" as const,
-    content,
-    topic,
-  };
-}

package/src/orchestrator/background.test.ts

@@ -1,268 +0,0 @@
-import { Database } from "bun:sqlite";
-import { beforeEach, describe, expect, test } from "bun:test";
-import { runMigrations } from "../db/migrations.ts";
-import { BackgroundDispatcher } from "./background.ts";
-
-/** UUID v4 regex: 8-4-4-4-12 hex chars. */
-const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-
-function createTestDb(): Database {
-  const db = new Database(":memory:");
-  db.exec("PRAGMA foreign_keys = ON");
-  runMigrations(db);
-  return db;
-}
-
-describe("BackgroundDispatcher", () => {
-  let db: Database;
-  let dispatcher: BackgroundDispatcher;
-
-  beforeEach(() => {
-    db = createTestDb();
-    dispatcher = new BackgroundDispatcher(db);
-  });
-
-  // 1. dispatch returns a UUID v4
-  test("dispatch returns a UUID v4", () => {
-    const id = dispatcher.dispatch({ agent: "scout", description: "Find auth flow" });
-    expect(id).toMatch(UUID_RE);
-  });
-
-  // 2. getStatus returns dispatched task with status='pending'
-  test("getStatus returns pending task after dispatch", () => {
-    const id = dispatcher.dispatch({ agent: "scout", description: "Find auth flow" });
-    const task = dispatcher.getStatus(id);
-    expect(task).toBeDefined();
-    expect(task!.id).toBe(id);
-    expect(task!.status).toBe("pending");
-    expect(task!.agent).toBe("scout");
-    expect(task!.description).toBe("Find auth flow");
-    expect(task!.createdAt).toBeGreaterThan(0);
-  });
-
-  // 3. markRunning transitions to 'running' + sets sessionId + startedAt
-  test("markRunning transitions to running with sessionId", () => {
-    const id = dispatcher.dispatch({ agent: "smith", description: "Refactor utils" });
-    dispatcher.markRunning(id, "session-abc");
-    const task = dispatcher.getStatus(id);
-    expect(task!.status).toBe("running");
-    expect(task!.sessionId).toBe("session-abc");
-    expect(task!.startedAt).toBeGreaterThan(0);
-  });
-
-  // 4. markComplete transitions to 'completed' + sets result + completedAt
-  test("markComplete transitions to completed with result", () => {
-    const id = dispatcher.dispatch({ agent: "smith", description: "Fix bug" });
-    dispatcher.markRunning(id, "session-1");
-    dispatcher.markComplete(id, "Fixed in src/utils.ts");
-    const task = dispatcher.getStatus(id);
-    expect(task!.status).toBe("completed");
-    expect(task!.result).toBe("Fixed in src/utils.ts");
-    expect(task!.completedAt).toBeGreaterThan(0);
-  });
-
-  // 5. markFailed transitions to 'failed' + sets error + completedAt
-  test("markFailed transitions to failed with error", () => {
-    const id = dispatcher.dispatch({ agent: "scout", description: "Scan deps" });
-    dispatcher.markFailed(id, "timeout after 30s");
-    const task = dispatcher.getStatus(id);
-    expect(task!.status).toBe("failed");
-    expect(task!.result).toBe("timeout after 30s");
-    expect(task!.completedAt).toBeGreaterThan(0);
-  });
-
-  // 6. getActive returns only pending+running (not completed/failed/cancelled)
-  test("getActive returns only pending and running tasks", () => {
-    const id1 = dispatcher.dispatch({ agent: "a", description: "task1" });
-    const id2 = dispatcher.dispatch({ agent: "a", description: "task2" });
-    const id3 = dispatcher.dispatch({ agent: "a", description: "task3" });
-    const id4 = dispatcher.dispatch({ agent: "a", description: "task4" });
-
-    dispatcher.markRunning(id2, "s1");
-    dispatcher.markComplete(id3, "done");
-    dispatcher.markFailed(id4, "err");
-
-    const active = dispatcher.getActive();
-    const activeIds = active.map((t) => t.id);
-    expect(activeIds).toContain(id1);
-    expect(activeIds).toContain(id2);
-    expect(activeIds).not.toContain(id3);
-    expect(activeIds).not.toContain(id4);
-    expect(active).toHaveLength(2);
-  });
-
-  // 7. reconcile returns completed+failed tasks
-  test("reconcile returns completed and failed tasks", () => {
-    const id1 = dispatcher.dispatch({ agent: "a", description: "t1" });
-    const id2 = dispatcher.dispatch({ agent: "a", description: "t2" });
-    const id3 = dispatcher.dispatch({ agent: "a", description: "t3" });
-
-    dispatcher.markComplete(id1, "ok");
-    dispatcher.markFailed(id2, "err");
-    // id3 stays pending
-
-    const finished = dispatcher.reconcile();
-    const finishedIds = finished.map((t) => t.id);
-    expect(finishedIds).toContain(id1);
-    expect(finishedIds).toContain(id2);
-    expect(finishedIds).not.toContain(id3);
-    expect(finished).toHaveLength(2);
-  });
-
-  // 8. remove deletes the task
-  test("remove deletes the task", () => {
-    const id = dispatcher.dispatch({ agent: "a", description: "disposable" });
-    expect(dispatcher.getStatus(id)).toBeDefined();
-    dispatcher.remove(id);
-    expect(dispatcher.getStatus(id)).toBeUndefined();
-  });
-
-  // 9. stats returns correct counts per status
-  test("stats returns correct counts per status", () => {
-    dispatcher.dispatch({ agent: "a", description: "p1" });
-    const id2 = dispatcher.dispatch({ agent: "a", description: "p2" });
-    const id3 = dispatcher.dispatch({ agent: "a", description: "p3" });
-    const id4 = dispatcher.dispatch({ agent: "a", description: "p4" });
-    const id5 = dispatcher.dispatch({ agent: "a", description: "p5" });
-
-    dispatcher.markRunning(id2, "s");
-    dispatcher.markComplete(id3, "ok");
-    dispatcher.markFailed(id4, "err");
-    dispatcher.cancel(id5);
-
-    const s = dispatcher.stats();
-    expect(s.pending).toBe(1);
-    expect(s.running).toBe(1);
-    expect(s.completed).toBe(1);
-    expect(s.failed).toBe(1);
-    expect(s.cancelled).toBe(1);
-  });
-
-  // 10. cancel on pending task → returns true, status='cancelled'
-  test("cancel on pending task returns true and sets cancelled", () => {
-    const id = dispatcher.dispatch({ agent: "a", description: "cancel me" });
-    const result = dispatcher.cancel(id);
-    expect(result).toBe(true);
-    const task = dispatcher.getStatus(id);
-    expect(task!.status).toBe("cancelled");
-    expect(task!.completedAt).toBeGreaterThan(0);
-  });
-
-  // 11. cancel on completed task → returns false (already terminal)
-  test("cancel on completed task returns false", () => {
-    const id = dispatcher.dispatch({ agent: "a", description: "done already" });
-    dispatcher.markComplete(id, "finished");
-    const result = dispatcher.cancel(id);
-    expect(result).toBe(false);
-    const task = dispatcher.getStatus(id);
-    expect(task!.status).toBe("completed"); // unchanged
-  });
-
-  // 12. listByAgent returns only tasks for that agent, newest first
-  test("listByAgent filters by agent and orders by created_at DESC", () => {
-    dispatcher.dispatch({ agent: "scout", description: "first" });
-    dispatcher.dispatch({ agent: "smith", description: "other" });
-    dispatcher.dispatch({ agent: "scout", description: "third" });
-
-    const scoutTasks = dispatcher.listByAgent("scout");
-    expect(scoutTasks).toHaveLength(2);
-    // All returned tasks belong to scout
-    expect(scoutTasks.every((t) => t.agent === "scout")).toBe(true);
-    const descriptions = scoutTasks.map((t) => t.description).sort();
-    expect(descriptions).toEqual(["first", "third"]);
-    // smith tasks not included
-    expect(scoutTasks.some((t) => t.agent === "smith")).toBe(false);
-  });
-
-  // 13. dispatch with files+worktree options → persisted and retrievable
-  test("dispatch with files and worktree persists them", () => {
-    const id = dispatcher.dispatch({
-      agent: "painter",
-      description: "redesign nav",
-      files: ["src/nav.ts", "src/sidebar.ts"],
-      worktree: "/tmp/wt/nav-redesign",
-    });
-    const task = dispatcher.getStatus(id);
-    expect(task!.files).toEqual(["src/nav.ts", "src/sidebar.ts"]);
-    expect(task!.worktree).toBe("/tmp/wt/nav-redesign");
-  });
-
-  // 15. finalize deletes terminal tasks older than threshold
-  test("finalize deletes terminal tasks older than threshold", () => {
-    const now = Date.now();
-    const twoHoursAgo = now - 2 * 60 * 60 * 1000;
-    const thirtyMinAgo = now - 30 * 60 * 1000;
-    const insertSql = `INSERT INTO background_tasks
-      (id, agent, description, status, started_at, completed_at, created_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?)`;
-    db.prepare(insertSql).run(
-      "old1",
-      "a",
-      "t1",
-      "completed",
-      twoHoursAgo,
-      twoHoursAgo,
-      twoHoursAgo,
-    );
-    db.prepare(insertSql).run("old2", "a", "t2", "failed", twoHoursAgo, twoHoursAgo, twoHoursAgo);
-    db.prepare(insertSql).run(
-      "old3",
-      "a",
-      "t3",
-      "cancelled",
-      twoHoursAgo,
-      twoHoursAgo,
-      twoHoursAgo,
-    );
-    db.prepare(insertSql).run(
-      "fresh",
-      "a",
-      "t4",
-      "completed",
-      thirtyMinAgo,
-      thirtyMinAgo,
-      thirtyMinAgo,
-    );
-    db.prepare(insertSql).run("live", "a", "t5", "running", thirtyMinAgo, null, thirtyMinAgo);
-
-    const deleted = dispatcher.finalize(60 * 60 * 1000); // 1h cutoff
-    expect(deleted).toBe(3);
-
-    expect(dispatcher.getStatus("old1")).toBeUndefined();
-    expect(dispatcher.getStatus("old2")).toBeUndefined();
-    expect(dispatcher.getStatus("old3")).toBeUndefined();
-    expect(dispatcher.getStatus("fresh")?.status).toBe("completed");
-    expect(dispatcher.getStatus("live")?.status).toBe("running");
-  });
-
-  test("finalize is a no-op when no terminal tasks exceed threshold", () => {
-    const id = dispatcher.dispatch({ agent: "a", description: "fresh" });
-    dispatcher.markComplete(id, "done");
-
-    const deleted = dispatcher.finalize(60 * 60 * 1000);
-    expect(deleted).toBe(0);
-    expect(dispatcher.getStatus(id)).toBeDefined();
-  });
-
-  test("finalize does NOT delete pending or running tasks regardless of age", () => {
-    const id = dispatcher.dispatch({ agent: "a", description: "stale pending" });
-    // Manually backdate created_at to long ago — finalize must not touch it
-    const longAgo = Date.now() - 7 * 24 * 60 * 60 * 1000;
-    db.prepare("UPDATE background_tasks SET created_at = ? WHERE id = ?").run(longAgo, id);
-
-    const deleted = dispatcher.finalize(1000); // 1 second cutoff
-    expect(deleted).toBe(0);
-    expect(dispatcher.getStatus(id)?.status).toBe("pending");
-  });
-
-  // 14. Persistence: new BackgroundDispatcher with SAME db → task still exists
-  test("new BackgroundDispatcher with same db sees existing tasks", () => {
-    const id = dispatcher.dispatch({ agent: "scout", description: "persist me" });
-    // Create a NEW dispatcher with the same db
-    const dispatcher2 = new BackgroundDispatcher(db);
-    const task = dispatcher2.getStatus(id);
-    expect(task).toBeDefined();
-    expect(task!.description).toBe("persist me");
-    expect(task!.status).toBe("pending");
-  });
-});

package/src/orchestrator/background.ts

@@ -1,293 +0,0 @@
-/**
- * Background task dispatcher for the ndomo orchestrator.
- * Tracks state of tasks delegated to specialist agents.
- *
- * DB-backed via bun:sqlite — persists across restarts.
- * The actual OpenCode task tool call is made by the foreman prompt —
- * this class is a pure state tracker, not an I/O layer.
- */
-
-import type { Database } from "bun:sqlite";
-
-/** Current state of a background task. */
-export interface BackgroundTask {
-  /** Unique task identifier (UUID v4). */
-  id: string;
-  /** Agent handling this task. */
-  agent: string;
-  /** What the agent is doing. */
-  description: string;
-  /** Lifecycle status. */
-  status: "pending" | "running" | "completed" | "failed" | "cancelled";
-  /** OpenCode session ID once the task is dispatched. */
-  sessionId?: string;
-  /** Agent output after completion. */
-  result?: string;
-  /** Epoch ms when the task was dispatched. */
-  startedAt?: number;
-  /** Epoch ms when the task finished (success or failure). */
-  completedAt?: number;
-  /** Epoch ms when the task was created. */
-  createdAt: number;
-  /** Files the agent should focus on. */
-  files?: string[];
-  /** Git worktree path for isolation. */
-  worktree?: string;
-}
-
-/** Options for dispatching a new background task. */
-export interface DispatchOptions {
-  /** Which agent should handle this. */
-  agent: string;
-  /** Task description for the agent. */
-  description: string;
-  /** Files the agent should focus on. */
-  files?: string[];
-  /** Git worktree path for isolation (optional). */
-  worktree?: string;
-}
-
-/** DB row shape from background_tasks table (snake_case). */
-interface BackgroundTaskRow {
-  id: string;
-  agent: string;
-  description: string;
-  status: string;
-  session_id: string | null;
-  result: string | null;
-  started_at: number | null;
-  completed_at: number | null;
-  created_at: number;
-  files: string | null;
-  worktree: string | null;
-}
-
-/**
- * Background task state tracker backed by bun:sqlite.
- *
- * Usage:
- * ```ts
- * const dispatcher = new BackgroundDispatcher(db);
- * const id = dispatcher.dispatch({ agent: "scout", description: "Find auth flow" });
- * // ... later, when the task completes ...
- * dispatcher.markComplete(id, "Found auth in src/auth/middleware.ts");
- * ```
- */
-export class BackgroundDispatcher {
-  constructor(private db: Database) {}
-
-  /**
-   * Convert a DB row to a BackgroundTask object.
-   * Deserializes JSON fields (files).
-   */
-  private rowToTask(row: BackgroundTaskRow): BackgroundTask {
-    const task: BackgroundTask = {
-      id: row.id,
-      agent: row.agent,
-      description: row.description,
-      status: row.status as BackgroundTask["status"],
-      createdAt: row.created_at,
-    };
-    if (row.session_id != null) task.sessionId = row.session_id;
-    if (row.result != null) task.result = row.result;
-    if (row.started_at != null) task.startedAt = row.started_at;
-    if (row.completed_at != null) task.completedAt = row.completed_at;
-    if (row.files != null) {
-      try {
-        task.files = JSON.parse(row.files) as string[];
-      } catch {
-        task.files = [];
-      }
-    }
-    if (row.worktree != null) task.worktree = row.worktree;
-    return task;
-  }
-
-  /**
-   * Register a new background task and return its ID.
-   * The task starts in "pending" status — the foreman is responsible
-   * for calling markRunning() once the OpenCode task tool is invoked.
-   *
-   * @param options - Task configuration.
-   * @returns Unique task ID (UUID v4).
-   */
-  dispatch(options: DispatchOptions): string {
-    const id = crypto.randomUUID();
-    this.db
-      .query(
-        "INSERT INTO background_tasks (id, agent, description, status, files, worktree) VALUES (?, ?, ?, 'pending', ?, ?)",
-      )
-      .run(
-        id,
-        options.agent,
-        options.description,
-        options.files ? JSON.stringify(options.files) : null,
-        options.worktree ?? null,
-      );
-    return id;
-  }
-
-  /**
-   * Transition a task to "running" status.
-   *
-   * @param taskId - Task to update.
-   * @param sessionId - OpenCode session ID.
-   */
-  markRunning(taskId: string, sessionId: string): void {
-    this.db
-      .query(
-        "UPDATE background_tasks SET status = 'running', session_id = ?, started_at = ? WHERE id = ?",
-      )
-      .run(sessionId, Date.now(), taskId);
-  }
-
-  /**
-   * Get the current state of a task.
-   *
-   * @param taskId - Task ID to look up.
-   * @returns Task state or undefined if not found.
-   */
-  getStatus(taskId: string): BackgroundTask | undefined {
-    const row = this.db
-      .query("SELECT * FROM background_tasks WHERE id = ?")
-      .get(taskId) as BackgroundTaskRow | null;
-    return row ? this.rowToTask(row) : undefined;
-  }
-
-  /**
-   * Get all tasks that are currently pending or running.
-   *
-   * @returns Array of active tasks.
-   */
-  getActive(): BackgroundTask[] {
-    const rows = this.db
-      .query("SELECT * FROM background_tasks WHERE status IN ('pending', 'running')")
-      .all() as BackgroundTaskRow[];
-    return rows.map((r) => this.rowToTask(r));
-  }
-
-  /**
-   * Mark a task as successfully completed.
-   *
-   * @param taskId - Task to update.
-   * @param result - Agent output.
-   */
-  markComplete(taskId: string, result: string): void {
-    this.db
-      .query(
-        "UPDATE background_tasks SET status = 'completed', result = ?, completed_at = ? WHERE id = ?",
-      )
-      .run(result, Date.now(), taskId);
-  }
-
-  /**
-   * Mark a task as failed.
-   *
-   * @param taskId - Task to update.
-   * @param error - Error description.
-   */
-  markFailed(taskId: string, error: string): void {
-    this.db
-      .query(
-        "UPDATE background_tasks SET status = 'failed', result = ?, completed_at = ? WHERE id = ?",
-      )
-      .run(error, Date.now(), taskId);
-  }
-
-  /**
-   * Return completed or failed tasks that haven't been reconciled yet.
-   * After calling this, the caller should process results and clear them.
-   *
-   * @returns Array of finished tasks.
-   */
-  reconcile(): BackgroundTask[] {
-    const rows = this.db
-      .query("SELECT * FROM background_tasks WHERE status IN ('completed', 'failed')")
-      .all() as BackgroundTaskRow[];
-    return rows.map((r) => this.rowToTask(r));
-  }
-
-  /**
-   * Remove a task from tracking (after reconciliation).
-   *
-   * @param taskId - Task to remove.
-   */
-  remove(taskId: string): void {
-    this.db.query("DELETE FROM background_tasks WHERE id = ?").run(taskId);
-  }
-
-  /**
-   * Get count of tasks by status.
-   */
-  stats(): {
-    pending: number;
-    running: number;
-    completed: number;
-    failed: number;
-    cancelled: number;
-  } {
-    const rows = this.db
-      .query("SELECT status, COUNT(*) as count FROM background_tasks GROUP BY status")
-      .all() as Array<{ status: string; count: number }>;
-
-    const counts = { pending: 0, running: 0, completed: 0, failed: 0, cancelled: 0 };
-    for (const row of rows) {
-      if (row.status in counts) {
-        counts[row.status as keyof typeof counts] = row.count;
-      }
-    }
-    return counts;
-  }
-
-  /**
-   * Cancel a pending or running task.
-   *
-   * @param taskId - Task to cancel.
-   * @returns true if the task was cancelled, false if it was already terminal.
-   */
-  cancel(taskId: string): boolean {
-    const result = this.db
-      .query(
-        "UPDATE background_tasks SET status = 'cancelled', completed_at = ? WHERE id = ? AND status IN ('pending', 'running')",
-      )
-      .run(Date.now(), taskId);
-    return result.changes > 0;
-  }
-
-  /**
-   * Delete terminal (completed/failed/cancelled) tasks older than `maxAgeMs`.
-   * Prevents unbounded growth of background_tasks on long-running installs.
-   *
-   * Pending and running tasks are NEVER finalized regardless of age — they're
-   * still live work. `maxAgeMs` is measured from `completed_at`, so a task that
-   * just finished a moment ago is safe.
-   *
-   * @param maxAgeMs - Maximum age in milliseconds for terminal tasks.
-   * @returns Number of rows deleted.
-   */
-  finalize(maxAgeMs: number): number {
-    const cutoff = Date.now() - maxAgeMs;
-    const result = this.db
-      .query(
-        `DELETE FROM background_tasks
-         WHERE status IN ('completed', 'failed', 'cancelled')
-           AND completed_at IS NOT NULL
-           AND completed_at < ?`,
-      )
-      .run(cutoff);
-    return result.changes;
-  }
-
-  /**
-   * List all tasks for a specific agent, newest first.
-   *
-   * @param agent - Agent name to filter by.
-   * @returns Array of tasks for that agent.
-   */
-  listByAgent(agent: string): BackgroundTask[] {
-    const rows = this.db
-      .query("SELECT * FROM background_tasks WHERE agent = ? ORDER BY created_at DESC")
-      .all(agent) as BackgroundTaskRow[];
-    return rows.map((r) => this.rowToTask(r));
-  }
-}