@hasna/workflows 0.1.3 → 0.2.0

package/types/service.d.ts

@@ -1,16 +1,82 @@
+import { type RunToCompletionOptions } from "./daemon.js";
+import { openStore } from "./store.js";
 import type { WorkflowGraph } from "./graph.js";
 import type { HealthReport, ReadinessReport, WorkflowsConfig } from "./types.js";
-export declare function packageVersion(): string;
+export { packageVersion } from "./version.js";
 /** Resolve the service configuration from env + explicit overrides. */
 export declare function resolveWorkflowsConfig(overrides?: Partial<WorkflowsConfig>): WorkflowsConfig;
 export declare class WorkflowsService {
+    private readonly execution;
     readonly name = "workflows";
     readonly version: string;
     readonly config: WorkflowsConfig;
     private readonly startedAt;
-    constructor(config?: Partial<WorkflowsConfig>);
+    private readonly databaseEnv;
+    constructor(config?: Partial<WorkflowsConfig>, execution?: RunToCompletionOptions);
     health(): HealthReport;
-    ready(): ReadinessReport;
+    ready(): Promise<ReadinessReport>;
+    private openEngineStore;
+    private withStore;
+    /** Explicit operator bootstrap; ordinary reads and server startup never create tables. */
+    initializeStorage(): Promise<void>;
+    listRuns(options?: Parameters<ReturnType<typeof openStore>["listRuns"]>[0]): Promise<import("./store.js").RunRow[]>;
+    getRun(id: string): Promise<import("./store.js").RunRow | undefined>;
+    listNodes(id: string): Promise<import("./store.js").RunNodeRow[]>;
+    events(id: string): import("./wal.js").WalEntry[];
+    cancelRun(id: string): Promise<import("./store.js").RunRow | undefined>;
+    resumeRun(id: string): Promise<{
+        runId: string;
+        status: "cancelled" | "pending" | "running" | "completed" | "failed" | "interrupted";
+        error: string | null;
+        result: any;
+        reused: boolean;
+    }>;
+    sessions(action: "list" | "pull"): {
+        seq: number;
+        at: string;
+        operation: "claim_acquired" | "claim_released" | "graph_registered" | "run_started" | "run_finished" | "node_started" | "node_finished" | "memo_set";
+    }[] | {
+        entries: number;
+        torn: boolean;
+        repaired: boolean;
+        liveClaims: {
+            runId: string;
+            worker: string;
+            fencing: number;
+            expiresAt: string;
+        }[];
+    };
+    machines(action: "list" | "status"): {
+        name: string;
+        role: string;
+        version: string;
+    }[] | {
+        health: HealthReport;
+        sessions: {
+            seq: number;
+            at: string;
+            operation: "claim_acquired" | "claim_released" | "graph_registered" | "run_started" | "run_finished" | "node_started" | "node_finished" | "memo_set";
+        }[] | {
+            entries: number;
+            torn: boolean;
+            repaired: boolean;
+            liveClaims: {
+                runId: string;
+                worker: string;
+                fencing: number;
+                expiresAt: string;
+            }[];
+        };
+        name: string;
+        role: string;
+        version: string;
+    };
+    daemonStatus(): {
+        activeClaims: number;
+        mode: string;
+        continuousDaemon: boolean;
+    };
+    listMemos(): Promise<import("./store.js").MemoRow[]>;
     /**
      * The authenticated trigger: run a graph to a terminal state (bounded
      * cycles) and return its summary. The HTTP layer authenticates; this
@@ -29,4 +95,9 @@ export declare class WorkflowsService {
         reused: boolean;
     }>;
 }
-export declare function createWorkflowsService(config?: Partial<WorkflowsConfig>): WorkflowsService;
+export declare function createWorkflowsService(config?: Partial<WorkflowsConfig>, execution?: RunToCompletionOptions): WorkflowsService;
+export declare class WorkflowRequestError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, message: string, status?: number);
+}

package/types/session.d.ts

@@ -1,5 +1,6 @@
 import { SessionWAL } from "./wal.js";
-import type { RunRow, WorkflowsStore } from "./store.js";
+import type { RunRow, WorkflowsStore, EngineStore } from "./store.js";
+import type { WorkflowGraph } from "./graph.js";
 export interface RepairResult {
     /** runs found running with no live claim */
     interrupted: number;
@@ -9,18 +10,41 @@ export interface RepairResult {
     failed: number;
 }
 export declare const DEFAULT_MAX_ATTEMPTS = 3;
-export declare function repairTornRuns(store: WorkflowsStore, wal: SessionWAL, opts?: {
+export declare function repairTornRuns<S extends EngineStore>(store: S, wal: SessionWAL, opts?: {
     maxAttempts?: number;
     now?: number;
-}): RepairResult;
+}): S extends WorkflowsStore ? RepairResult : Promise<RepairResult>;
 /** Stable hash of a JSON-serializable payload. */
 export declare function inputHash(payload: unknown): string;
 /** Memo key: graphName:nodeId:<inputHash>. */
 export declare function memoKey(graphName: string, nodeId: string, input: unknown): string;
 /** Look up a memo by input; a hit increments hitCount and returns the row. */
-export declare function tryMemoHit(store: WorkflowsStore, graphName: string, nodeId: string, input: unknown): import("./store.js").MemoRow | undefined;
+export declare function tryMemoHit<S extends EngineStore>(store: S, graphName: string, nodeId: string, input: unknown): ReturnType<S["memoGet"]>;
 /** Persist a node output for future runs with the same input. */
-export declare function recordMemo(store: WorkflowsStore, graphName: string, nodeId: string, input: unknown, output: unknown): void;
+export declare function recordMemo<S extends EngineStore>(store: S, graphName: string, nodeId: string, input: unknown, output: unknown): ReturnType<S["memoPut"]>;
+/** One watched file's fingerprint entry (mtime + sha256). */
+export interface MemoWatchEntry {
+    /** The pattern as declared on the graph. */
+    pattern: string;
+    /** The resolved absolute path (or the glob-relative file path). */
+    path: string;
+    missing: boolean;
+    mtimeMs: number | null;
+    size: number | null;
+    sha256: string | null;
+}
+/**
+ * Fingerprint of the graph's memoWatch files: mtimes + content hashes.
+ * Stress V3/V4 F2 (measured 2026-08-30): a memoized node reading
+ * $WORKFLOWS_DATA_DIR/scratch/wf2.cnt served a stale cached "0" while the
+ * file said "2" — the memo key covered only {command, prompt, context}. The
+ * fingerprint joins the memo input, so a changed watched file invalidates the
+ * cache exactly when the command's live result can differ. Exact paths and
+ * glob patterns are supported (relative to `dataDir` or absolute); a missing
+ * exact path keeps a stable `missing` entry so its later appearance (or a
+ * re-creation with different content) still changes the fingerprint.
+ */
+export declare function memoWatchFingerprint(graph: WorkflowGraph, dataDir: string): MemoWatchEntry[] | undefined;
 /** Requeue a cancelled run's in-flight nodes (used by cancel + resume). */
 export declare function resetRunNodes(store: WorkflowsStore, run: RunRow): void;
 export interface RestoreResult {
@@ -45,7 +69,6 @@ export declare function restoreInterruptedRun(store: WorkflowsStore, runId: stri
 /**
  * Idempotent run lookup: the run whose context carries the given idempotency
  * key, if any. The three-table law forbids an extra column, so the key lives
- * in the reserved __wf namespace of context_json; the scan is bounded by the
- * store's own listRuns cap (1000 rows).
+ * in the reserved __wf namespace of context_json; a database lookup covers the entire run history.
  */
-export declare function findRunByIdempotencyKey(store: WorkflowsStore, key: string): RunRow | undefined;
+export declare function findRunByIdempotencyKey<S extends EngineStore>(store: S, key: string): ReturnType<S["getRunByIdempotencyKey"]>;

package/types/setup.d.ts

@@ -0,0 +1,71 @@
+import { type IdentityEnvironment } from "./identity.js";
+type SetupOptions = {
+    apiUrl?: string;
+    replace?: boolean;
+    agent?: string;
+    env?: IdentityEnvironment;
+    fetchImpl?: typeof fetch;
+};
+export declare function setupWorkflows(options?: SetupOptions): Promise<{
+    app: string;
+    action: string;
+    credentials_path: string;
+    mode: string;
+    authority: string;
+    verified_before_write: boolean;
+    verified_after_write: boolean;
+    effective_tier: "disk";
+    effective_source: string;
+    preservation: string | undefined;
+    warning: null;
+}>;
+export declare function loginWorkflows(options?: SetupOptions, suppliedKey?: string): Promise<{
+    app: string;
+    action: string;
+    credentials_path: string;
+    mode: string;
+    authority: string;
+    verified_before_write: boolean;
+    verified_after_write: boolean;
+    effective_tier: "disk";
+    effective_source: string;
+    preservation: string | undefined;
+    warning: null;
+}>;
+/** Sign out only a key written by login; environment and setup credentials stay owned by their source. */
+export declare function logoutWorkflows(options?: {
+    revoke?: boolean;
+    env?: IdentityEnvironment;
+}): {
+    app: string;
+    action: string;
+    exit_code: number;
+    message: string;
+} | {
+    app: string;
+    action: string;
+    credentials_path: string;
+    preservation: string;
+    exit_code: number;
+    message: string;
+};
+export declare function workflowsWhoami(options?: {
+    apiUrl?: string;
+    agent?: string;
+    env?: IdentityEnvironment;
+}): {
+    app: string;
+    agent: string;
+    agent_source: string;
+    authority: string;
+    credential_tier: import("@hasna/contracts").CredentialTier;
+    credential_source: string | null;
+} | {
+    app: string;
+    agent: string;
+    agent_source: string;
+    authority: string;
+    credential_tier: string;
+    credential_source: null;
+};
+export {};

package/types/store.d.ts

@@ -48,11 +48,35 @@ export interface CreateRunNodeInput {
     nodeId: string;
     lane?: string;
 }
+export interface StepCommit {
+    runId: string;
+    nodeRowId: string;
+    status: NodeStatus;
+    patch?: Parameters<WorkflowsStore["setRunNodeStatus"]>[2];
+    incrementAttempts?: boolean;
+    context?: unknown;
+    memo?: {
+        key: string;
+        graphName: string;
+        nodeId: string;
+        inputHash: string;
+        outputJson: string;
+    };
+}
+export type DispatchResult<T> = {
+    started: false;
+} | {
+    started: true;
+    result: T;
+};
 export interface WorkflowsStore {
+    /** The data dir this store was opened on (resolves relative memoWatch paths). */
+    readonly dataDir: string;
     close(): void;
     listTables(): string[];
     createRun(input: CreateRunInput): RunRow;
     getRun(id: string): RunRow | undefined;
+    getRunByIdempotencyKey(key: string): RunRow | undefined;
     listRuns(opts?: {
         status?: RunStatus;
         limit?: number;
@@ -63,12 +87,21 @@ export interface WorkflowsStore {
         startedAt?: string;
         finishedAt?: string;
     }): void;
+    compareRunStatus(id: string, expected: RunStatus[], status: RunStatus, patch?: Parameters<WorkflowsStore["setRunStatus"]>[2]): boolean;
     /** Persist the run's durable execution state (the engine's cursor + steps). */
     setRunContext(id: string, context: unknown): void;
+    setRunningContext(id: string, context: unknown): boolean;
+    blockRunResume(id: string): void;
+    finishDispatch(id: string, unconfirmed: boolean): void;
+    dispatchIfRunning<T>(id: string, action: () => T): DispatchResult<T>;
+    commitStep(input: StepCommit): boolean;
     bumpAttempts(id: string): void;
     createRunNode(input: CreateRunNodeInput): RunNodeRow;
     getRunNode(id: string): RunNodeRow | undefined;
     listRunNodes(runId: string): RunNodeRow[];
+    /** The newest run_nodes row for a (run, node) pair — a node may own one row
+     * per while iteration, and `nodes show` + engine row-reuse need the latest. */
+    getLatestRunNode(runId: string, nodeId: string): RunNodeRow | undefined;
     setRunNodeStatus(id: string, status: NodeStatus, patch?: {
         exitCode?: number | null;
         output?: unknown;
@@ -84,3 +117,5 @@ export interface WorkflowsStore {
     memoClear(): void;
 }
 export declare function openStore(dataDir: string): WorkflowsStore;
+/** One execution engine accepts the synchronous embedded and asynchronous hosted stores. */
+export type EngineStore = WorkflowsStore | import("./db/postgres-store.js").AsyncWorkflowsStore;

package/types/tool-definitions.d.ts

@@ -0,0 +1,18 @@
+export interface McpTool {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+export interface ToolCallResult {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+}
+export declare function textResult(payload: unknown): ToolCallResult;
+export declare function workflowsTools(_service?: unknown): McpTool[];

package/types/types.d.ts

@@ -20,9 +20,17 @@ export interface WorkflowsConfig {
     apiUrl?: string;
     /** Optional client API key (WORKFLOWS_API_KEY) — resolved, never printed. */
     apiKey?: string;
+    /** Gateway origin identity. When configured, every /v1 route requires it. */
+    originAuth?: string;
+    /** Hosted server authority. SQLite requires an explicit embedded selection. */
+    storageBackend: "postgresql" | "sqlite";
+    databaseUrl?: string;
+    databaseSchema?: string;
 }
 export interface HealthReport {
     ok: boolean;
+    status: "ok";
+    backend: "postgresql" | "sqlite";
     service: string;
     version: string;
     pid: number;

package/types/version.d.ts

@@ -0,0 +1 @@
+export declare function packageVersion(): string;

package/types/wal.d.ts

@@ -71,14 +71,22 @@ export declare const WAL_FILE_NAME = "session.wal";
 export declare const SESSIONS_DIR_NAME = "sessions";
 export declare class SessionWAL {
     readonly filePath: string;
+    private journalLocked;
     private constructor();
     static open(dataDir: string): SessionWAL;
     static openAt(filePath: string): SessionWAL;
     /** Append one op and return the persisted entry (seq is 1-based). */
     append(op: WalOp): WalEntry;
+    private withJournalLock;
+    /** Atomic journal claim/release decisions use the same cross-process mutex. */
+    exclusive<T>(operation: () => T): T;
+    private appendLocked;
     private nextSeq;
     /** Read and verify the whole WAL; truncate the first torn tail. */
-    replay(): WalReplay;
+    replay(options?: {
+        repair?: boolean;
+    }): WalReplay;
+    private replayLocked;
     close(): void;
 }
 /** Write a fresh (empty) WAL — used by tests and by init. */