@hasna/workflows 0.1.4 → 0.2.1

package/hasna.contract.json

@@ -3,8 +3,8 @@
   "name": "workflows",
   "class": "service",
   "contractVersion": "v1",
-  "kitVersion": "0.14.2",
-  "description": "Universal graph workflow app: graph language (start/step/decision/while/end), three-table run store, session WAL, claims/leases daemon, four lane adapters (claude, codex, cursor, grok), and a full CLI on four surfaces (CLI, MCP, serve, SDK). Local state lives at the effective workflows data home (~/.hasna/workflows by default, resolved via @hasna/paths; the XDG data home is adopted once the store is migrated there or HASNA_DATA_HOME is set).",
+  "kitVersion": "1.3.3",
+  "description": "Hosted workflow CLI, MCP and HTTP SDK, with a PostgreSQL execution server and a preserved session journal.",
   "bins": [
     "workflows",
     "workflows-mcp",
@@ -19,7 +19,7 @@
       "kind": "api",
       "status": "supported",
       "bin": "workflows-serve",
-      "authMode": "local-only",
+      "authMode": "api-key",
       "health": {
         "method": "GET",
         "path": "/health",
@@ -35,41 +35,41 @@
         "path": "/version",
         "public": true
       },
-      "openApiPath": "/openapi.json"
+      "openApiPath": "/v1/openapi.json"
     },
     {
       "name": "typescript-sdk",
       "kind": "sdk",
       "status": "supported",
-      "authMode": "local-only",
+      "authMode": "api-key",
       "exportSubpath": "./sdk",
-      "clientClassName": "WorkflowsService",
-      "generatedFrom": "/openapi.json"
+      "clientClassName": "WorkflowsClient",
+      "generatedFrom": "/v1/openapi.json"
     },
     {
       "name": "mcp",
       "kind": "mcp",
       "status": "supported",
       "mcpBin": "workflows-mcp",
-      "authMode": "local-only"
+      "authMode": "api-key"
     },
     {
       "name": "cli",
       "kind": "cli",
       "status": "supported",
       "bin": "workflows",
-      "authMode": "local-only"
+      "authMode": "api-key"
     }
   ],
   "metadata": {
     "serve": {
       "healthEndpoints": [
-        "/health",
-        "/ready",
-        "/version"
+        "/v1/health",
+        "/v1/ready",
+        "/v1/version"
       ],
-      "openapi": "/openapi.json",
-      "auth": "local-only"
+      "openapi": "/v1/openapi.json",
+      "auth": "api-key"
     },
     "release": {
       "artifactScan": {
@@ -78,10 +78,10 @@
     }
   },
   "storage": {
-    "backend": "sqlite",
+    "backend": "postgresql",
     "engines": [
-      "sqlite",
-      "postgresql"
+      "postgresql",
+      "sqlite"
     ],
     "envPrefix": "HASNA_WORKFLOWS_",
     "aliasEnvPrefix": "WORKFLOWS_",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/workflows",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "description": "Universal graph workflow app — graph language (start/step/decision/while/end), three-table store, session WAL, daemon with claims/leases, four lane adapters (claude/codex/cursor/grok), and a full CLI on four surfaces",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,8 +16,8 @@
       "import": "./dist/index.js"
     },
     "./sdk": {
-      "types": "./types/index.d.ts",
-      "import": "./dist/index.js"
+      "types": "./types/sdk.d.ts",
+      "import": "./dist/sdk.js"
     },
     "./cli": {
       "types": "./types/cli/index.d.ts",
@@ -32,14 +32,17 @@
     "hasna.contract.json"
   ],
   "scripts": {
-    "build": "bun run build:runtime && bun run build:types",
-    "build:runtime": "rm -rf dist && bun build src/cli/index.ts --outdir dist/cli --target bun --packages external && bun build src/mcp/index.ts --outdir dist/mcp --target bun --packages external && bun build src/serve/index.ts --outdir dist/serve --target bun --packages external && bun build src/index.ts src/service.ts src/handlers.ts src/agent-tools.ts src/types.ts --root src --outdir dist --target bun --packages external",
-    "build:types": "rm -rf types && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir types",
+    "build": "bun run check:sdk && bun run build:runtime && bun run build:types",
+    "generate:sdk": "bun scripts/generate-sdk.ts --write",
+    "check:sdk": "bun scripts/generate-sdk.ts",
+    "test:artifacts": "bun scripts/artifact-acceptance.ts",
+    "build:runtime": "bun build src/cli/index.ts --outdir dist/cli --target bun && bun build src/mcp/index.ts --outdir dist/mcp --target bun && bun build src/serve/index.ts src/serve/admin.ts --outdir dist/serve --target bun --packages external && bun build src/index.ts src/service.ts src/handlers.ts src/agent-tools.ts src/types.ts --root src --outdir dist --target bun --packages external && bun build src/sdk.ts --outdir dist --target node",
+    "build:types": "tsc -p tsconfig.build.json --emitDeclarationOnly --outDir types",
     "artifact-scan": "bun scripts/contracts-cli.mjs artifact-scan dist",
     "contract:check": "bun scripts/contracts-cli.mjs repo-conformance .",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
-    "test:pg": "WORKFLOWS_TEST_DATABASE_URL=\"${WORKFLOWS_TEST_DATABASE_URL:?point it at a throwaway Postgres; the live-PG gate must not pass without one}\" WORKFLOWS_REQUIRE_POSTGRES=1 bun test src/db/pg-live.test.ts",
+    "test:pg": "WORKFLOWS_TEST_DATABASE_URL=\"${WORKFLOWS_TEST_DATABASE_URL:?point it at a fresh test Postgres database}\" WORKFLOWS_REQUIRE_POSTGRES=1 bun test src/db/postgres-store.test.ts src/db/postgres-http.test.ts src/db/postgres-fencing.test.ts",
     "prepack": "bun run build && bun run artifact-scan",
     "prepublishOnly": "bun run test && bun run build"
   },
@@ -58,7 +61,8 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/hasna/apps.git"
+    "url": "https://github.com/hasna/apps.git",
+    "directory": "apps/workflows"
   },
   "homepage": "https://github.com/hasna/apps/tree/main/apps/workflows",
   "bugs": {
@@ -72,15 +76,14 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.3.234",
     "@cursor/sdk": "^1.0.28",
-    "@hasna/paths": "0.1.0",
-    "@openai/codex-sdk": "0.147.0",
-    "commander": "^13.1.0"
+    "@hasna/contracts": "1.3.3",
+    "@openai/codex-sdk": "0.160.0",
+    "commander": "^13.1.0",
+    "pg": "^8.16.3"
   },
   "devDependencies": {
-    "@hasna/contracts": "0.14.2",
     "@types/bun": "1.3.14",
     "@types/pg": "^8.15.6",
-    "pg": "^8.16.3",
     "typescript": "^5.7.3"
   }
 }

