AgentHub/server/lib/dashboard-runs.js

/**
 * @file dashboard-runs.js
 * @description Persistence layer for runs spawned via the dashboard's
 * /api/run endpoint. The in-memory handle map in run-spawner.js reaps
 * handles 5 min after exit, which is fine for live re-attach but loses
 * historical data. This module mirrors every spawn / status transition
 * into a sqlite row so the Run page can show a full history of what
 * the user has spawned and resume any of those sessions.
 *
 * All db operations are wrapped in try/catch so a failure here can never
 * take down a live run — persistence is a side benefit, not a blocker.
 *
 * A run started through a lane also carries that lane's id (`lane_id`), so the
 * Workspace page can list one lane's own run history; runs spawned straight
 * from POST /api/run leave it null.
 *
 * A run's id is its tmux pane name (`agenthub-lane-<id>[-slot]`), which every
 * Start in that pane reuses. So a new run first ARCHIVES the row it replaces
 * under `<id>@<its started_at>` (flagged `abandoned` if it never said it
 * ended) — history is kept, and `getRun(<pane name>)` is always the pane's
 * current run. A row is flagged dead only once its tmux session is gone
 * (`reconcileOrphans(isAlive)`): panes outlive a server restart. A session
 * whose pane died under it is kept `interrupted` until the user resumes or
 * dismisses it (`listInterrupted`, `dismissInterrupted`).
 *
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */

const { db } = require("../db");

const PROMPT_PREVIEW_LIMIT = 500;

const insertStmt = db.prepare(`
  INSERT OR REPLACE INTO dashboard_runs (
    id, session_id, mode, cwd, model, permission_mode, effort,
    resume_session_id, prompt_preview, status, exit_code, started_at, ended_at,
    lane_id, tool, worktree, proxy, account, pane_token_hash
  ) VALUES (
    @id, @session_id, @mode, @cwd, @model, @permission_mode, @effort,
    @resume_session_id, @prompt_preview, @status, @exit_code, @started_at, @ended_at,
    @lane_id, @tool, @worktree, @proxy, @account, @pane_token_hash
  )
`);

const updateStmt = db.prepare(`
  UPDATE dashboard_runs
  SET session_id = COALESCE(@session_id, session_id),
      status = COALESCE(@status, status),
      exit_code = COALESCE(@exit_code, exit_code),
      ended_at = COALESCE(@ended_at, ended_at)
  WHERE id = @id
`);

const RUN_COLUMNS = `id, session_id, mode, cwd, model, permission_mode, effort,
         resume_session_id, prompt_preview, status, exit_code,
         started_at, ended_at, lane_id, tool, worktree, proxy, account`;

const listStmt = db.prepare(`
  SELECT ${RUN_COLUMNS}
  FROM dashboard_runs
  ORDER BY started_at DESC
  LIMIT @limit
`);

const listByLaneStmt = db.prepare(`
  SELECT ${RUN_COLUMNS}
  FROM dashboard_runs
  WHERE lane_id = @laneId
  ORDER BY started_at DESC
  LIMIT @limit
`);

const listByLaneToolStmt = db.prepare(`
  SELECT ${RUN_COLUMNS}
  FROM dashboard_runs
  WHERE lane_id = @laneId AND tool = @tool
  ORDER BY started_at DESC
  LIMIT @limit
`);

const getStmt = db.prepare(`
  SELECT ${RUN_COLUMNS}
  FROM dashboard_runs WHERE id = @id
`);

// The row a new run in the same pane replaces, kept under its own id.
const archiveStmt = db.prepare(`
  UPDATE dashboard_runs
  SET id = id || '@' || started_at,
      status = CASE WHEN status IN ('running', 'spawning') THEN 'abandoned' ELSE status END,
      ended_at = COALESCE(ended_at, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
  WHERE id = ?
`);

/**
 * Insert a new run record at spawn time; the pane's previous run, if any, is
 * archived first rather than overwritten.
 */
