lastlight 0.1.8 → 0.2.0

package/dist/state/db.d.ts

@@ -1,348 +1,80 @@
 import Database from "better-sqlite3";
-export interface PhaseHistoryEntry {
-    phase: string;
-    timestamp: string;
-    success: boolean;
-    summary?: string;
-}
-export interface WorkflowApproval {
-    id: string;
-    workflowRunId: string;
-    gate: string;
-    summary: string;
-    status: 'pending' | 'approved' | 'rejected';
-    /**
-     * Gate flavor. `approve` gates resolve only on an explicit approve/reject
-     * command; `reply` gates resolve on any free-form reply in the same
-     * thread (used by the socratic explore loop).
-     */
-    kind: 'approve' | 'reply';
-    requestedBy?: string;
-    respondedBy?: string;
-    response?: string;
-    respondedAt?: string;
-    createdAt: 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
-     * `updateWorkflowRunScratch`. 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>;
-    nodeStatuses?: Record<string, "pending" | "running" | "succeeded" | "failed" | "skipped">;
-    startedAt: string;
+import { ExecutionStore } from "./execution-store.js";
+import { ApprovalStore } from "./approval-store.js";
+import { WorkflowRunStore } from "./workflow-run-store.js";
+export type { ExecutionRecord } from "./execution-store.js";
+export type { WorkflowApproval } from "./approval-store.js";
+export type { WorkflowRun, PhaseHistoryEntry, PhaseMarker } from "./workflow-run-store.js";
+export { ExecutionStore } from "./execution-store.js";
+export { ApprovalStore } from "./approval-store.js";
+export { WorkflowRunStore } from "./workflow-run-store.js";
+export interface CronOverride {
+    name: string;
+    enabled: boolean;
+    /** Cron expression overriding the YAML default; null means use the YAML value. */
+    schedule: string | null;
     updatedAt: string;
-    finishedAt?: string;
+    updatedBy: string | null;
 }
-export interface ExecutionRecord {
-    id: string;
-    triggerType: "webhook" | "cron" | "chat" | "api";
-    triggerId: string;
-    skill: string;
-    repo?: string;
-    issueNumber?: number;
-    startedAt: string;
-    finishedAt?: string;
-    success?: boolean;
-    error?: string;
-    turns?: number;
-    durationMs?: number;
-    /**
-     * Agent SDK session id captured from the stream-json `system/init` line.
-     * Used by the dashboard to look up the session log for a given phase.
-     */
-    sessionId?: string;
-    /** Total USD cost reported by Claude on the final result message. */
-    costUsd?: number;
-    /** Fresh input tokens (no cache hit). */
-    inputTokens?: number;
-    /** Tokens that triggered a cache write. */
-    cacheCreationInputTokens?: number;
-    /** Tokens served from prompt cache. */
-    cacheReadInputTokens?: number;
-    /** Output tokens generated by the model. */
-    outputTokens?: number;
-    /** API-side duration (excludes orchestrator overhead). */
-    apiDurationMs?: number;
-    /** Result subtype, e.g. "success" or "error_max_turns". */
-    stopReason?: string;
-    /**
-     * Workflow run that owns this execution. Scopes dedup: a fresh re-trigger
-     * creates a new workflow_run_id, so `shouldRunPhase` won't find matching
-     * rows from the prior run and will correctly run the phase again.
-     */
-    workflowRunId?: string;
+/**
+ * Per-workflow kill switch persisted to SQLite. When `enabled` is false,
+ * `runSimpleWorkflow` short-circuits and does not create a `workflow_runs`
+ * row — applies to every trigger source (cron, webhooks, mentions, Slack).
+ * No row at all means "enabled" (default).
+ */
+export interface WorkflowOverride {
+    name: string;
+    enabled: boolean;
+    updatedAt: string;
+    updatedBy: string | null;
 }
 /**
  * Lightweight SQLite state for operational tracking.
  * NOT for conversation history — only execution logs and rate limits.
+ *
+ * Construction root for the three per-table stores (issue #97): it opens the
+ * single `Database` connection, runs {@link migrate}, and builds
+ * {@link ExecutionStore} / {@link ApprovalStore} / {@link WorkflowRunStore} on
+ * top of it (all sharing the one connection so better-sqlite3 transactions
+ * span every store). Callers reach the stores via `db.runs` / `db.approvals` /
+ * `db.executions`. StateDb itself retains only the cross-cutting cron-override
+ * and workflow kill-switch concerns.
  */
 export declare class StateDb {
     private db;
+    /** Owns the `executions` ledger. */
+    readonly executions: ExecutionStore;
+    /** Owns the `workflow_approvals` table. */
+    readonly approvals: ApprovalStore;
+    /** Aggregate root for `workflow_runs` + the atomic lifecycle operations. */
+    readonly runs: WorkflowRunStore;
     constructor(dbPath?: string);
-    private migrate;
-    recordStart(record: Omit<ExecutionRecord, "finishedAt" | "success" | "error" | "turns" | "durationMs">): void;
-    /**
-     * Mid-run update: persist the agent session id as soon as the executor sees
-     * the stream-json `system/init` line. Lets the dashboard surface the live
-     * session log for an in-flight phase, not just for completed ones.
-     */
-    recordSessionId(id: string, sessionId: string): void;
-    recordFinish(id: string, result: {
-        success: boolean;
-        error?: string;
-        turns?: number;
-        durationMs?: number;
-        sessionId?: string;
-        costUsd?: number;
-        inputTokens?: number;
-        cacheCreationInputTokens?: number;
-        cacheReadInputTokens?: number;
-        outputTokens?: number;
-        apiDurationMs?: number;
-        stopReason?: string;
-    }): void;
-    /**
-     * List chat threads aggregated from the executions table.
-     *
-     * Each row collapses every execution sharing a `trigger_id` (the messaging
-     * session id) into one summary so the dashboard's chat-sessions tab can
-     * show one card per Slack thread, not one per turn. Joined with
-     * `messaging_sessions` for the agent SDK session id (used to resolve to
-     * the on-disk jsonl when streaming messages) and with `messaging_messages`
-     * for the most recent assistant text (preview snippet).
-     */
-    listChatThreads(limit: number): {
-        triggerId: string;
-        agentSessionId: string | null;
-        firstStartedAt: string;
-        lastActivityAt: string;
-        turnCount: number;
-        totalCost: number;
-        inputTokens: number;
-        outputTokens: number;
-        cacheReadTokens: number;
-        lastAssistantContent: string | null;
-    }[];
-    /** Look up a single chat thread by its messaging session id (= trigger_id). */
-    getChatThread(triggerId: string): {
-        triggerId: string;
-        agentSessionId: string | null;
-        firstStartedAt: string;
-        lastActivityAt: string;
-        turnCount: number;
-        totalCost: number;
-        inputTokens: number;
-        outputTokens: number;
-        cacheReadTokens: number;
-        lastAssistantContent: string | null;
-    } | null;
-    /** Check if a skill is currently running for a given trigger */
-    isRunning(skill: string, triggerId: string): boolean;
-    /** Check if a skill has already completed successfully for a given trigger */
-    isCompleted(skill: string, triggerId: string): boolean;
-    /**
-     * Check if a phase should run: not currently running AND not already
-     * succeeded. When `workflowRunId` is provided, scopes the check to that
-     * specific run — a fresh re-trigger (new workflow_run_id) will see no
-     * matching rows and correctly return "run" even if a prior completed run
-     * for the same trigger exists. Omit `workflowRunId` for legacy callers
-     * (e.g. chat/status-report dedup) that want the old trigger-wide scope.
-     */
-    shouldRunPhase(skill: string, triggerId: string, workflowRunId?: string): "run" | "running" | "done";
-    /** Mark all stale "running" executions for a skill/trigger as failed.
-     *  Called when we detect no matching Docker container is alive. */
-    markStaleAsFailed(skill: string, triggerId: string, workflowRunId?: string): number;
-    /**
-     * Mark every unfinished execution row for a trigger as failed, regardless
-     * of skill. Used by the boot-time recovery sweep to clear out phases that
-     * were running when the harness crashed/restarted, so the runner's dedup
-     * logic doesn't think they're still in flight.
-     */
-    markAllStaleForTrigger(triggerId: string, reason: string): number;
-    /**
-     * Mark the most recent execution for a skill/trigger as failed.
-     * Used when the agent SDK reported success but the orchestrator decided
-     * the business outcome was a failure (e.g. guardrails BLOCKED, reviewer
-     * REQUEST_CHANGES). Without this, runPhase would skip the phase on the
-     * next run because the DB still says success=1.
-     */
-    markLatestAsFailed(skill: string, triggerId: string, reason: string, workflowRunId?: string): number;
-    /** Get recent executions for a skill */
-    recentExecutions(skill: string, limit?: number): ExecutionRecord[];
-    /** Count consecutive failures for a skill (for cron failure tracking) */
-    consecutiveFailures(skill: string): number;
-    /** Update rate limit state */
-    updateRateLimit(resource: string, remaining: number, resetAt: string): void;
-    /** Get all rate limit records */
-    getRateLimits(): Array<{
-        resource: string;
-        remaining: number;
-        reset_at: string;
-        updated_at: string;
-    }>;
-    /**
-     * Get the current state of a system component.
-     * Returns null if the component has never reported.
-     */
-    getSystemStatus(component: string): {
-        state: string;
-        reason: string | null;
-        since: string;
-        updated_at: string;
-    } | null;
-    /**
-     * Set the state of a system component. If the new state differs from the
-     * current state, updates `since` to now (transition timestamp). Returns
-     * true on transition (state changed), false on refresh (state unchanged).
-     */
-    setSystemStatus(component: string, state: string, reason?: string): boolean;
-    /** List all known component statuses. */
-    listSystemStatus(): Array<{
-        component: string;
-        state: string;
-        reason: string | null;
-        since: string;
-        updated_at: string;
-    }>;
-    /** Get all executions with pagination */
-    allExecutions(limit?: number, offset?: number): ExecutionRecord[];
-    /**
-     * Get every execution recorded for a workflow run, with camelCase fields
-     * ready for the dashboard. Ordered by start time ascending so phases
-     * display in the order they ran. Scopes to a specific `workflow_run_id`
-     * when provided (preferred — isolates fresh re-triggers from prior runs);
-     * falls back to the legacy trigger-wide scope for rows written before the
-     * workflow_run_id column existed.
-     */
-    getExecutionsForWorkflowRun(workflowRunId: string, triggerId: string, workflowName?: string): ExecutionRecord[];
-    /** Get currently running executions (no finished_at) */
-    runningExecutions(): ExecutionRecord[];
-    /** Aggregate execution stats */
-    executionStats(): {
-        total_executions: number;
-        today_count: number;
-        by_skill: Record<string, {
-            count: number;
-            success: number;
-            fail: number;
-        }>;
-        by_trigger: Record<string, number>;
-        running: number;
-    };
-    /** Daily aggregated stats for the last N days */
-    dailyStats(days: number): {
-        date: string;
-        executions: number;
-        successes: number;
-        failures: number;
-        totalTokens: number;
-        inputTokens: number;
-        outputTokens: number;
-        cacheReadTokens: number;
-        costUsd: number;
-    }[];
-    /** Hourly aggregated stats for the last N hours (UTC). Bucket key is `YYYY-MM-DDTHH`. */
-    hourlyStats(hours: number): {
-        date: string;
-        executions: number;
-        successes: number;
-        failures: number;
-        totalTokens: number;
-        inputTokens: number;
-        outputTokens: number;
-        cacheReadTokens: number;
-        costUsd: number;
-    }[];
-    /** Create a new workflow run record */
-    createWorkflowRun(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.
-     */
-    updateWorkflowRunScratch(id: string, patch: Record<string, unknown>): void;
-    /** Update the current phase and append to phase history */
-    updateWorkflowPhase(id: string, phase: string, entry: PhaseHistoryEntry): void;
-    /** Mark a workflow run as finished */
-    finishWorkflowRun(id: string, status: "succeeded" | "failed" | "cancelled", error?: string): void;
-    /** Get a single workflow run by ID */
-    getWorkflowRun(id: string): WorkflowRun | null;
-    /** Find the most recent active (running or paused) workflow run for a trigger */
-    getWorkflowRunByTrigger(triggerId: string): WorkflowRun | null;
-    /** List all active (running or paused) workflow runs */
-    activeWorkflowRuns(): WorkflowRun[];
-    /** List recent workflow runs, ordered by start time descending */
-    recentWorkflowRuns(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'].
-     */
-    listWorkflowRuns(opts?: {
-        limit?: number;
-        offset?: number;
-        sinceIso?: string;
-        workflowName?: string;
-        statuses?: string[];
-    }): {
-        runs: WorkflowRun[];
-        total: number;
-    };
-    /** Distinct workflow_name values, sorted alphabetically. */
-    distinctWorkflowNames(): string[];
-    /** Cancel a workflow run */
-    cancelWorkflowRun(id: string): void;
-    /** Pause a workflow run (waiting for approval) */
-    pauseWorkflowRun(id: string): void;
-    /** Resume a paused workflow run (set back to running) */
-    resumeWorkflowRun(id: string): void;
-    /** Create a new pending approval request */
-    createApproval(approval: Omit<WorkflowApproval, "status" | "respondedBy" | "response" | "respondedAt" | "kind"> & {
-        kind?: WorkflowApproval["kind"];
+    /** Get the override row for a single cron, or null if none. */
+    getCronOverride(name: string): CronOverride | null;
+    /** All override rows keyed by cron name. */
+    getAllCronOverrides(): Map<string, CronOverride>;
+    /**
+     * Upsert an override. Pass only the fields you want to change — undefined
+     * fields preserve the existing value (or default to enabled=1, schedule=null
+     * on insert).
+     */
+    setCronOverride(name: string, patch: {
+        enabled?: boolean;
+        schedule?: string | null;
+        updatedBy?: string;
     }): void;
-    /**
-     * Resolve a reply gate: marks the approval row as approved (reply gates
-     * don't have approve/reject semantics — any reply is a "go") and stores
-     * the reply text as the `response`. Used by the socratic explore loop.
-     */
-    resolveReplyGate(id: string, replyText: string, responder: string): void;
-    /**
-     * Find the most recent pending reply gate for a given trigger id. Used by
-     * the router to short-circuit free-form replies on a paused socratic
-     * explore loop without re-running classifier logic.
-     */
-    getPendingReplyGateByTrigger(triggerId: string): WorkflowApproval | null;
-    /** Get a single approval by ID */
-    getApproval(id: string): WorkflowApproval | null;
-    /** Find the pending approval for a workflow run */
-    getPendingApprovalForWorkflow(workflowRunId: string): WorkflowApproval | null;
-    /** Find the pending approval by trigger ID (join with workflow_runs) */
-    getPendingApprovalByTrigger(triggerId: string): WorkflowApproval | null;
-    /** List all pending approvals */
-    listPendingApprovals(): WorkflowApproval[];
-    /** Record the response to an approval */
-    respondToApproval(id: string, status: 'approved' | 'rejected', respondedBy: string, response?: string): void;
-    /** Update a single node's status in the workflow run's nodeStatuses map. */
-    updateNodeStatus(workflowId: string, nodeName: string, status: "pending" | "running" | "succeeded" | "failed" | "skipped"): void;
-    private deserializeApproval;
-    private deserializeWorkflowRun;
+    /** Remove the override entirely (revert to YAML defaults). */
+    clearCronOverride(name: string): void;
+    private deserializeCronOverride;
+    /**
+     * Cheap check used by every dispatch path. Returns true unless an explicit
+     * `workflow_overrides` row says otherwise.
+     */
+    isWorkflowEnabled(name: string): boolean;
+    getWorkflowOverride(name: string): WorkflowOverride | null;
+    getAllWorkflowOverrides(): Map<string, WorkflowOverride>;
+    setWorkflowEnabled(name: string, enabled: boolean, updatedBy?: string): void;
+    private deserializeWorkflowOverride;
     /** Expose the underlying Database instance (for SessionManager, etc.) */
     get database(): Database.Database;
     close(): void;