@hasna/loops 0.4.14 → 0.4.23

package/dist/lib/store/index.d.ts

@@ -0,0 +1,268 @@
+import type { CreateLoopInput, CreateWorkflowInput, Loop, LoopRun, LoopStatus, RunReceipt, RunStatus, WorkflowEvent, WorkflowInvocation, WorkflowRun, WorkflowSpec, WorkflowStepRun, WorkflowWorkItem, WorkflowWorkItemStatus, WriteRunReceiptInput } from "../../types.js";
+import type { Goal, GoalPlanNode, GoalRun, GoalStatus } from "../goal/types.js";
+import type { HasnaStorageClient } from "../cloud/storage.js";
+import type { Env } from "../cloud/mode.js";
+import { Store } from "../store.js";
+import type { PruneHistoryOptions, PruneHistorySummary } from "../store.js";
+/** Which transport backs a resolved store (for banners/diagnostics only). */
+export type StoreTransport = "local" | "cloud-http";
+/**
+ * Thrown when a command routed through the cloud ApiStore hits an operation that
+ * the hosted `/v1` API does not yet expose. Failing loudly here is deliberate:
+ * the alternative (silently reading/writing the on-box sqlite island while the
+ * machine is flipped to cloud) is exactly the split-brain bug we are removing.
+ */
+export declare class CloudUnsupportedError extends Error {
+    constructor(operation: string);
+}
+/**
+ * The single data interface for the OpenLoops client. Both {@link LocalStore}
+ * and {@link ApiStore} implement it; callers hold a `LoopStore` and never know
+ * (or branch on) which one. Every method is async so the two transports share
+ * one surface.
+ */
+export interface LoopStore {
+    readonly transport: StoreTransport;
+    close(): Promise<void>;
+    createLoop(input: CreateLoopInput, from?: Date): Promise<Loop>;
+    getLoop(id: string): Promise<Loop | undefined>;
+    findLoopByName(name: string): Promise<Loop | undefined>;
+    requireLoop(idOrName: string): Promise<Loop>;
+    requireUniqueLoop(idOrName: string): Promise<Loop>;
+    listLoops(opts?: {
+        status?: LoopStatus;
+        limit?: number;
+        offset?: number;
+        archived?: boolean;
+        includeArchived?: boolean;
+        name?: string;
+    }): Promise<Loop[]>;
+    countLoops(status?: LoopStatus, opts?: {
+        archived?: boolean;
+        includeArchived?: boolean;
+    }): Promise<number>;
+    updateLoop(id: string, patch: Partial<Pick<Loop, "status" | "nextRunAt" | "retryScheduledFor" | "expiresAt">>): Promise<Loop>;
+    renameLoop(id: string, name: string): Promise<Loop>;
+    archiveLoop(idOrName: string): Promise<Loop>;
+    unarchiveLoop(idOrName: string): Promise<Loop>;
+    deleteLoop(idOrName: string): Promise<boolean>;
+    createWorkflow(input: CreateWorkflowInput): Promise<WorkflowSpec>;
+    getWorkflow(id: string): Promise<WorkflowSpec | undefined>;
+    findWorkflowByName(name: string): Promise<WorkflowSpec | undefined>;
+    requireWorkflow(idOrName: string): Promise<WorkflowSpec>;
+    listWorkflows(opts?: {
+        status?: WorkflowSpec["status"];
+        limit?: number;
+        offset?: number;
+    }): Promise<WorkflowSpec[]>;
+    countWorkflows(opts?: {
+        status?: WorkflowSpec["status"];
+    }): Promise<number>;
+    archiveWorkflow(idOrName: string): Promise<WorkflowSpec>;
+    getWorkflowRun(id: string): Promise<WorkflowRun | undefined>;
+    requireWorkflowRun(id: string): Promise<WorkflowRun>;
+    listWorkflowRuns(opts?: {
+        workflowId?: string;
+        loopRunId?: string;
+        limit?: number;
+    }): Promise<WorkflowRun[]>;
+    listWorkflowStepRuns(workflowRunId: string): Promise<WorkflowStepRun[]>;
+    listWorkflowEvents(workflowRunId: string, limit?: number): Promise<WorkflowEvent[]>;
+    recoverWorkflowRun(workflowRunId: string, reason?: string): Promise<{
+        run: WorkflowRun;
+        recoveredSteps: WorkflowStepRun[];
+    }>;
+    cancelWorkflowRun(workflowRunId: string, reason?: string): Promise<WorkflowRun>;
+    listWorkflowWorkItems(opts?: {
+        status?: WorkflowWorkItemStatus;
+        routeKey?: string;
+        limit?: number;
+    }): Promise<WorkflowWorkItem[]>;
+    getWorkflowWorkItem(id: string): Promise<WorkflowWorkItem | undefined>;
+    requeueWorkflowWorkItem(id: string, patch?: {
+        reason?: string;
+    }): Promise<WorkflowWorkItem>;
+    listWorkflowInvocations(opts?: {
+        limit?: number;
+    }): Promise<WorkflowInvocation[]>;
+    getWorkflowInvocation(id: string): Promise<WorkflowInvocation | undefined>;
+    getGoal(id: string): Promise<Goal | undefined>;
+    findGoalByLoop(idOrName: string): Promise<Goal | undefined>;
+    findGoalByRunId(id: string): Promise<Goal | undefined>;
+    listGoals(opts?: {
+        status?: GoalStatus;
+        limit?: number;
+    }): Promise<Goal[]>;
+    listGoalPlanNodes(goalIdOrPlanId: string): Promise<GoalPlanNode[]>;
+    listGoalRuns(opts?: {
+        goalId?: string;
+        runId?: string;
+        limit?: number;
+    }): Promise<GoalRun[]>;
+    listRuns(opts?: {
+        loopId?: string;
+        status?: RunStatus;
+        limit?: number;
+        offset?: number;
+    }): Promise<LoopRun[]>;
+    getRun(id: string): Promise<LoopRun | undefined>;
+    writeRunReceipt(input: WriteRunReceiptInput): Promise<RunReceipt>;
+    getRunReceipt(runId: string): Promise<RunReceipt | undefined>;
+    listRunReceipts(opts?: {
+        loopId?: string;
+        repo?: string;
+        taskId?: string;
+        knowledgeId?: string;
+        status?: string;
+        limit?: number;
+    }): Promise<RunReceipt[]>;
+    pruneHistory(opts: PruneHistoryOptions): Promise<PruneHistorySummary>;
+}
+/**
+ * On-box SQLite transport. Wraps a single {@link Store} and awaits its
+ * synchronous methods so callers see the async {@link LoopStore} surface.
+ */
+export declare class LocalStore implements LoopStore {
+    readonly transport: "local";
+    private readonly store;
+    constructor(store?: Store);
+    /**
+     * The underlying on-box sqlite {@link Store}. Exposed ONLY for genuinely
+     * local-runtime operations that cannot route over HTTP — the scheduler
+     * (tick/run-now inline execution), migration import/export, and local
+     * diagnostics (doctor/health/daemon status). Callers must gate on
+     * `transport === "local"` first; the hosted ApiStore has no `raw` store, so
+     * these operations fail loudly in cloud mode instead of touching an island.
+     */
+    get raw(): Store;
+    close(): Promise<void>;
+    createLoop(input: CreateLoopInput, from?: Date): Promise<Loop>;
+    getLoop(id: string): Promise<Loop | undefined>;
+    findLoopByName(name: string): Promise<Loop | undefined>;
+    requireLoop(idOrName: string): Promise<Loop>;
+    requireUniqueLoop(idOrName: string): Promise<Loop>;
+    listLoops(opts?: Parameters<Store["listLoops"]>[0]): Promise<Loop[]>;
+    countLoops(status?: LoopStatus, opts?: {
+        archived?: boolean;
+        includeArchived?: boolean;
+    }): Promise<number>;
+    updateLoop(id: string, patch: Partial<Pick<Loop, "status" | "nextRunAt" | "retryScheduledFor" | "expiresAt">>): Promise<Loop>;
+    renameLoop(id: string, name: string): Promise<Loop>;
+    archiveLoop(idOrName: string): Promise<Loop>;
+    unarchiveLoop(idOrName: string): Promise<Loop>;
+    deleteLoop(idOrName: string): Promise<boolean>;
+    createWorkflow(input: CreateWorkflowInput): Promise<WorkflowSpec>;
+    getWorkflow(id: string): Promise<WorkflowSpec | undefined>;
+    findWorkflowByName(name: string): Promise<WorkflowSpec | undefined>;
+    requireWorkflow(idOrName: string): Promise<WorkflowSpec>;
+    listWorkflows(opts?: Parameters<Store["listWorkflows"]>[0]): Promise<WorkflowSpec[]>;
+    countWorkflows(opts?: {
+        status?: WorkflowSpec["status"];
+    }): Promise<number>;
+    archiveWorkflow(idOrName: string): Promise<WorkflowSpec>;
+    getWorkflowRun(id: string): Promise<WorkflowRun | undefined>;
+    requireWorkflowRun(id: string): Promise<WorkflowRun>;
+    listWorkflowRuns(opts?: Parameters<Store["listWorkflowRuns"]>[0]): Promise<WorkflowRun[]>;
+    listWorkflowStepRuns(workflowRunId: string): Promise<WorkflowStepRun[]>;
+    listWorkflowEvents(workflowRunId: string, limit?: number): Promise<WorkflowEvent[]>;
+    recoverWorkflowRun(workflowRunId: string, reason?: string): Promise<{
+        run: WorkflowRun;
+        recoveredSteps: WorkflowStepRun[];
+    }>;
+    cancelWorkflowRun(workflowRunId: string, reason?: string): Promise<WorkflowRun>;
+    listWorkflowWorkItems(opts?: Parameters<Store["listWorkflowWorkItems"]>[0]): Promise<WorkflowWorkItem[]>;
+    getWorkflowWorkItem(id: string): Promise<WorkflowWorkItem | undefined>;
+    requeueWorkflowWorkItem(id: string, patch?: {
+        reason?: string;
+    }): Promise<WorkflowWorkItem>;
+    listWorkflowInvocations(opts?: Parameters<Store["listWorkflowInvocations"]>[0]): Promise<WorkflowInvocation[]>;
+    getWorkflowInvocation(id: string): Promise<WorkflowInvocation | undefined>;
+    getGoal(id: string): Promise<Goal | undefined>;
+    findGoalByLoop(idOrName: string): Promise<Goal | undefined>;
+    findGoalByRunId(id: string): Promise<Goal | undefined>;
+    listGoals(opts?: Parameters<Store["listGoals"]>[0]): Promise<Goal[]>;
+    listGoalPlanNodes(goalIdOrPlanId: string): Promise<GoalPlanNode[]>;
+    listGoalRuns(opts?: Parameters<Store["listGoalRuns"]>[0]): Promise<GoalRun[]>;
+    listRuns(opts?: Parameters<Store["listRuns"]>[0]): Promise<LoopRun[]>;
+    getRun(id: string): Promise<LoopRun | undefined>;
+    writeRunReceipt(input: WriteRunReceiptInput): Promise<RunReceipt>;
+    getRunReceipt(runId: string): Promise<RunReceipt | undefined>;
+    listRunReceipts(opts?: Parameters<Store["listRunReceipts"]>[0]): Promise<RunReceipt[]>;
+    pruneHistory(opts: PruneHistoryOptions): Promise<PruneHistorySummary>;
+}
+/**
+ * Self_hosted / cloud transport: routes every read+write through the hosted
+ * `/v1` API. Loop/name resolution (requireLoop/requireUniqueLoop/find*) is done
+ * client-side by listing and matching, mirroring the local Store behaviour, so a
+ * server that ignores a name filter can never return the wrong row.
+ */
+export declare class ApiStore implements LoopStore {
+    private readonly client;
+    readonly baseUrl: string;
+    readonly transport: "cloud-http";
+    constructor(client: HasnaStorageClient, baseUrl: string);
+    private get t();
+    close(): Promise<void>;
+    createLoop(input: CreateLoopInput): Promise<Loop>;
+    getLoop(id: string): Promise<Loop | undefined>;
+    findLoopByName(name: string): Promise<Loop | undefined>;
+    requireLoop(idOrName: string): Promise<Loop>;
+    requireUniqueLoop(idOrName: string): Promise<Loop>;
+    private resolveLoop;
+    listLoops(opts?: Parameters<LoopStore["listLoops"]>[0]): Promise<Loop[]>;
+    countLoops(status?: LoopStatus, opts?: {
+        archived?: boolean;
+        includeArchived?: boolean;
+    }): Promise<number>;
+    updateLoop(id: string, patch: Partial<Pick<Loop, "status" | "nextRunAt" | "retryScheduledFor" | "expiresAt">>): Promise<Loop>;
+    renameLoop(id: string, name: string): Promise<Loop>;
+    archiveLoop(idOrName: string): Promise<Loop>;
+    unarchiveLoop(idOrName: string): Promise<Loop>;
+    deleteLoop(idOrName: string): Promise<boolean>;
+    createWorkflow(input: CreateWorkflowInput): Promise<WorkflowSpec>;
+    getWorkflow(id: string): Promise<WorkflowSpec | undefined>;
+    findWorkflowByName(name: string): Promise<WorkflowSpec | undefined>;
+    requireWorkflow(idOrName: string): Promise<WorkflowSpec>;
+    listWorkflows(opts?: Parameters<LoopStore["listWorkflows"]>[0]): Promise<WorkflowSpec[]>;
+    countWorkflows(opts?: {
+        status?: WorkflowSpec["status"];
+    }): Promise<number>;
+    archiveWorkflow(idOrName: string): Promise<WorkflowSpec>;
+    getWorkflowRun(id: string): Promise<WorkflowRun | undefined>;
+    requireWorkflowRun(id: string): Promise<WorkflowRun>;
+    listWorkflowRuns(opts?: Parameters<LoopStore["listWorkflowRuns"]>[0]): Promise<WorkflowRun[]>;
+    listWorkflowStepRuns(workflowRunId: string): Promise<WorkflowStepRun[]>;
+    listWorkflowEvents(workflowRunId: string, limit?: number): Promise<WorkflowEvent[]>;
+    recoverWorkflowRun(workflowRunId: string, reason?: string): Promise<{
+        run: WorkflowRun;
+        recoveredSteps: WorkflowStepRun[];
+    }>;
+    cancelWorkflowRun(_workflowRunId: string, _reason?: string): Promise<WorkflowRun>;
+    listWorkflowWorkItems(opts?: Parameters<LoopStore["listWorkflowWorkItems"]>[0]): Promise<WorkflowWorkItem[]>;
+    getWorkflowWorkItem(id: string): Promise<WorkflowWorkItem | undefined>;
+    requeueWorkflowWorkItem(_id: string, _patch?: {
+        reason?: string;
+    }): Promise<WorkflowWorkItem>;
+    listWorkflowInvocations(opts?: Parameters<LoopStore["listWorkflowInvocations"]>[0]): Promise<WorkflowInvocation[]>;
+    getWorkflowInvocation(id: string): Promise<WorkflowInvocation | undefined>;
+    getGoal(id: string): Promise<Goal | undefined>;
+    findGoalByLoop(idOrName: string): Promise<Goal | undefined>;
+    findGoalByRunId(id: string): Promise<Goal | undefined>;
+    listGoals(opts?: Parameters<LoopStore["listGoals"]>[0]): Promise<Goal[]>;
+    listGoalPlanNodes(goalIdOrPlanId: string): Promise<GoalPlanNode[]>;
+    listGoalRuns(opts?: Parameters<LoopStore["listGoalRuns"]>[0]): Promise<GoalRun[]>;
+    listRuns(opts?: Parameters<LoopStore["listRuns"]>[0]): Promise<LoopRun[]>;
+    getRun(id: string): Promise<LoopRun | undefined>;
+    writeRunReceipt(input: WriteRunReceiptInput): Promise<RunReceipt>;
+    getRunReceipt(runId: string): Promise<RunReceipt | undefined>;
+    listRunReceipts(opts?: Parameters<LoopStore["listRunReceipts"]>[0]): Promise<RunReceipt[]>;
+    pruneHistory(opts: PruneHistoryOptions): Promise<PruneHistorySummary>;
+}
+/**
+ * Resolve the client store for the current environment: an {@link ApiStore} when
+ * the client-flip contract resolves to cloud-http (self_hosted/cloud), else a
+ * {@link LocalStore}. Callers hold a {@link LoopStore} and never branch on mode.
+ */
+export declare function getStore(env?: Env): LoopStore;
+/** True when the resolved store is the hosted HTTP transport (cloud/self_hosted). */
+export declare function isCloudStore(env?: Env): boolean;