function recordRun(handle) {
  try {
    try {
      archiveStmt.run(handle.id);
    } catch (err) {
      // An archive id already taken (an imported bundle) — fall back to the
      // replace below rather than lose the new run.
      console.warn(`[dashboard-runs] could not archive run ${handle?.id}: ${err.message}`);
    }
    const startedAt = new Date(handle.startedAt || Date.now()).toISOString();
    const endedAt = handle.endedAt ? new Date(handle.endedAt).toISOString() : null;
    const prompt = typeof handle.prompt === "string" ? handle.prompt : "";
    insertStmt.run({
      id: handle.id,
      session_id: handle.sessionId || null,
      mode: handle.mode,
      cwd: handle.cwd || "",
      model: handle.model || null,
      permission_mode: handle.permissionMode || null,
      effort: handle.effort || null,
      resume_session_id: handle.resumeSessionId || null,
      prompt_preview: prompt.slice(0, PROMPT_PREVIEW_LIMIT) || null,
      status: handle.status || "spawning",
      exit_code: typeof handle.exitCode === "number" ? handle.exitCode : null,
      started_at: startedAt,
      ended_at: endedAt,
      lane_id: typeof handle.laneId === "number" ? handle.laneId : null,
      tool: typeof handle.tool === "string" && handle.tool ? handle.tool : "claude",
      worktree: handle.worktree ? 1 : 0,
      proxy: handle.proxy || null,
      account: handle.account || null,
      pane_token_hash: handle.paneTokenHash || null,
    });
  } catch (err) {
    // Best-effort by design (a live run must never fail because sqlite did),
    // but not silent: a swallowed insert leaves the runs modal showing rows with
    // no cwd, model, prompt or start time, which reads as a UI bug rather than a
    // persistence one. Say it once, here, where the cause is known.
    console.warn(`[dashboard-runs] failed to record run ${handle?.id}: ${err.message}`);
  }
}

/**
 * Patch an existing run record. Pass null/undefined for fields you don't
 * want to overwrite — COALESCE in SQL leaves the existing value untouched.
 */
function patchRun({ id, sessionId, status, exitCode, endedAt }) {
  try {
    updateStmt.run({
      id,
      session_id: sessionId ?? null,
      status: status ?? null,
      exit_code: typeof exitCode === "number" ? exitCode : null,
      ended_at: endedAt ? new Date(endedAt).toISOString() : null,
    });
  } catch {
    /* ignore */
  }
}

/** @param {{limit?: number, laneId?: number|null, tool?: string|null}} [opts]
 *  laneId narrows to one lane's runs, and tool (with a laneId) to one tool's. */
function listRuns({ limit = 50, laneId = null, tool = null } = {}) {
  try {
    const safeLimit = Math.max(1, Math.min(500, Math.floor(Number(limit) || 50)));
    if (laneId != null && tool) return listByLaneToolStmt.all({ limit: safeLimit, laneId, tool });
    if (laneId != null) return listByLaneStmt.all({ limit: safeLimit, laneId });
    return listStmt.all({ limit: safeLimit });
  } catch {
    return [];
  }
}

const forgetShellStmt = db.prepare(`DELETE FROM dashboard_runs WHERE id = ? AND tool = 'shell'`);

/** Drop a closed Terminal tab's row — a shell has no session, so the row is
 *  only the sidebar's "recently closed" entry. Never touches another tool's. */
function forgetShellRun(id) {
  return forgetShellStmt.run(id).changes > 0;
}

function getRun(id) {
  try {
    return getStmt.get({ id }) || null;
  } catch {
    return null;
  }
}

const sessionProxyStmt = db.prepare(`
  SELECT proxy FROM dashboard_runs
  WHERE session_id = @sessionId OR resume_session_id = @sessionId
  ORDER BY started_at DESC LIMIT 1
`);

/**
 * The AI Proxy the newest run holding `sessionId` started on (null = native,
 * or no run known) — what a resume that names no proxy goes back to.
 */
function proxyForSession(sessionId) {
  try {
    return sessionProxyStmt.get({ sessionId })?.proxy || null;
  } catch {
    return null;
  }
}

const sessionLaneStmt = db.prepare(`
  SELECT lane_id FROM dashboard_runs
  WHERE session_id = @sessionId AND lane_id IS NOT NULL
  ORDER BY started_at DESC LIMIT 1
`);

/** The lane of the newest run that holds `sessionId`, or null. */
function laneForSession(sessionId) {
  try {
    return sessionLaneStmt.get({ sessionId })?.lane_id ?? null;
  } catch {
    return null;
  }
}

