@hasna/workflows 0.1.3 → 0.2.0

package/hasna.contract.json

@@ -3,8 +3,8 @@
   "name": "workflows",
   "class": "service",
   "contractVersion": "v1",
-  "kitVersion": "0.14.1",
-  "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.3",
+  "version": "0.2.0",
   "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"
+    "commander": "^13.1.0",
+    "@hasna/contracts": "1.3.3",
+    "pg": "^8.16.3"
   },
   "devDependencies": {
-    "@hasna/contracts": "0.14.1",
-    "@types/bun": "latest",
+    "@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;
@@ -114,6 +118,11 @@ export interface RunToCompletionOptions {
     /** Pre-set the daemon's isolation; the foreground driver always isolates
      * to its own run anyway (see isolateRun in runGraphToCompletion). */
     isolatedRunId?: string;
+    /** 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

@@ -53,6 +53,13 @@ export interface WorkflowGraph {
     name: string;
     version: string;
     nodes: GraphNode[];
+    /**
+     * Optional files/globs (relative to the data dir, or absolute) whose
+     * fingerprint (mtime + sha256) joins every memoized node's input.
+     * A memoized command that reads external state MUST declare it here, or
+     * it can serve a stale cached value that contradicts a live run.
+     */
+    memoWatch?: string[];
 }
 export interface GraphIssue {
     /** Dotted path to the offending member, e.g. "nodes.build" or "nodes.w.body". */

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/types.d.ts

@@ -19,6 +19,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 +54,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 +70,4 @@ export declare function spawnCli(cmd: string[], opts: {
     timeoutMs?: number;
     binaryName: string;
     packageHint: string;
-}): LaneResult;
+}): 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

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

@@ -0,0 +1,159 @@
+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;
+    "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 {};