package/dist/lib/store.d.ts

@@ -1,4 +1,4 @@
-import type { CreateLoopInput, CreateWorkflowInvocationInput, CreateWorkflowInput, Goal, GoalAutoExecute, GoalPlanNode, GoalRun, GoalStatus, Loop, LoopRun, LoopStatus, RunStatus, TimeoutMs, WorkflowEvent, WorkflowInvocation, WorkflowRun, WorkflowRunStatus, WorkflowSpec, WorkflowStepRun, WorkflowWorkItem, WorkflowWorkItemStatus, UpsertWorkflowWorkItemInput } from "../types.js";
+import type { CreateLoopInput, CreateWorkflowInvocationInput, CreateWorkflowInput, Goal, GoalAutoExecute, GoalPlanNode, GoalRun, GoalStatus, Loop, LoopRun, LoopStatus, RunReceipt, RunStatus, TimeoutMs, WriteRunReceiptInput, WorkflowEvent, WorkflowInvocation, WorkflowRun, WorkflowRunStatus, WorkflowSpec, WorkflowStepRun, WorkflowWorkItem, WorkflowWorkItemStatus, UpsertWorkflowWorkItemInput } from "../types.js";
 interface DaemonLeaseFence {
     daemonLeaseId?: string;
     now?: Date;
@@ -51,6 +51,23 @@ export interface RunRow {
     created_at: string;
     updated_at: string;
 }
+export interface RunReceiptRow {
+    loop_id: string;
+    run_id: string;
+    machine_json: string;
+    repo: string;
+    task_ids_json: string;
+    knowledge_ids_json: string;
+    digest_id: string;
+    started_at: string | null;
+    finished_at: string | null;
+    status: string;
+    exit_code: number | null;
+    summary_json: string;
+    evidence_paths_json: string;
+    created_at: string;
+    updated_at: string;
+}
 export interface WorkflowRow {
     id: string;
     name: string;
@@ -111,6 +128,7 @@ export interface WorkflowWorkItemRow {
     subject_ref: string;
     project_key: string | null;
     project_group: string | null;
+    machine_id: string | null;
     route_scope: string | null;
     priority: number;
     status: string;
@@ -229,6 +247,7 @@ export interface LeaseRow {
 }
 export declare function rowToLoop(row: LoopRow): Loop;
 export declare function rowToRun(row: RunRow): LoopRun;
+export declare function rowToRunReceipt(row: RunReceiptRow): RunReceipt;
 export declare function rowToWorkflow(row: WorkflowRow): WorkflowSpec;
 export declare function rowToWorkflowRun(row: WorkflowRunRow): WorkflowRun;
 export declare function rowToWorkflowInvocation(row: WorkflowInvocationRow): WorkflowInvocation;
@@ -349,6 +368,7 @@ export interface RecordGoalEventInput {
     rawResponse?: unknown;
 }
 export declare function workItemStatusForLoopRun(status: RunStatus, attempt: number, maxAttempts: number | undefined): WorkflowWorkItemStatus | undefined;
+export declare function scrubbedOrNull(value: string | undefined | null): string | null;
 /** Scrub secrets then bound size before persisting run stdout/stderr. */
 export declare function persistedRunOutput(value: string | undefined | null): string | null;
 export declare class Store {
@@ -360,6 +380,7 @@ export declare class Store {
     private migrate;
     private migrations;
     private createBaseSchema;
+    private createRunReceiptsSchema;
     /**
      * Add a column only if it does not already exist. Idempotent — avoids the
      * "duplicate column name" error that SQLite logs (via libsqlite3, before any
@@ -381,8 +402,10 @@ export declare class Store {
     listLoops(opts?: {
         status?: LoopStatus;
         limit?: number;
+        offset?: number;
         archived?: boolean;
         includeArchived?: boolean;
+        name?: string;
     }): Loop[];
     private withLatestRunSummaries;
     dueLoops(now: Date, limit?: number): Loop[];
@@ -566,7 +589,20 @@ export declare class Store {
         loopId?: string;
         status?: RunStatus;
         limit?: number;
+        offset?: number;
     }): LoopRun[];
+    writeRunReceipt(input: WriteRunReceiptInput, opts?: {
+        now?: Date;
+    }): RunReceipt;
+    getRunReceipt(runId: string): RunReceipt | undefined;
+    listRunReceipts(opts?: {
+        loopId?: string;
+        repo?: string;
+        taskId?: string;
+        knowledgeId?: string;
+        status?: string;
+        limit?: number;
+    }): RunReceipt[];
     private deferLiveExpiredRun;
     recoverExpiredRunLeases(now?: Date, opts?: DaemonLeaseFence & {
         limit?: number;
@@ -589,6 +625,17 @@ export declare class Store {
     }): number;
     countRuns(status?: RunStatus): number;
     exportMigrationRows(opts?: StoreMigrationRowsOptions): StoreMigrationRows;
+    /**
+     * Page through loop_runs for a streaming export. A full `exportMigrationRows`
+     * loads every run's stdout/stderr into memory at once (hundreds of MB on a
+     * busy host); a self-hosted backfill instead pulls stable ordered pages so
+     * peak memory stays bounded. Order is deterministic (created_at, id) so
+     * offset paging over an immutable snapshot never skips or repeats a row.
+     */
+    exportMigrationRunPage(opts: {
+        limit: number;
+        offset: number;
+    }): LoopRun[];
     private countTable;
     private migrationChecks;
     upsertMigrationWorkflow(workflow: WorkflowSpec, opts?: StoreMigrationUpsertOptions): WorkflowSpec;