commandmate 0.16.0 → 0.18.0

package/dist/server/src/lib/db/migrations/v50-tasks.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * Migration v50: tasks (Issue #1545, Phase 2-1).
+ *
+ * The table the execution contract lands in. Until now a message sent to an
+ * agent left only a `chat_messages` row: what the agent was *supposed* to do,
+ * which paths it was allowed to touch, and what would count as done existed
+ * nowhere the system could read back. A task row is that record.
+ *
+ * `contract_json` is a parsed snapshot, not a path to re-read. A contract file
+ * edited after the send must not retroactively change what the running task
+ * agreed to — otherwise "did it meet the contract?" has no fixed answer.
+ * `contract_path` is kept alongside it for provenance only.
+ *
+ * The `status` vocabulary is CHECK-constrained because the distinctions are the
+ * point of the table and a typo landing as a new value would create a bucket
+ * nothing queries:
+ *   pending       — row exists, message not sent yet
+ *   running       — sent; the agent is working
+ *   waiting_input — blocked on a prompt (used by the Phase 3-1 state machine)
+ *   verifying     — a verification run is in flight for this task
+ *   succeeded     — that run came back `passed`
+ *   failed        — the run came back `failed`, or no verdict was reachable
+ *   not_started   — the run came back `not_started` (no work evidence at all)
+ *   cancelled     — abandoned explicitly
+ *
+ * `last_verification_run_id` deliberately carries no REFERENCES clause, for the
+ * same reason `verification_runs.task_id` (v49) does not point here: the two
+ * tables reference each other, so a foreign key in either direction would order
+ * the migrations against themselves. Application code keeps them consistent.
+ *
+ * Timestamps are epoch milliseconds (INTEGER), matching v44 onward.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.v50_migrations = void 0;
+exports.v50_migrations = [
+    {
+        version: 50,
+        name: 'add-tasks',
+        up: (db) => {
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS tasks (
+          id TEXT PRIMARY KEY,
+          worktree_id TEXT NOT NULL,
+          cli_tool_id TEXT NOT NULL,
+          instance_id TEXT,
+          title TEXT NOT NULL,
+          goal TEXT NOT NULL,
+          contract_path TEXT,
+          contract_json TEXT NOT NULL,
+          status TEXT NOT NULL CHECK (status IN ('pending','running','waiting_input','verifying','succeeded','failed','not_started','cancelled')),
+          last_verification_run_id INTEGER,
+          created_at INTEGER NOT NULL,
+          updated_at INTEGER NOT NULL,
+          started_at INTEGER,
+          finished_at INTEGER
+        );
+      `);
+            db.exec(`
+        CREATE INDEX IF NOT EXISTS idx_tasks_worktree
+          ON tasks(worktree_id, created_at DESC);
+      `);
+        },
+        down: (db) => {
+            db.exec('DROP TABLE IF EXISTS tasks;');
+        },
+    },
+];

package/dist/server/src/lib/db/migrations/v51-task-events.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * Migration v51: task_events (Issue #1548, Phase 3-1).
+ *
+ * An append-only log of every attempt to move a task's status. v50 recorded
+ * where a task *is*; this records how it got there — which is what "how many
+ * times did a human have to intervene" and "how many re-instruction loops did
+ * this take" are computed from (Phase 4 Eval). Neither question is answerable
+ * from a status column that only ever holds the latest value.
+ *
+ * `to_status` is nullable on purpose: a rejected transition is written with
+ * `to_status = NULL`. An event the state machine refused is evidence that some
+ * caller believed a transition was possible when it was not, and silently
+ * dropping it would hide exactly the wiring bug worth finding.
+ *
+ * No CHECK constraint on `event`, unlike `tasks.status` in v50. The status
+ * vocabulary is written by many callers and read by queries that branch on it;
+ * events have a single writer (`applyTaskEvent`) whose input is a closed
+ * TypeScript union, so a CHECK here would only add a migration to the cost of
+ * adding an event without closing a hole the type system leaves open.
+ *
+ * No foreign key to `tasks` for the same reason v50's
+ * `last_verification_run_id` has none: this table is history, and history that
+ * disappears when its subject is deleted cannot be audited afterwards.
+ *
+ * Timestamps are epoch milliseconds (INTEGER), matching v44 onward.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.v51_migrations = void 0;
+exports.v51_migrations = [
+    {
+        version: 51,
+        name: 'add-task-events',
+        up: (db) => {
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS task_events (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          task_id TEXT NOT NULL,
+          event TEXT NOT NULL,
+          from_status TEXT NOT NULL,
+          to_status TEXT,
+          payload_json TEXT,
+          created_at INTEGER NOT NULL
+        );
+      `);
+            // (task_id, created_at) is the only read pattern: one task's history in
+            // order. id breaks ties, because same-millisecond events are ordinary —
+            // a rejected transition and its retry can land in the same tick.
+            db.exec(`
+        CREATE INDEX IF NOT EXISTS idx_task_events_task
+          ON task_events(task_id, created_at);
+      `);
+        },
+        down: (db) => {
+            db.exec('DROP TABLE IF EXISTS task_events;');
+        },
+    },
+];

