@hasna/workflows 0.1.4 → 0.2.1

package/types/sdk/generated-api.d.ts

@@ -0,0 +1,161 @@
+export interface ApiError {
+    "error": string;
+    "message"?: string;
+}
+export interface HealthReport {
+    "ok": boolean;
+    "status": "ok";
+    "backend": "postgresql" | "sqlite";
+    "service": string;
+    "version": string;
+    "pid": number;
+    "uptimeMs": number;
+}
+export interface ReadinessReport {
+    "ok": boolean;
+    "service": string;
+    "version": string;
+    "checks": Record<string, string>;
+}
+export interface GraphValidation {
+    "ok": boolean;
+    "issues": Array<{
+        "path": string;
+        "message": string;
+    }>;
+}
+export interface StartNode {
+    "id": string;
+    "type": "start";
+    "next"?: string;
+}
+export interface StepNode {
+    "id": string;
+    "type": "step";
+    "next"?: string;
+    "lane"?: "claude" | "codex" | "cursor" | "grok";
+    "prompt"?: string;
+    "command"?: string;
+    "cwd"?: string;
+    "codexMode"?: "repository" | "read-only";
+    "maxRetries"?: number;
+    "memo"?: boolean;
+    "timeoutMs"?: number;
+}
+export interface DecisionNode {
+    "id": string;
+    "type": "decision";
+    "condition": string;
+    "then"?: string;
+    "else"?: string;
+}
+export interface WhileNode {
+    "id": string;
+    "type": "while";
+    "condition": string;
+    "body": Array<string>;
+    "maxIterations": number;
+    "next"?: string;
+}
+export interface EndNode {
+    "id": string;
+    "type": "end";
+}
+export type GraphNode = StartNode | StepNode | DecisionNode | WhileNode | EndNode;
+export interface WorkflowGraph {
+    "name": string;
+    "version": string;
+    "nodes": Array<GraphNode>;
+    "memoWatch"?: Array<string>;
+}
+export interface RunSummary {
+    "runId": string;
+    "status": "pending" | "running" | "completed" | "failed" | "interrupted" | "cancelled";
+    "error": string | null;
+    "result": unknown;
+    "reused": boolean;
+}
+export interface RunRow {
+    "id": string;
+    "graphName": string;
+    "graphVersion": string;
+    "status": "pending" | "running" | "completed" | "failed" | "interrupted" | "cancelled";
+    "attempts": number;
+    "contextJson": string;
+    "resultJson": string | null;
+    "error": string | null;
+    "startedAt": string | null;
+    "finishedAt": string | null;
+    "createdAt": string;
+    "updatedAt": string;
+}
+export interface RunNodeRow {
+    "id": string;
+    "runId": string;
+    "nodeId": string;
+    "status": "pending" | "running" | "completed" | "failed" | "skipped";
+    "attempts": number;
+    "lane": string | null;
+    "exitCode": number | null;
+    "outputJson": string | null;
+    "error": string | null;
+    "startedAt": string | null;
+    "finishedAt": string | null;
+}
+export declare abstract class WorkflowsApi {
+    protected abstract apiRequest<T>(method: string, path: string, opts: {
+        body?: unknown;
+        query?: Record<string, unknown>;
+    }): Promise<T>;
+    /** Bounded-trigger executor status */
+    inspectDaemon(): Promise<Record<string, unknown>>;
+    /** Service health */
+    getHealth(): Promise<HealthReport>;
+    /** Inspect lane substrates; this does not prove sign-in or model capacity */
+    listLanes(): Promise<Array<Record<string, unknown>>>;
+    /** Inspect one lane substrate */
+    probeLane(lane: "claude" | "codex" | "cursor" | "grok"): Promise<Record<string, unknown>>;
+    /** This executor, not a fleet census */
+    listServerMachines(): Promise<Array<Record<string, unknown>>>;
+    /** This executor's health and claims */
+    inspectServerMachine(): Promise<Record<string, unknown>>;
+    /** Recent memo results */
+    listMemoRecords(): Promise<Array<Record<string, unknown>>>;
+    /** Authentication and actual schema readiness */
+    getReadiness(): Promise<ReadinessReport>;
+    /** List recent runs */
+    listRunRecords(query?: {
+        "status"?: "pending" | "running" | "completed" | "failed" | "interrupted" | "cancelled";
+        "limit"?: number;
+    }): Promise<Array<RunRow>>;
+    /** Read a durable run */
+    getRunRecord(id: string): Promise<RunRow>;
+    /** Cancel a pending, running or interrupted run and fence late results */
+    cancelWorkflow(id: string): Promise<RunRow>;
+    /** Preserved execution journal events */
+    getRunEvents(id: string): Promise<Array<Record<string, unknown>>>;
+    /** Ordered node execution history */
+    getRunNodes(id: string): Promise<Array<RunNodeRow>>;
+    /** Continue a failed, cancelled or interrupted run using its pinned graph; active or unconfirmed execution refuses resume */
+    resumeWorkflow(id: string): Promise<RunSummary>;
+    /** Recent journal event metadata */
+    listSessionEvents(): Promise<Array<Record<string, unknown>>>;
+    /** Read journal and claim state without repair */
+    inspectSession(): Promise<Record<string, unknown>>;
+    /** Execute a bounded workflow; identical keyed retries reuse the original run */
+    triggerWorkflow(body: {
+        "graph": WorkflowGraph;
+        "context"?: Record<string, unknown>;
+        "idempotencyKey"?: string;
+        "maxCycles"?: number;
+    }): Promise<RunSummary>;
+    /** Validate a workflow graph */
+    validateWorkflow(body: {
+        "graph": WorkflowGraph;
+    }): Promise<GraphValidation>;
+    /** Package version */
+    getVersion(): Promise<{
+        "service": string;
+        "version": string;
+    }>;
+}

package/types/sdk.d.ts

@@ -0,0 +1,6 @@
+/** The SDK is a hosted HTTP client; server implementation is exported at the package root. */
+export { WorkflowsClient, createWorkflowsClient } from "./client.js";
+export type { WorkflowsClientOptions, RunSummary } from "./client.js";
+export type { WorkflowGraph, GraphNode, GraphValidation } from "./graph.js";
+export type { RunRow, RunNodeRow, RunStatus } from "./store.js";
+export type { HealthReport, ReadinessReport } from "./types.js";

package/types/serve/admin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

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,5 @@
 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 */
@@ -10,18 +10,18 @@ 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. */
@@ -69,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,6 +48,27 @@ 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;
@@ -55,6 +76,7 @@ export interface WorkflowsStore {
     listTables(): string[];
     createRun(input: CreateRunInput): RunRow;
     getRun(id: string): RunRow | undefined;
+    getRunByIdempotencyKey(key: string): RunRow | undefined;
     listRuns(opts?: {
         status?: RunStatus;
         limit?: number;
@@ -65,8 +87,14 @@ 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;
@@ -89,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. */