// The newest same-tool run in session `s`'s folder that was live when it
// started (2 s of slack: agy stamps whole seconds).
const runOf = (col, s) => `
  SELECT r.${col} FROM dashboard_runs r
  WHERE r.lane_id IS NOT NULL AND r.tool = ${s}.tool AND r.cwd = ${s}.cwd
    AND julianday(r.started_at) <= julianday(${s}.started_at) + 2.0 / 86400
    AND julianday(${s}.started_at) <= julianday(COALESCE(r.ended_at, 'now'))
  ORDER BY r.started_at DESC LIMIT 1`;
const claimToolStmt = db.prepare(`
  UPDATE sessions SET lane_id = (${runOf("lane_id", "sessions")})
  WHERE lane_id IS NULL AND tool != 'claude' AND (@id IS NULL OR id = @id)
    AND (${runOf("lane_id", "sessions")}) IS NOT NULL
`);
const claimRunStmt = db.prepare(`
  UPDATE dashboard_runs SET session_id = @id
  WHERE session_id IS NULL
    AND id = (SELECT (${runOf("id", "s")}) FROM sessions s WHERE s.id = @id AND s.tool != 'claude')
`);

/**
 * Stamp the workspace (`sessions.lane_id`) of a Codex / Antigravity session
 * that nothing bound: their panes learn their session only from opt-in hooks
 * (routes/hooks.js → bindRunSession), so without them a session the poll
 * imported belonged to no workspace and vanished from it once its tab closed.
 * Claude is left to `--session-id` + its hooks. `sessionId` null = every one;
 * a single session also becomes its run's `session_id` while that is empty,
 * so its live tab shows the session instead of a second "New session".
 * ponytail: matched by (tool, cwd, time), so an agy started by hand in the
 * same folder while a pane of that tool is live is counted as the pane's.
 */
function claimToolSessions(sessionId = null) {
  try {
    if (sessionId) claimRunStmt.run({ id: sessionId });
    return claimToolStmt.run({ id: sessionId }).changes;
  } catch {
    return 0;
  }
}

const runningStmt = db.prepare(
  "SELECT id, tool, session_id, cwd, started_at FROM dashboard_runs WHERE status IN ('running', 'spawning')"
);

/**
 * How long a new run is never judged dead. A tmux list is a cached answer —
 * a member's may be up to 15 s old (tmux.js MEMBER_LIST_MAX_AGE_MS) — and only
 * the process that started a pane writes it into its own cache, so another
 * dashboard on the same database (a dev server) ended a pane it had simply
 * not listed yet: the proxy gateway then answered 401 to a live Codex.
 */
const YOUNG_RUN_MS = 20_000;
function isYoungRun(startedAt, now = Date.now()) {
  const t = Date.parse(startedAt || "");
  return Number.isFinite(t) && now - t < YOUNG_RUN_MS;
}
const endStmt = db.prepare(`
  UPDATE dashboard_runs
  SET status = @status,
      ended_at = COALESCE(ended_at, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
  WHERE id = @id AND status IN ('running', 'spawning')
`);
// Claude says why it ended: `/exit`, Ctrl+C/Ctrl+D and `/logout` are the
// user's own; a signal (tmux killed) reports `other` and a power cut nothing.
const userExitStmt = db.prepare(`
  SELECT 1 FROM events
  WHERE session_id = ? AND event_type = 'SessionEnd'
    AND json_extract(data, '$.reason') IN ('prompt_input_exit', 'logout')
  LIMIT 1
`);

const anyEndStmt = db.prepare(`
  SELECT 1 FROM events WHERE session_id = ? AND event_type = 'SessionEnd' LIMIT 1
`);
// Whether the pane's tmux server was already up when the run started (and is
// still): then the pane ended on its own, not with its server.
function tmuxOutlived(row, serverStartedAt) {
  const since = serverStartedAt(row.id);
  const started = Date.parse(row.started_at || "");
  return Number.isFinite(since) && Number.isFinite(started) && since <= started;
}

// A shell has no session, so its row only tracks the open tab: once closed it
// is dropped — the sidebar keeps no list of closed Terminal tabs.
const pruneShellsStmt = db.prepare(`
  DELETE FROM dashboard_runs WHERE tool = 'shell' AND status NOT IN ('running', 'spawning')
`);