package/dist/server/src/lib/db/task-events-db.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * task_events row I/O (Issue #1548, migration v51).
+ *
+ * `insertTaskEvent` is deliberately NOT re-exported from the `@/lib/db` barrel.
+ * The log is only meaningful if every row was produced by a real state-machine
+ * decision, so the sole writer is `applyTaskEvent`
+ * (`@/lib/tasks/task-transition-service`), which imports this module directly.
+ * A caller reaching for the barrel gets the reader and nothing else.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.insertTaskEvent = insertTaskEvent;
+exports.listTaskEvents = listTaskEvents;
+function mapRow(row) {
+    return {
+        id: row.id,
+        taskId: row.task_id,
+        event: row.event,
+        fromStatus: row.from_status,
+        toStatus: row.to_status,
+        payload: row.payload_json === null ? null : JSON.parse(row.payload_json),
+        createdAt: new Date(row.created_at),
+    };
+}
+/** Append one event. See the module comment for why this is not barrel-exported. */
+function insertTaskEvent(db, input) {
+    // An empty payload is stored as NULL rather than '{}': "nothing was attached"
+    // and "an empty object was attached" are the same fact, and one of them makes
+    // the column readable at a glance.
+    const payloadJson = input.payload === undefined || Object.keys(input.payload).length === 0
+        ? null
+        : JSON.stringify(input.payload);
+    const info = db
+        .prepare(`
+      INSERT INTO task_events (task_id, event, from_status, to_status, payload_json, created_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `)
+        .run(input.taskId, input.event, input.fromStatus, input.toStatus, payloadJson, input.createdAt);
+    return Number(info.lastInsertRowid);
+}
+/**
+ * One task's history, oldest first.
+ *
+ * `id ASC` breaks ties rather than leaving same-millisecond rows in an arbitrary
+ * order — a rejected transition and the retry that followed it routinely share a
+ * timestamp, and reading them out of order inverts the story they tell.
+ */
+function listTaskEvents(db, taskId, limit = 200) {
+    const rows = db
+        .prepare(`
+      SELECT id, task_id, event, from_status, to_status, payload_json, created_at
+      FROM task_events
+      WHERE task_id = ?
+      ORDER BY created_at ASC, id ASC
+      LIMIT ?
+    `)
+        .all(taskId, limit);
+    return rows.map(mapRow);
+}

package/dist/server/src/lib/db/tasks-db.js

@@ -0,0 +1,263 @@
+"use strict";
+/**
+ * Task database operations (Issue #1545, migration v50).
+ *
+ * A task row is the durable record of an execution contract: the goal that was
+ * sent, the paths the agent was allowed to touch, the gates that decide
+ * completion, and where the task got to. `contract_json` holds the *parsed
+ * snapshot* taken at send time, so editing the contract file afterwards cannot
+ * change what a running task agreed to.
+ *
+ * `updateTaskStatus` throws when the row does not exist. A silent no-op would
+ * let a caller believe it recorded a transition it never recorded — the same
+ * failure `verification-db.ts` guards against.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERIFIABLE_TASK_STATUSES = exports.ACTIVE_TASK_STATUSES = exports.TERMINAL_TASK_STATUSES = exports.TASK_STATUSES = void 0;
+exports.isTerminalTaskStatus = isTerminalTaskStatus;
+exports.createTask = createTask;
+exports.getTask = getTask;
+exports.listTasks = listTasks;
+exports.updateTaskStatus = updateTaskStatus;
+exports.getActiveTask = getActiveTask;
+exports.getVerifiableTask = getVerifiableTask;
+exports.getActiveTaskForInstance = getActiveTaskForInstance;
+const crypto_1 = require("crypto");
+/**
+ * Lifecycle of a task.
+ *
+ * The runtime tuple mirrors the `status` CHECK constraint in migration v50 and
+ * is what callers validate untrusted input against, so a status cannot be
+ * accepted by an API route and then rejected by SQLite.
+ *
+ * `not_started` is distinct from `failed`: the work was never produced, so
+ * nothing was judged. `failed` means a verdict was reached, or that no verdict
+ * could be reached at all — either way the task did not pass.
+ */
+exports.TASK_STATUSES = [
+    'pending',
+    'running',
+    'waiting_input',
+    'verifying',
+    'succeeded',
+    'failed',
+    'not_started',
+    'cancelled',
+];
+/** Statuses a task can no longer move out of. */
+exports.TERMINAL_TASK_STATUSES = [
+    'succeeded',
+    'failed',
+    'not_started',
+    'cancelled',
+];
+/**
+ * Statuses that mean "this task is the one a verification run belongs to".
+ *
+ * `pending` is excluded on purpose: nothing has been sent, so there is no work
+ * a run could be judging.
+ */
+exports.ACTIVE_TASK_STATUSES = [
+    'running',
+    'waiting_input',
+    'verifying',
+];
+/**
+ * Statuses a verification run that has to *discover* its task may attach to.
+ *
+ * The active three plus the two the state machine explicitly reopens:
+ * `transitionTask` accepts `verify_started` from `failed` and `not_started`
+ * because a task can fail on one run and pass on the retry. Resolving only the
+ * active three meant that reopening was reachable only by a caller that already
+ * knew the task id — so the retry every agent performs after a red gate found
+ * no contract, and with it no scope to judge (#1620).
+ *
+ * `succeeded` and `cancelled` stay out: those are closed for good, and a run
+ * that silently adopted one would be judging work against a verdict already
+ * given. {@link ACTIVE_TASK_STATUSES} keeps its narrower meaning for the
+ * callers that ask "what is this agent working on right now" (Auto-Yes, prompt
+ * events), where a finished task must not answer.
+ */
+exports.VERIFIABLE_TASK_STATUSES = [
+    ...exports.ACTIVE_TASK_STATUSES,
+    'failed',
+    'not_started',
+];
+function isTerminalTaskStatus(status) {
+    return exports.TERMINAL_TASK_STATUSES.includes(status);
+}
+const TASK_COLUMNS = `
+  id, worktree_id, cli_tool_id, instance_id, title, goal, contract_path, contract_json,
+  status, last_verification_run_id, created_at, updated_at, started_at, finished_at
+`;
+function mapTaskRow(row) {
+    return {
+        id: row.id,
+        worktreeId: row.worktree_id,
+        cliToolId: row.cli_tool_id,
+        instanceId: row.instance_id,
+        title: row.title,
+        goal: row.goal,
+        contractPath: row.contract_path,
+        contract: JSON.parse(row.contract_json),
+        status: row.status,
+        lastVerificationRunId: row.last_verification_run_id,
+        createdAt: new Date(row.created_at),
+        updatedAt: new Date(row.updated_at),
+        startedAt: row.started_at === null ? null : new Date(row.started_at),
+        finishedAt: row.finished_at === null ? null : new Date(row.finished_at),
+    };
+}
+/** Insert a task, `pending` unless the caller says otherwise. */
+function createTask(db, input) {
+    const now = Date.now();
+    const id = (0, crypto_1.randomUUID)();
+    const status = input.status ?? 'pending';
+    db.prepare(`
+    INSERT INTO tasks (
+      id, worktree_id, cli_tool_id, instance_id, title, goal, contract_path, contract_json,
+      status, last_verification_run_id, created_at, updated_at, started_at, finished_at
+    )
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, ?, ?, ?, NULL)
+  `).run(id, input.worktreeId, input.cliToolId, input.instanceId ?? null, input.contract.title, input.contract.goal, input.contractPath ?? null, JSON.stringify(input.contract), status, now, now, status === 'pending' ? null : now);
+    const task = getTask(db, id);
+    if (!task) {
+        throw new Error('Failed to persist task');
+    }
+    return task;
+}
+function getTask(db, taskId) {
+    const row = db
+        .prepare(`SELECT ${TASK_COLUMNS} FROM tasks WHERE id = ?`)
+        .get(taskId);
+    return row ? mapTaskRow(row) : null;
+}
+/**
+ * Tasks for a worktree, newest first.
+ *
+ * `rowid DESC` breaks ties, not `id DESC`: ids are random UUIDs, so comparing
+ * them orders same-millisecond rows arbitrarily. rowid is insertion order, which
+ * is what "newest" means when two tasks share a timestamp.
+ */
+function listTasks(db, worktreeId, limit = 20) {
+    const rows = db
+        .prepare(`
+      SELECT ${TASK_COLUMNS} FROM tasks
+      WHERE worktree_id = ?
+      ORDER BY created_at DESC, rowid DESC
+      LIMIT ?
+    `)
+        .all(worktreeId, limit);
+    return rows.map(mapTaskRow);
+}
+/**
+ * Move a task to `status`, stamping the timestamps that status implies.
+ *
+ * `started_at` is written on the first transition out of `pending` and never
+ * overwritten — it records when the work began, not when it last changed state.
+ * `finished_at` is written for terminal statuses only.
+ *
+ * @throws Error when the task does not exist
+ */
+function updateTaskStatus(db, taskId, status, patch = {}) {
+    const now = Date.now();
+    const info = db
+        .prepare(`
+      UPDATE tasks
+      SET status = ?,
+          updated_at = ?,
+          started_at = CASE WHEN ? = 'pending' THEN started_at ELSE COALESCE(started_at, ?) END,
+          finished_at = CASE WHEN ? = 1 THEN ? ELSE finished_at END,
+          last_verification_run_id = COALESCE(?, last_verification_run_id)
+      WHERE id = ?
+    `)
+        .run(status, now, status, now, isTerminalTaskStatus(status) ? 1 : 0, now, patch.lastVerificationRunId ?? null, taskId);
+    if (info.changes === 0) {
+        throw new Error(`Task ${taskId} not found`);
+    }
+    return getTask(db, taskId);
+}
+/**
+ * The task a verification run for this worktree belongs to, or null.
+ *
+ * Filters are applied only when supplied. A verification run is worktree-scoped
+ * — the gates execute over the whole working tree and a worktree admits one run
+ * at a time — so the runner resolves without filters and takes the most recently
+ * updated active task.
+ */
+function getActiveTask(db, worktreeId, cliToolId, instanceId) {
+    const conditions = ['worktree_id = ?'];
+    const params = [worktreeId];
+    if (cliToolId !== undefined) {
+        conditions.push('cli_tool_id = ?');
+        params.push(cliToolId);
+    }
+    if (instanceId !== undefined) {
+        conditions.push('instance_id = ?');
+        params.push(instanceId);
+    }
+    const placeholders = exports.ACTIVE_TASK_STATUSES.map(() => '?').join(', ');
+    const row = db
+        .prepare(`
+      SELECT ${TASK_COLUMNS} FROM tasks
+      WHERE ${conditions.join(' AND ')} AND status IN (${placeholders})
+      ORDER BY updated_at DESC, created_at DESC, rowid DESC
+      LIMIT 1
+    `)
+        .get(...params, ...exports.ACTIVE_TASK_STATUSES);
+    return row ? mapTaskRow(row) : null;
+}
+/**
+ * The task a verification run should attach to when the caller cannot name one.
+ *
+ * Worktree-scoped for the same reason {@link getActiveTask} is: the gates run
+ * over the whole working tree, so there is nothing finer to narrow by. Ordered
+ * like {@link getActiveTask} — most recently updated first, insertion order
+ * breaking a same-millisecond tie — so the answer is the last task to have
+ * moved, not whichever row SQLite happened to reach first.
+ *
+ * @see VERIFIABLE_TASK_STATUSES for why this is wider than "active"
+ */
+function getVerifiableTask(db, worktreeId) {
+    const placeholders = exports.VERIFIABLE_TASK_STATUSES.map(() => '?').join(', ');
+    const row = db
+        .prepare(`
+      SELECT ${TASK_COLUMNS} FROM tasks
+      WHERE worktree_id = ? AND status IN (${placeholders})
+      ORDER BY updated_at DESC, created_at DESC, rowid DESC
+      LIMIT 1
+    `)
+        .get(worktreeId, ...exports.VERIFIABLE_TASK_STATUSES);
+    return row ? mapTaskRow(row) : null;
+}
+/**
+ * The active task governing one agent instance, or null.
+ *
+ * Distinct from {@link getActiveTask} because the primary instance is recorded
+ * two different ways: `instance_id` is NULL when no `--instance` was given, and
+ * the tool id itself (`'claude'`) when `--instance claude` was. Both mean the
+ * primary instance, so both must match — `= ?` cannot express either, since
+ * `instance_id = NULL` is never true in SQL.
+ *
+ * Auto-Yes needs this precision: a contract sent to `codex-2` must not govern
+ * the auto-answering of `codex`, and taking the worktree's most recent active
+ * task would do exactly that.
+ *
+ * @param instanceId - Agent instance id; pass the tool id itself for the primary
+ */
+function getActiveTaskForInstance(db, worktreeId, cliToolId, instanceId) {
+    const isPrimary = instanceId === cliToolId;
+    const placeholders = exports.ACTIVE_TASK_STATUSES.map(() => '?').join(', ');
+    const row = db
+        .prepare(`
+      SELECT ${TASK_COLUMNS} FROM tasks
+      WHERE worktree_id = ?
+        AND cli_tool_id = ?
+        AND (instance_id = ? OR (instance_id IS NULL AND ?))
+        AND status IN (${placeholders})
+      ORDER BY updated_at DESC, created_at DESC, rowid DESC
+      LIMIT 1
+    `)
+        .get(worktreeId, cliToolId, instanceId, isPrimary ? 1 : 0, ...exports.ACTIVE_TASK_STATUSES);
+    return row ? mapTaskRow(row) : null;
+}