package/types/agent-tools.d.ts

@@ -1,19 +1,5 @@
 import type { WorkflowsService } from "./service.js";
-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 workflowsTools(_service: WorkflowsService): McpTool[];
+export { workflowsTools } from "./tool-definitions.js";
+export type { McpTool, ToolCallResult } from "./tool-definitions.js";
+import type { ToolCallResult } from "./tool-definitions.js";
 export declare function callWorkflowTool(service: WorkflowsService, name: string, args: Record<string, unknown>): Promise<ToolCallResult>;

package/types/client-error.d.ts

@@ -0,0 +1,4 @@
+/** Only authored diagnostics and known scalar codes may reach a CLI or MCP transcript. */
+export declare class WorkflowInputError extends Error {
+}
+export declare function workflowErrorMessage(error: unknown): string;

package/types/client-tools.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowsClient } from "./client.js";
+import { type ToolCallResult } from "./tool-definitions.js";
+/** MCP delegates data operations to the same hosted client as the CLI and SDK. */
+export declare function callClientTool(client: () => WorkflowsClient, name: string, args: Record<string, unknown>): Promise<ToolCallResult>;

package/types/client.d.ts

@@ -0,0 +1,60 @@
+/** Hosted client shared by CLI, MCP and SDK. Never opens an application store. */
+import { type ClientTransportResolution } from "@hasna/contracts/client";
+import type { WorkflowGraph } from "./graph.js";
+import type { RunRow, RunNodeRow, RunStatus } from "./store.js";
+import type { HealthReport, ReadinessReport } from "./types.js";
+import { WorkflowsApi } from "./sdk/generated-api.js";
+export interface WorkflowsClientOptions {
+    apiUrl?: string;
+    apiKey?: string;
+    env?: Record<string, string | undefined>;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    agent?: string;
+}
+export interface RunSummary {
+    runId: string;
+    status: string;
+    error: string | null;
+    result: unknown;
+    reused: boolean;
+}
+export declare class WorkflowsClient extends WorkflowsApi {
+    readonly name = "workflows";
+    readonly resolution: ClientTransportResolution;
+    private readonly http;
+    constructor(options?: WorkflowsClientOptions);
+    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+    protected apiRequest<T>(method: string, path: string, opts: {
+        body?: unknown;
+        query?: Record<string, unknown>;
+    }): Promise<T>;
+    health(): Promise<HealthReport>;
+    ready(): Promise<ReadinessReport>;
+    version(): Promise<{
+        service: string;
+        version: string;
+    }>;
+    validate(graph: unknown): Promise<{
+        ok: boolean;
+        issues: {
+            path: string;
+            message: string;
+        }[];
+    }>;
+    triggerRun(graph: WorkflowGraph, context?: unknown, opts?: {
+        maxCycles?: number;
+        idempotencyKey?: string;
+    }): Promise<RunSummary>;
+    listRuns(options?: {
+        status?: RunStatus;
+        limit?: number;
+    }): Promise<RunRow[]>;
+    getRun(id: string): Promise<RunRow>;
+    listNodes(id: string): Promise<RunNodeRow[]>;
+    events(id: string): Promise<unknown[]>;
+    cancelRun(id: string): Promise<RunRow>;
+    resumeRun(id: string): Promise<RunSummary>;
+    lanes(): Promise<unknown[]>;
+}
+export declare function createWorkflowsClient(options?: WorkflowsClientOptions): WorkflowsClient;