/**
 * Ends every row still marked running/spawning whose pane is gone. A pane is
 * a tmux session, which outlives a server restart, so liveness is asked of
 * `isAlive(id)` (tmux), never assumed from the restart. Run at boot and on
 * the server's run-heal beat, which also drops every closed Terminal tab's row.
 *
 * A pane AgentHub closed itself (Stop, close tab, Quit) is already `killed`.
 * Of the rest, an agent session the user did not exit is `interrupted` — a
 * reboot, a killed tmux, a crash — and offered for resume
 * (`listInterrupted`); everything else is `abandoned`. A pane whose tmux
 * server kept running since before it started (`serverStartedAt(id)`, epoch
 * ms or null) ended by itself — the user quit Codex, `exit`ed, closed it —
 * so it is not offered either: for Claude only when it said it ended (any
 * SessionEnd; none at all is a crash), for any other tool, which says
 * nothing, always. A server that cannot be asked counts as gone.
 *
 * Returns the number of rows updated.
 */
function reconcileOrphans(isAlive = () => false, serverStartedAt = () => null) {
  try {
    let changes = 0;
    const { unseenMemberFolder } = require("./linux-accounts");
    for (const row of runningStmt.all()) {
      if (isAlive(row.id) || unseenMemberFolder(row.cwd) || isYoungRun(row.started_at)) continue;
      const interrupted =
        row.tool !== "shell" &&
        !!row.session_id &&
        !(row.tool === "claude" && userExitStmt.get(row.session_id)) &&
        !(
          tmuxOutlived(row, serverStartedAt) &&
          (row.tool !== "claude" || anyEndStmt.get(row.session_id))
        );
      changes += endStmt.run({
        id: row.id,
        status: interrupted ? "interrupted" : "abandoned",
      }).changes;
    }
    pruneShellsStmt.run();
    return changes;
  } catch {
    return 0;
  }
}

// The newest interrupted run of each session that nothing ran since — a
// session resumed by any path drops out — of workspaces `@owner` owns (any
// owner when null). A workspace removed since takes its rows with it.
const interruptedStmt = db.prepare(`
  SELECT r.id, r.session_id, r.lane_id, r.tool, r.cwd, r.model, r.permission_mode, r.effort,
         r.prompt_preview, r.started_at, r.ended_at,
         l.title AS lane_title, l.cwd AS lane_cwd, s.name AS session_name
  FROM dashboard_runs r
  JOIN lanes l ON l.id = r.lane_id
  LEFT JOIN sessions s ON s.id = r.session_id
  WHERE r.status = 'interrupted' AND r.session_id IS NOT NULL
    AND (@owner IS NULL OR l.owner_id = @owner)
    AND NOT EXISTS (
      SELECT 1 FROM dashboard_runs n
      WHERE n.session_id = r.session_id AND n.id != r.id
        AND (n.started_at >= r.started_at OR n.status IN ('running', 'spawning'))
    )
  ORDER BY r.ended_at DESC
  LIMIT 50
`);
const dismissStmt = db.prepare(`
  UPDATE dashboard_runs SET status = 'abandoned'
  WHERE status = 'interrupted' AND session_id = @sessionId
    AND lane_id IN (SELECT id FROM lanes WHERE @owner IS NULL OR owner_id = @owner)
`);

/** Sessions whose pane went away without the user ending them, newest first. */
function listInterrupted(ownerId = null) {
  try {
    return interruptedStmt.all({ owner: ownerId });
  } catch {
    return [];
  }
}

/** The user answered: these sessions are no longer offered for resume. */
function dismissInterrupted(sessionIds, ownerId = null) {
  let changes = 0;
  for (const sessionId of sessionIds) {
    changes += dismissStmt.run({ sessionId, owner: ownerId }).changes;
  }
  return changes;
}

module.exports = {
  recordRun,
  patchRun,
  listRuns,
  getRun,
  forgetShellRun,
  reconcileOrphans,
  isYoungRun,
  listInterrupted,
  dismissInterrupted,
  proxyForSession,
  laneForSession,
  claimToolSessions,
};