lastlight 0.1.8 → 0.2.0

package/dist/state/migrate.js

@@ -0,0 +1,175 @@
+/**
+ * Apply the full SQLite schema for the harness state DB.
+ *
+ * Centralized here (rather than on a store) because the three stores
+ * (`WorkflowRunStore` / `ApprovalStore` / `ExecutionStore`) all share a
+ * single `Database` connection and assume the schema already exists. `StateDb`
+ * is the construction root and calls this once at boot; tests that exercise a
+ * store directly construct a raw `Database`, call `migrate()`, then build the
+ * store on top.
+ *
+ * Every statement is idempotent (`IF NOT EXISTS` / additive `ALTER` guarded by
+ * try/catch) so it is safe to run on an existing DB.
+ */
+export function migrate(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS executions (
+      id TEXT PRIMARY KEY,
+      trigger_type TEXT NOT NULL,
+      trigger_id TEXT NOT NULL,
+      skill TEXT NOT NULL,
+      repo TEXT,
+      issue_number INTEGER,
+      started_at TEXT NOT NULL,
+      finished_at TEXT,
+      success INTEGER,
+      error TEXT,
+      turns INTEGER,
+      duration_ms INTEGER
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_executions_trigger ON executions(trigger_type, trigger_id);
+    CREATE INDEX IF NOT EXISTS idx_executions_skill ON executions(skill, started_at);
+
+    CREATE TABLE IF NOT EXISTS workflow_runs (
+      id TEXT PRIMARY KEY,
+      workflow_name TEXT NOT NULL,
+      trigger_id TEXT NOT NULL,
+      repo TEXT,
+      issue_number INTEGER,
+      current_phase TEXT NOT NULL,
+      phase_history TEXT NOT NULL DEFAULT '[]',
+      status TEXT NOT NULL DEFAULT 'running',
+      context TEXT,
+      started_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      finished_at TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_workflow_runs_trigger ON workflow_runs(trigger_id, status);
+    CREATE INDEX IF NOT EXISTS idx_workflow_runs_status ON workflow_runs(status);
+    -- Dashboard's workflow-runs list query is ORDER BY started_at DESC
+    -- LIMIT 20, often with optional workflow_name / status filters and a
+    -- companion COUNT(*). It polls every 5s, so it's worth a covering
+    -- index — without one this is a full-table sort.
+    CREATE INDEX IF NOT EXISTS idx_workflow_runs_started_at ON workflow_runs(started_at DESC);
+    CREATE INDEX IF NOT EXISTS idx_workflow_runs_name_started ON workflow_runs(workflow_name, started_at DESC);
+
+    CREATE TABLE IF NOT EXISTS cron_overrides (
+      name TEXT PRIMARY KEY,
+      enabled INTEGER NOT NULL DEFAULT 1,
+      schedule TEXT,
+      updated_at TEXT NOT NULL,
+      updated_by TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS workflow_overrides (
+      name TEXT PRIMARY KEY,
+      enabled INTEGER NOT NULL DEFAULT 1,
+      updated_at TEXT NOT NULL,
+      updated_by TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS workflow_approvals (
+      id TEXT PRIMARY KEY,
+      workflow_run_id TEXT NOT NULL,
+      gate TEXT NOT NULL,
+      summary TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'pending',
+      requested_by TEXT,
+      responded_by TEXT,
+      response TEXT,
+      responded_at TEXT,
+      created_at TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_approvals_workflow ON workflow_approvals(workflow_run_id);
+    CREATE INDEX IF NOT EXISTS idx_approvals_status ON workflow_approvals(status);
+  `);
+    // Mutable phase-to-phase state for features like the socratic explore
+    // loop that accumulate data across reply-gate pauses.
+    try {
+        db.exec(`ALTER TABLE workflow_runs ADD COLUMN scratch TEXT`);
+    }
+    catch {
+        // Column already exists — ignore
+    }
+    // Restart attempt counter — bumped each time resumeOrphanedWorkflows
+    // re-dispatches a still-'running' row at boot. Acts as a circuit
+    // breaker so an OOM-on-restart loop can't churn forever.
+    try {
+        db.exec(`ALTER TABLE workflow_runs ADD COLUMN restart_count INTEGER NOT NULL DEFAULT 0`);
+    }
+    catch {
+        // Column already exists — ignore
+    }
+    // Gate flavor: 'approve' (explicit approve/reject) vs 'reply' (resolves
+    // on any free-form reply in the same thread — used by the socratic
+    // explore loop).
+    try {
+        db.exec(`ALTER TABLE workflow_approvals ADD COLUMN kind TEXT NOT NULL DEFAULT 'approve'`);
+    }
+    catch {
+        // Column already exists — ignore
+    }
+    // Artifact (handoff doc) filename a gate is asking the reviewer to approve,
+    // e.g. 'architect-plan.md'. Lets the focused approval view open the right
+    // doc. Nullable — most gates carry no artifact. Additive, safe on existing DBs.
+    try {
+        db.exec(`ALTER TABLE workflow_approvals ADD COLUMN artifact TEXT`);
+    }
+    catch {
+        // Column already exists — ignore
+    }
+    // Add session_id column to executions so the dashboard can resolve a
+    // phase click to its agent session log. Additive — safe on existing DBs.
+    try {
+        db.exec(`ALTER TABLE executions ADD COLUMN session_id TEXT`);
+    }
+    catch {
+        // Column already exists — ignore
+    }
+    // Per-execution runtime usage metrics, captured from the OpenCode
+    // step_finish events. Lets the dashboard show cost / tokens per phase
+    // and lets us aggregate spend later. All additive, safe on existing DBs.
+    for (const col of [
+        "cost_usd REAL",
+        "input_tokens INTEGER",
+        "cache_creation_input_tokens INTEGER",
+        "cache_read_input_tokens INTEGER",
+        "output_tokens INTEGER",
+        "api_duration_ms INTEGER",
+        "stop_reason TEXT",
+        // Links a phase execution to its owning workflow_run. Dedup and
+        // "already running / done" checks scope to this column so a fresh
+        // re-trigger of the same workflow on the same issue creates new
+        // executions instead of reusing the old run's rows.
+        "workflow_run_id TEXT",
+        // Final assistant text for a phase execution. Populated only for
+        // loop iterations whose output is referenced by `scratch.<key>
+        // .lastOutputExecutionId` — keeps the inlined LLM output out of
+        // `workflow_runs.scratch` (which is read on every list query)
+        // while still being available to the runner's resume path.
+        "output_text TEXT",
+        // JSON map of agentic-pi extensions active for this execution
+        // (file-search / github / web-search → {status, mode?, provider?,
+        // toolCount?, reason?}). Surfaced in the dashboard phase-detail panel.
+        "extension_status TEXT",
+        // JSON object of agentic-pi's skill-loading status for this execution
+        // ({status, discovered, skills[], mappedPaths, noSkills}). The skill-
+        // loading counterpart to extension_status; surfaced in the same panel.
+        "skills_status TEXT",
+    ]) {
+        try {
+            db.exec(`ALTER TABLE executions ADD COLUMN ${col}`);
+        }
+        catch {
+            // Column already exists — ignore
+        }
+    }
+    try {
+        db.exec(`CREATE INDEX IF NOT EXISTS idx_executions_workflow_run ON executions(workflow_run_id, skill)`);
+    }
+    catch {
+        // Index already exists — ignore
+    }
+}
+//# sourceMappingURL=migrate.js.map

package/dist/state/migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../../src/state/migrate.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,OAAO,CAAC,EAAqB;IAC3C,EAAE,CAAC,IAAI,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEP,CAAC,CAAC;IAEH,sEAAsE;IACtE,sDAAsD;IACtD,IAAI,CAAC;QACH,EAAE,CAAC,IAAI,CAAC,mDAAmD,CAAC,CAAC;IAC/D,CAAC;IAAC,MAAM,CAAC;QACP,iCAAiC;IACnC,CAAC;IAED,qEAAqE;IACrE,iEAAiE;IACjE,yDAAyD;IACzD,IAAI,CAAC;QACH,EAAE,CAAC,IAAI,CAAC,+EAA+E,CAAC,CAAC;IAC3F,CAAC;IAAC,MAAM,CAAC;QACP,iCAAiC;IACnC,CAAC;IAED,wEAAwE;IACxE,mEAAmE;IACnE,iBAAiB;IACjB,IAAI,CAAC;QACH,EAAE,CAAC,IAAI,CAAC,gFAAgF,CAAC,CAAC;IAC5F,CAAC;IAAC,MAAM,CAAC;QACP,iCAAiC;IACnC,CAAC;IAED,4EAA4E;IAC5E,0EAA0E;IAC1E,gFAAgF;IAChF,IAAI,CAAC;QACH,EAAE,CAAC,IAAI,CAAC,yDAAyD,CAAC,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,iCAAiC;IACnC,CAAC;IAED,qEAAqE;IACrE,yEAAyE;IACzE,IAAI,CAAC;QACH,EAAE,CAAC,IAAI,CAAC,mDAAmD,CAAC,CAAC;IAC/D,CAAC;IAAC,MAAM,CAAC;QACP,iCAAiC;IACnC,CAAC;IAED,kEAAkE;IAClE,sEAAsE;IACtE,yEAAyE;IACzE,KAAK,MAAM,GAAG,IAAI;QAChB,eAAe;QACf,sBAAsB;QACtB,qCAAqC;QACrC,iCAAiC;QACjC,uBAAuB;QACvB,yBAAyB;QACzB,kBAAkB;QAClB,gEAAgE;QAChE,kEAAkE;QAClE,gEAAgE;QAChE,oDAAoD;QACpD,sBAAsB;QACtB,iEAAiE;QACjE,+DAA+D;QAC/D,gEAAgE;QAChE,8DAA8D;QAC9D,2DAA2D;QAC3D,kBAAkB;QAClB,8DAA8D;QAC9D,kEAAkE;QAClE,uEAAuE;QACvE,uBAAuB;QACvB,sEAAsE;QACtE,sEAAsE;QACtE,uEAAuE;QACvE,oBAAoB;KACrB,EAAE,CAAC;QACF,IAAI,CAAC;YACH,EAAE,CAAC,IAAI,CAAC,qCAAqC,GAAG,EAAE,CAAC,CAAC;QACtD,CAAC;QAAC,MAAM,CAAC;YACP,iCAAiC;QACnC,CAAC;IACH,CAAC;IACD,IAAI,CAAC;QACH,EAAE,CAAC,IAAI,CACL,8FAA8F,CAC/F,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,gCAAgC;IAClC,CAAC;AACH,CAAC"}

package/dist/state/workflow-run-store.d.ts

@@ -0,0 +1,195 @@
+import type Database from "better-sqlite3";
+import type { ApprovalStore } from "./approval-store.js";
+export interface PhaseHistoryEntry {
+    phase: string;
+    timestamp: string;
+    success: boolean;
+    summary?: string;
+}
+export interface WorkflowRun {
+    id: string;
+    workflowName: string;
+    triggerId: string;
+    repo?: string;
+    issueNumber?: number;
+    currentPhase: string;
+    phaseHistory: PhaseHistoryEntry[];
+    status: "running" | "paused" | "succeeded" | "failed" | "cancelled";
+    context?: Record<string, unknown>;
+    /**
+     * Mutable phase-to-phase state, merged at the top level by
+     * `mergeScratch`. Distinct from `context` (which is the immutable trigger
+     * input) — used by features like the socratic explore loop to accumulate
+     * Q&A across reply-gate pauses.
+     */
+    scratch?: Record<string, unknown>;
+    /**
+     * Number of times `resumeOrphanedWorkflows` has re-dispatched this run
+     * after a harness restart. Bounded by a small limit so a run that
+     * crashes the host (e.g. agent OOM) is marked failed instead of
+     * retried forever.
+     */
+    restartCount?: number;
+    startedAt: string;
+    updatedAt: string;
+    finishedAt?: string;
+}
+/** A non-agent phase marker folded into an atomic lifecycle op. */
+export interface PhaseMarker {
+    phase: string;
+    summary?: string;
+}
+/**
+ * Aggregate root for a workflow run's lifecycle. Owns the `workflow_runs`
+ * table (including the `phase_history` JSON column) and the named, atomic
+ * transitions a run moves through: create → pause-for-approval →
+ * resume/finish, plus gate resolution and the socratic reply append.
+ *
+ * Carved out of the old `StateDb` god-class (issue #97). The deepening: every
+ * multi-step mutation that previously lived as an un-guarded read-modify-write
+ * chain in `index.ts` / `admin/routes.ts` / `phase-executor.ts` is now a
+ * single named operation wrapped in ONE `better-sqlite3` transaction — a throw
+ * partway through rolls the whole thing back, so a run can never be left
+ * marked `running` with its gate unresolved (the hazard the issue calls out).
+ *
+ * Constructed with an injected {@link ApprovalStore}: an approval has no life
+ * independent of its run, so the cross-table ops call the approval store's
+ * single-table writes from inside this store's transaction. Both stores MUST
+ * be built from the same `Database` — better-sqlite3 transactions are
+ * per-connection.
+ *
+ * The long-running re-dispatch (`dispatchWorkflow`, which spawns a Docker
+ * sandbox for minutes) is deliberately NOT part of any transaction here —
+ * better-sqlite3 transactions are synchronous. The atomic boundary is the DB
+ * mutations only; the caller dispatches after the transaction commits.
+ */
+export declare class WorkflowRunStore {
+    private db;
+    private approvals;
+    constructor(db: Database.Database, deps: {
+        approvals: ApprovalStore;
+    });
+    /** Create a new workflow run record */
+    createRun(run: Omit<WorkflowRun, "phaseHistory" | "updatedAt">): void;
+    /**
+     * Top-level merge of `patch` into the workflow run's scratch state.
+     * Loop iterations can append to `scratch.socratic.qa` without clobbering
+     * other keys.
+     *
+     * Throws if `patch` is not JSON-serializable (e.g. it contains a BigInt) —
+     * which is exactly how the atomic ops prove their rollback: a poison patch
+     * makes `JSON.stringify` throw mid-transaction.
+     */
+    mergeScratch(id: string, patch: Record<string, unknown>): void;
+    /**
+     * Update the current phase and append to phase history. This is the single
+     * seam through which all phase-history writes flow (issue #97 defers the
+     * full `phase_history`/`executions` reconciliation to a follow-up, but
+     * routes every write through here so that future change touches one method
+     * instead of ~10 call sites).
+     */
+    appendPhase(id: string, phase: string, entry: PhaseHistoryEntry): void;
+    /** Get a single workflow run by ID */
+    getRun(id: string): WorkflowRun | null;
+    /** Find the most recent active (running or paused) workflow run for a trigger */
+    getByTrigger(triggerId: string): WorkflowRun | null;
+    /** List all active (running or paused) workflow runs */
+    listActive(): WorkflowRun[];
+    /** List recent workflow runs, ordered by start time descending */
+    listRecent(limit?: number): WorkflowRun[];
+    /**
+     * List workflow runs with pagination + filters. Returns the page slice
+     * AND the post-filter total so the dashboard knows how many remain.
+     *
+     * - sinceIso filters `started_at >= sinceIso` (used for the header date range).
+     * - workflowName filters by exact `workflow_name`.
+     * - statuses filters to one of the workflow statuses (`running`, `paused`,
+     *   `succeeded`, `failed`, `cancelled`). Used for the dashboard's "live"
+     *   filter, which maps to ['running','paused'].
+     */
+    list(opts?: {
+        limit?: number;
+        offset?: number;
+        sinceIso?: string;
+        workflowName?: string;
+        statuses?: string[];
+    }): {
+        runs: WorkflowRun[];
+        total: number;
+    };
+    /** Distinct workflow_name values, sorted alphabetically. */
+    distinctNames(): string[];
+    /**
+     * Mark a workflow run as finished. Plain status flip when called with just
+     * `{ error }`; when a `terminalMarker` is supplied (the runner's
+     * `on_success.set_phase`), the phase-history append and the status flip
+     * happen in ONE transaction so the dashboard never sees the terminal phase
+     * without the finished status, or vice versa.
+     */
+    finishRun(id: string, status: "succeeded" | "failed" | "cancelled", opts?: {
+        error?: string;
+        terminalMarker?: PhaseMarker;
+    }): void;
+    private flipFinished;
+    /** Cancel a workflow run */
+    cancelRun(id: string): void;
+    /** Pause a workflow run (waiting for approval) */
+    setPaused(id: string): void;
+    /** Resume a paused workflow run (set back to running) */
+    setRunning(id: string): void;
+    /**
+     * Increment the restart counter and return the new value. Used by
+     * `resumeOrphanedWorkflows` to enforce a retry budget so a run that
+     * crashes the host (agent OOM, etc.) eventually self-terminates instead
+     * of being re-dispatched on every boot.
+     */
+    incrementRestartCount(id: string): number;
+    private deserialize;
+    /**
+     * Resolve a socratic reply gate and resume the run, atomically: the reply
+     * gate flips `pending → approved` (recording the reply text), the caller's
+     * scratch patch merges in, and the run goes back to `running` — all in one
+     * transaction. A throw anywhere rolls the whole thing back, so the run can
+     * never be left `running` with its gate unresolved or its reply lost (the
+     * hazard issue #97 calls out).
+     *
+     * The reply-gate resolve is guarded by `kind = 'reply' AND status = 'pending'`
+     * (see {@link ApprovalStore.resolveReplyGate}); if it changes zero rows —
+     * because a racing reply already resolved the gate — this throws and the
+     * transaction aborts, which is the double-reply concurrency guard.
+     *
+     * The caller (`index.ts`) computes the explore-domain `scratch.socratic.qa`
+     * patch and passes it in; the generic store stays ignorant of that shape.
+     */
+    /**
+     * Pause a run for an approval gate, atomically: create the pending approval,
+     * optionally merge a scratch patch (loops persist their iteration state
+     * here), append the `waiting_approval` phase marker, and flip the run to
+     * `paused` — all in one transaction. Covers the standard post-phase gate,
+     * the reviewer-loop gate, and the interactive generic-loop gate.
+     *
+     * The marker is appended BEFORE the approval insert so that an insert
+     * failure provably rolls back the phase-history write (the injected
+     * ApprovalStore participates in the same transaction); ordering is invisible
+     * outside the transaction.
+     */
+    pauseForApproval(runId: string, approval: Parameters<ApprovalStore["create"]>[0], marker: PhaseMarker, scratchPatch?: Record<string, unknown>): void;
+    /**
+     * Approve a gate and resume its run, atomically. Reads the approval to find
+     * its run, records the `approved` response, and flips the run back to
+     * `running` in one transaction; returns the run so the caller can dispatch.
+     * Used by the GitHub/Slack path (`index.ts`), which validates the dispatch
+     * target BEFORE calling this so the flip to `running` is always followed by a
+     * dispatch. The dashboard path does NOT use this — it can't prove a dispatch
+     * will follow before responding, so it records the approval and lets
+     * `resumeWorkflow` flip the run only as part of an actual dispatch.
+     */
+    resolveGateAndResume(approvalId: string, responder: string): WorkflowRun | null;
+    /**
+     * Reject a gate and fail its run, atomically: record the `rejected` response
+     * (with reason) and flip the run to `failed` in one transaction. Returns the
+     * run (or null if the approval's run was already gone).
+     */
+    resolveGateAndFail(approvalId: string, responder: string, reason?: string): WorkflowRun | null;
+    resolveReplyGateAndResume(runId: string, approvalId: string, replyText: string, responder: string, scratchPatch: Record<string, unknown>): WorkflowRun | null;
+}