package/types/daemon.d.ts

@@ -1,5 +1,5 @@
 import { type WorkflowGraph } from "./graph.js";
-import type { RunRow, WorkflowsStore } from "./store.js";
+import type { RunRow, WorkflowsStore, EngineStore } from "./store.js";
 import { SessionWAL } from "./wal.js";
 import { type LaneJob, type LaneResult } from "./lanes/types.js";
 export type { LaneJob, LaneKind, LaneResult } from "./lanes/types.js";
@@ -50,8 +50,8 @@ export type StepOutcome = {
     kind: "blocked";
 };
 /** Execute a shell command with a bounded timeout (the built-in step executor). */
-export declare function runCommand(job: LaneJob): LaneResult;
-export declare class WorkflowsDaemon {
+export declare function runCommand(job: LaneJob): Promise<LaneResult>;
+export declare class WorkflowsDaemon<S extends EngineStore = WorkflowsStore> {
     private readonly store;
     private readonly wal;
     readonly worker: string;
@@ -66,7 +66,7 @@ export declare class WorkflowsDaemon {
     private readonly fencingCounter;
     private graphCache;
     private isolatedRunId;
-    constructor(store: WorkflowsStore, wal: SessionWAL, options?: DaemonOptions);
+    constructor(store: S, wal: SessionWAL, options?: DaemonOptions);
     /** Foreground single-run mode: reap() touches only this run from now on. */
     isolateRun(runId: string): void;
     /**
@@ -82,25 +82,29 @@ export declare class WorkflowsDaemon {
     /** Acquire (or refresh) the lease on a run. Returns null while another
      * worker's lease is live. */
     claim(runId: string): Lease | null;
+    private claimLocked;
     /** Extend a lease. Only the fencing-holding worker may. */
     heartbeat(runId: string, fencing: number): boolean;
+    private heartbeatLocked;
     /** Release a lease. Only the fencing-holding worker may. */
     release(runId: string, fencing: number): boolean;
+    private releaseLocked;
     /** One bounded cycle: expire leases -> repair torn runs -> dispatch pending
      * runs -> advance every claimed run one step. */
     reap(): Promise<ReapReport>;
     /** Validate + persist a new run. Returns the pending run row. */
-    startRun(graph: WorkflowGraph, context: unknown): RunRow;
+    startRun(graph: WorkflowGraph, context: unknown): ReturnType<S["createRun"]>;
     /** Execute ONE step of the graph for a claimed run. */
     advanceRun(runId: string): Promise<StepOutcome>;
     private loadGraph;
     /** The condition scope: user context + steps + loop counter (i). */
     private conditionScope;
     private persistContext;
+    private discardStep;
     private executeStep;
-    /** Advance past a finished step node. Inside a while body with no next,
-     * the iteration completes and the while node re-enters. */
-    private afterNode;
+    /** Prepare continuation before commitStep so output, cursor and loop counts
+     * share one transaction. Cancellation retains all of them or rejects all. */
+    private advanceAfterStep;
     private executeWhile;
     private recordStepResult;
     private completeRun;
@@ -117,6 +121,8 @@ export interface RunToCompletionOptions {
     /** Observe the durable run identity immediately after creation (the CLI -j
      * failure surface needs the runId even when the run later throws). */
     onRunCreated?: (run: RunRow) => void;
+    /** Internal continuation of an existing durable run. */
+    existingRunId?: string;
 }
 /** Drive a run to a terminal state with bounded cycles. Returns the final row. */
-export declare function runGraphToCompletion(store: WorkflowsStore, wal: SessionWAL, graph: WorkflowGraph, context: unknown, options?: RunToCompletionOptions): Promise<RunRow>;
+export declare function runGraphToCompletion(store: EngineStore, wal: SessionWAL, graph: WorkflowGraph, context: unknown, options?: RunToCompletionOptions): Promise<RunRow>;

package/types/db/postgres-store.d.ts

@@ -0,0 +1,54 @@
+import type { WorkflowsStore, RunRow, RunNodeRow, MemoRow, CreateRunInput, CreateRunNodeInput, StepCommit, DispatchResult } from "../store.js";
+export type AsyncWorkflowsStore = {
+    [K in keyof WorkflowsStore]: WorkflowsStore[K] extends (...args: infer A) => infer R ? (...args: A) => Promise<R> : WorkflowsStore[K];
+};
+/** Safe diagnostic: driver errors may carry connection details and are never rendered. */
+export declare class WorkflowStorageError extends Error {
+    constructor();
+}
+export declare class PostgresWorkflowsStore implements AsyncWorkflowsStore {
+    private readonly pool;
+    private readonly prefix;
+    readonly dataDir: string;
+    private execution?;
+    constructor(options: {
+        databaseUrl: string;
+        dataDir: string;
+        schema?: string;
+    });
+    private rows;
+    close(): Promise<void>;
+    /** Session advisory lock is shared by every executor, including separate journals.
+     * All owner writes use its exact connection; a lost connection never falls back. */
+    acquireExecution(runId: string): Promise<boolean>;
+    releaseExecution(): Promise<void>;
+    private transaction;
+    listTables(): Promise<string[]>;
+    checkSchema(): Promise<boolean>;
+    /** Creation-only bootstrap. Operators admit this explicitly; reads never migrate. */
+    initialize(): Promise<void>;
+    createRun(input: CreateRunInput): Promise<RunRow>;
+    getRun(id: string): Promise<RunRow | undefined>;
+    getRunByIdempotencyKey(key: string): Promise<RunRow | undefined>;
+    listRuns(options?: Parameters<WorkflowsStore["listRuns"]>[0]): Promise<RunRow[]>;
+    setRunStatus(id: string, status: RunRow["status"], patch?: NonNullable<Parameters<WorkflowsStore["setRunStatus"]>[2]>): Promise<void>;
+    compareRunStatus(id: string, expected: RunRow["status"][], status: RunRow["status"], patch?: Parameters<WorkflowsStore["setRunStatus"]>[2]): Promise<boolean>;
+    setRunContext(id: string, context: unknown): Promise<void>;
+    setRunningContext(id: string, context: unknown): Promise<boolean>;
+    blockRunResume(id: string): Promise<void>;
+    dispatchIfRunning<T>(id: string, action: () => T): Promise<DispatchResult<T>>;
+    finishDispatch(id: string, unconfirmed: boolean): Promise<void>;
+    commitStep(input: StepCommit): Promise<boolean>;
+    bumpAttempts(id: string): Promise<void>;
+    createRunNode(input: CreateRunNodeInput): Promise<RunNodeRow>;
+    getRunNode(id: string): Promise<RunNodeRow | undefined>;
+    listRunNodes(runId: string): Promise<RunNodeRow[]>;
+    getLatestRunNode(runId: string, nodeId: string): Promise<RunNodeRow | undefined>;
+    setRunNodeStatus(id: string, status: RunNodeRow["status"], patch?: NonNullable<Parameters<WorkflowsStore["setRunNodeStatus"]>[2]>): Promise<void>;
+    bumpAttemptsNode(id: string): Promise<void>;
+    memoPut(key: string, graphName: string, nodeId: string, inputHash: string, outputJson: string): Promise<void>;
+    memoGet(key: string): Promise<MemoRow | undefined>;
+    memoHit(key: string): Promise<void>;
+    memoList(): Promise<MemoRow[]>;
+    memoClear(): Promise<void>;
+}

package/types/graph.d.ts

@@ -2,6 +2,8 @@ export declare const GRAPH_NODE_TYPES: readonly ["start", "step", "decision", "w
 export type GraphNodeType = (typeof GRAPH_NODE_TYPES)[number];
 export declare const LANE_KINDS: readonly ["claude", "codex", "cursor", "grok"];
 export type LaneKind = (typeof LANE_KINDS)[number];
+export declare const CODEX_EXECUTION_MODES: readonly ["repository", "read-only"];
+export type CodexExecutionMode = (typeof CODEX_EXECUTION_MODES)[number];
 export interface StartNode {
     id: string;
     type: "start";
@@ -16,6 +18,10 @@ export interface StepNode {
     prompt?: string;
     /** Shell command alternative to a lane prompt. */
     command?: string;
+    /** Working directory on the executor, shared by shell and model lanes. */
+    cwd?: string;
+    /** Codex prompts only. Read-only permits nonrepository work without writes or approvals. */
+    codexMode?: CodexExecutionMode;
     next?: string;
     /** Retries on lane failure. Default 0. */
     maxRetries?: number;

package/types/handlers.d.ts

@@ -1,3 +1,4 @@
-import type { WorkflowsService } from "./service.js";
+import { type WorkflowsService } from "./service.js";
 export declare function jsonResponse(body: unknown, status?: number): Response;
+export declare function openApiDoc(service: WorkflowsService): Record<string, unknown>;
 export declare function createRequestHandler(service: WorkflowsService): (req: Request) => Response | Promise<Response>;

package/types/identity.d.ts

@@ -0,0 +1,7 @@
+export type IdentityEnvironment = Record<string, string | undefined>;
+export interface WorkflowAgent {
+    name: string;
+    source: string;
+}
+export declare function workflowAgent(env?: IdentityEnvironment, explicit?: string): WorkflowAgent;
+export declare function workflowMcpAgent(env: IdentityEnvironment, harness: string, explicit?: unknown, meta?: unknown): WorkflowAgent;

package/types/lanes/codex.d.ts

@@ -1,9 +1,3 @@
-/**
- * codex lane adapter — @openai/codex-sdk.
- *
- * `new Codex({ config, env })` -> `thread.run(prompt)` -> `Turn` whose
- * `finalResponse` is the completed agent output. CLI fallback: `codex exec`.
- */
 import { type LaneAdapter } from "./types.js";
 export interface CodexAdapterDeps {
     sdkLoader?: () => Promise<unknown>;

package/types/lanes/types.d.ts

@@ -1,3 +1,4 @@
+import type { CodexExecutionMode } from "../graph.js";
 export declare const LANE_KINDS: readonly ["claude", "codex", "cursor", "grok"];
 export type LaneKind = (typeof LANE_KINDS)[number];
 export interface LaneJob {
@@ -7,6 +8,8 @@ export interface LaneJob {
     /** Shell command alternative (handled by the daemon's built-in executor). */
     command?: string;
     cwd?: string;
+    /** Repository checks remain native defaults unless read-only is explicitly selected. */
+    codexMode?: CodexExecutionMode;
     /** Environment for the lane process — never credentials from the vault. */
     env?: Record<string, string>;
     /** Per-invocation budget in ms. Default 120000. */
@@ -19,6 +22,8 @@ export interface LaneResult {
     output: string;
     durationMs: number;
     error?: string;
+    /** False when retry could overlap a timed-out execution or a policy refusal. */
+    retryable?: boolean;
 }
 /**
  * A lane maturity probe: is the substrate actually wired on THIS machine
@@ -52,8 +57,15 @@ export declare class LaneAdapterShapeError extends Error {
 export declare const DEFAULT_LANE_TIMEOUT_MS = 120000;
 /** Is a binary present on PATH (read-only existence check; never runs it)? */
 export declare function binaryOnPath(binary: string): boolean;
-/** Run a promise with a bounded wall-clock budget. */
-export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, what: string): Promise<T>;
+/** Preserve native subscription configuration while excluding API billing and server secrets. */
+export declare function subscriptionEnvironment(overrides?: Record<string, string>): Record<string, string>;
+/** SDKs that merge process.env need explicit undefined entries for excluded fields. */
+export declare function subscriptionSdkEnvironment(overrides?: Record<string, string>): Record<string, string | undefined>;
+export declare class LaneTimeoutError extends Error {
+    constructor(what: string, timeoutMs: number);
+}
+/** A timeout requests cancellation. Callers mark it non-retryable. */
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, what: string, cancel?: () => void): Promise<T>;
 /** Spawn a CLI binary with a bounded timeout; maps ENOENT to a missing-substrate error. */
 export declare function spawnCli(cmd: string[], opts: {
     cwd?: string;
@@ -61,4 +73,5 @@ export declare function spawnCli(cmd: string[], opts: {
     timeoutMs?: number;
     binaryName: string;
     packageHint: string;
-}): LaneResult;
+    stdoutOnly?: boolean;
+}): Promise<LaneResult>;

package/types/openapi.d.ts

@@ -0,0 +1,7 @@
+import type { OpenApiDocument } from "@hasna/contracts";
+/** One API description drives served discovery and generated SDK operations. */
+export declare function buildOpenApi(version: string): OpenApiDocument & {
+    servers: {
+        url: string;
+    }[];
+};

package/types/paths.d.ts

@@ -15,6 +15,15 @@
  * data-kind override `HASNA_DATA_HOME`. An existing local store never becomes
  * invisible on upgrade.
  */
+export type PathKind = "config" | "data" | "state" | "cache";
+export interface PathsResolverOptions {
+    app: string;
+    internal?: boolean;
+    platform?: string;
+    home?: string;
+    env?: Record<string, string | undefined>;
+}
+export declare function dataDir(options: PathsResolverOptions): string;
 /** The workflows app slug used by the @hasna/paths resolver. */
 export declare const APP: "workflows";
 /** The store database file name, the marker that a store lives at a data home. */
@@ -33,7 +42,7 @@ export declare function getLegacyDataDir(env?: NodeJS.ProcessEnv): string;
  * pre-existing `$HOME`-first resolution so the resolver follows the same home
  * the legacy path does.
  */
-export declare function getResolverDataDir(env?: NodeJS.ProcessEnv): string;
+export declare function getResolverDataDir(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string;
 /**
  * Whether the resolver (XDG) data home should be adopted as the effective
  * workflows data home. The resolver home is adopted only when the operator