mercury-agent 0.16.0 → 0.16.2

package/src/storage/db.ts

@@ -12,6 +12,9 @@ import type {
   SpacePreferenceEntry,
   SpaceRole,
   StoredMessage,
+  TaskRun,
+  TaskRunDetail,
+  TaskRunOutcome,
   TaskRunStatus,
   TokenUsage,
 } from "../types.js";
@@ -23,6 +26,39 @@ import type {
  */
 export const TASK_LAST_ERROR_MAX_LENGTH = 500;
 
+/**
+ * Ledger rows kept per task. A ceiling rather than a setting: a config key
+ * would be a two-surface job (dashboard rows are hardcoded) and nobody has
+ * asked to tune it. Questions that reach past this window belong to
+ * `token_usage`, which is unbounded.
+ *
+ * 200 is ~2 months of a thrice-daily task, or a week of a hourly one.
+ */
+export const TASK_RUNS_RETENTION_PER_TASK = 200;
+
+/**
+ * How long a ledger row outlives a task that no longer exists. Completed
+ * one-shots leave their rows behind on purpose (see the task_runs DDL), which
+ * is bounded per task but not in the number of tasks — feed-watch style
+ * verified one-shots would accumulate forever without a horizon. Thirty days
+ * comfortably covers the two-week re-audit the ledger exists to serve.
+ */
+export const TASK_RUNS_ORPHAN_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+
+/**
+ * What a caller must know to write a ledger row: which space it ran in, when
+ * it started, whether it was a preview, which attempt it was, and — if the
+ * handler reported it — what the run produced.
+ */
+export interface TaskRunLedgerEntry {
+  spaceId: string;
+  startedAt: number;
+  detail?: TaskRunDetail;
+  /** True for a "Run now" preview, which shares the code path but no schedule. */
+  manual: boolean;
+  attempt: number;
+}
+
 // `bun:sqlite` caches prepared statements per Database, capped at
 // Database.MAX_QUERY_CACHE_SIZE (default 20). When a 21st distinct statement is
 // prepared the least-recently-used one is evicted WITHOUT being finalized, so
@@ -173,6 +209,41 @@ export class Db {
       CREATE INDEX IF NOT EXISTS idx_tasks_next
       ON tasks(active, next_run_at);
 
+      -- One row per completed attempt. The tasks table keeps a snapshot of the
+      -- last one (last_run_at / last_status / last_error); history needs rows,
+      -- not wider columns, and the snapshot is what the dashboard already
+      -- reads. Both are written from the same recordTaskRun call, so there is
+      -- still exactly one write site per run.
+      --
+      -- task_id is deliberately NOT a foreign key. A one-shot task is deleted
+      -- by the scheduler the moment it completes, and a cascade would erase
+      -- its row microseconds after it was written — the normal lifecycle of
+      -- an at-task, not an edge case. Rows outlive their task; the user-facing
+      -- deletes (deleteTask, deleteSpace) clean up explicitly, and rows left
+      -- behind by completed one-shots age out past TASK_RUNS_ORPHAN_MAX_AGE_MS.
+      CREATE TABLE IF NOT EXISTS task_runs (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        task_id INTEGER NOT NULL,
+        space_id TEXT NOT NULL,
+        started_at INTEGER NOT NULL,
+        finished_at INTEGER NOT NULL,
+        status TEXT NOT NULL,
+        outcome TEXT,
+        model TEXT,
+        input_tokens INTEGER,
+        output_tokens INTEGER,
+        total_tokens INTEGER,
+        cost REAL,
+        reply_chars INTEGER,
+        files INTEGER,
+        manual INTEGER NOT NULL DEFAULT 0,
+        attempt INTEGER NOT NULL DEFAULT 1,
+        error TEXT
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_task_runs_task
+      ON task_runs(task_id, started_at DESC);
+
       CREATE TABLE IF NOT EXISTS chat_state (
         space_id TEXT PRIMARY KEY,
         min_message_id INTEGER NOT NULL DEFAULT 0,
@@ -578,6 +649,7 @@ export class Db {
       const tasks = this.db
         .query("DELETE FROM tasks WHERE space_id = ?")
         .run(spaceId).changes;
+      this.db.query("DELETE FROM task_runs WHERE space_id = ?").run(spaceId);
       const chatState = this.db
         .query("DELETE FROM chat_state WHERE space_id = ?")
         .run(spaceId).changes;
@@ -964,6 +1036,31 @@ export class Db {
       .run(JSON.stringify(meta), now, messageId);
   }
 
+  /**
+   * Remove one message row. Returns whether a row was deleted.
+   *
+   * Used for a turn that was written and then decided against — a scheduled
+   * run whose reply turns out to be a no-op leaves a prompt in the history
+   * that no answer will ever follow.
+   *
+   * Both tables that can reference a message are cleared first. `foreign_keys`
+   * is ON, so a platform-id row or another message's `reply_to_id` pointing at
+   * this one would otherwise turn the delete into a constraint failure rather
+   * than a no-op. The `reply_to_id` pointers are nulled rather than followed:
+   * severing a chain is right here, cascading it would delete a real answer.
+   */
+  deleteMessage(id: number): boolean {
+    this.db
+      .query("DELETE FROM message_platform_ids WHERE mercury_message_id = ?")
+      .run(id);
+    this.db
+      .query("UPDATE messages SET reply_to_id = NULL WHERE reply_to_id = ?")
+      .run(id);
+    return (
+      this.db.query("DELETE FROM messages WHERE id = ?").run(id).changes > 0
+    );
+  }
+
   clearMessages(spaceId: string): void {
     this.db.query("DELETE FROM messages WHERE space_id = ?").run(spaceId);
   }
@@ -1333,6 +1430,7 @@ export class Db {
     status: TaskRunStatus,
     error?: string | null,
     at = Date.now(),
+    ledger?: TaskRunLedgerEntry,
   ): void {
     const message =
       status === "error" && error
@@ -1345,6 +1443,115 @@ export class Db {
          WHERE id = ?`,
       )
       .run(at, status, message, Date.now(), id);
+
+    // A four-argument call is exactly the behaviour it always had. Only a
+    // caller that can say *what the run produced* writes history.
+    if (!ledger) return;
+    const usage = ledger.detail?.usage;
+    const outcome: TaskRunOutcome | null =
+      status === "error" ? "error" : (ledger.detail?.outcome ?? null);
+    const tx = this.db.transaction(() => {
+      this.db
+        .query(
+          `INSERT INTO task_runs(
+             task_id, space_id, started_at, finished_at, status, outcome,
+             model, input_tokens, output_tokens, total_tokens, cost,
+             reply_chars, files, manual, attempt, error
+           ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        )
+        .run(
+          id,
+          ledger.spaceId,
+          ledger.startedAt,
+          at,
+          status,
+          outcome,
+          usage?.model ?? null,
+          usage?.inputTokens ?? null,
+          usage?.outputTokens ?? null,
+          usage?.totalTokens ?? null,
+          usage?.cost ?? null,
+          ledger.detail?.replyChars ?? null,
+          ledger.detail?.files ?? null,
+          ledger.manual ? 1 : 0,
+          ledger.attempt,
+          message,
+        );
+      // Prune inside the same transaction: a reader can never see the table
+      // over its ceiling, and a failed insert takes its own prune with it.
+      this.db
+        .query(
+          `DELETE FROM task_runs
+            WHERE task_id = ?
+              AND id NOT IN (
+                SELECT id FROM task_runs WHERE task_id = ? ORDER BY id DESC LIMIT ?
+              )`,
+        )
+        .run(id, id, TASK_RUNS_RETENTION_PER_TASK);
+      // Rows whose task is gone age out. Cheap: tasks is tiny and task_runs is
+      // bounded, and it runs once per scheduled run, not per read.
+      this.db
+        .query(
+          `DELETE FROM task_runs
+            WHERE finished_at < ?
+              AND task_id NOT IN (SELECT id FROM tasks)`,
+        )
+        .run(at - TASK_RUNS_ORPHAN_MAX_AGE_MS);
+    });
+    tx();
+  }
+
+  /**
+   * The last `limit` attempts of a task, newest first. Empty for a task that
+   * predates the ledger — its history was never recorded, and inventing rows
+   * for it would be worse than saying so.
+   */
+  listTaskRuns(taskId: number, limit = 50): TaskRun[] {
+    const capped = Number.isFinite(limit)
+      ? Math.max(1, Math.min(TASK_RUNS_RETENTION_PER_TASK, Math.floor(limit)))
+      : 50;
+    return this.db
+      .query(
+        `SELECT id,
+                task_id as taskId,
+                space_id as spaceId,
+                started_at as startedAt,
+                finished_at as finishedAt,
+                status,
+                outcome,
+                model,
+                input_tokens as inputTokens,
+                output_tokens as outputTokens,
+                total_tokens as totalTokens,
+                cost,
+                reply_chars as replyChars,
+                files,
+                manual,
+                attempt,
+                error
+           FROM task_runs
+          WHERE task_id = ?
+          ORDER BY id DESC
+          LIMIT ?`,
+      )
+      .all(taskId, capped) as TaskRun[];
+  }
+
+  /**
+   * Replace a task's prompt in place. Schedule, status and ids are untouched,
+   * so a task whose wording changes keeps its next run and its history.
+   *
+   * The scheduler re-reads the row before each run, so a change lands on the
+   * next run; a run already in flight keeps the prompt it started with.
+   *
+   * Returns whether a row was updated — an unknown id is a caller error, not
+   * an exception, matching `deleteTask`.
+   */
+  updateTaskPrompt(id: number, prompt: string): boolean {
+    const result = this.db
+      .query("UPDATE tasks SET prompt = ?, updated_at = ? WHERE id = ?")
+      .run(prompt, Date.now(), id);
+    return result.changes > 0;
   }
 
   setTaskActive(id: number, active: boolean): void {
@@ -1353,10 +1560,18 @@ export class Db {
       .run(active ? 1 : 0, Date.now(), id);
   }
 
+  /**
+   * A user deleting a task takes its run history with it. `deleteTaskById`
+   * deliberately does not: that is the scheduler's path for a completed
+   * one-shot, whose history is the whole point of keeping.
+   */
   deleteTask(id: number, spaceId: string): boolean {
     const result = this.db
       .query("DELETE FROM tasks WHERE id = ? AND space_id = ?")
       .run(id, spaceId);
+    if (result.changes > 0) {
+      this.db.query("DELETE FROM task_runs WHERE task_id = ?").run(id);
+    }
     return result.changes > 0;
   }
 

package/src/types.ts

@@ -106,6 +106,62 @@ export interface ScheduledTask {
  */
 export type TaskRunStatus = "ok" | "error";
 
+/**
+ * What a scheduled run *produced*, as recorded in the run ledger.
+ *
+ * Deliberately wider than `TaskRunStatus`, and deliberately not a
+ * replacement for it: `posted` and `no_update` are both `status: "ok"`, and
+ * telling them apart is the question the 48-hour audit had to read an entire
+ * chat to answer. Keeping the two-valued snapshot on the task row means
+ * nothing downstream has to learn a new vocabulary.
+ *
+ * Delivery is not part of this. Whether the space actually saw the output is
+ * governed by the task's `silent` flag; folding the two together would make a
+ * silent task indistinguishable from a quiet one.
+ */
+export type TaskRunOutcome = "posted" | "no_update" | "error";
+
+/**
+ * What a task handler reports back about a run it completed. Optional at the
+ * scheduler boundary: a handler that returns nothing still gets a ledger row,
+ * with `outcome` null rather than a guess.
+ */
+export interface TaskRunDetail {
+  /** `error` is the scheduler's to write, never the handler's. */
+  outcome: Exclude<TaskRunOutcome, "error">;
+  /** Model, tokens and cost. Absent on an old agent image or non-JSON pi output. */
+  usage?: TokenUsage;
+  /** Length of the reply the run produced, before any send-path suppression. */
+  replyChars: number;
+  /** Files the run produced. A no-op reply with files still counts as posted. */
+  files: number;
+}
+
+/** One completed attempt, as stored in `task_runs`. */
+export interface TaskRun {
+  id: number;
+  taskId: number;
+  spaceId: string;
+  startedAt: number;
+  finishedAt: number;
+  status: TaskRunStatus;
+  /** Null when the handler reported no detail. */
+  outcome: TaskRunOutcome | null;
+  /** The model that actually ran, not the leg index — see the spec. */
+  model: string | null;
+  inputTokens: number | null;
+  outputTokens: number | null;
+  totalTokens: number | null;
+  cost: number | null;
+  replyChars: number | null;
+  files: number | null;
+  /** 1 when the run came from a "Run now" preview rather than the schedule. */
+  manual: number;
+  /** Attempt number within the current due cycle, starting at 1. */
+  attempt: number;
+  error: string | null;
+}
+
 export interface Space {
   /** User-chosen slug, primary key. e.g. "family", "work" */
   id: string;