@hasna/workflows 0.1.4 → 0.2.1

package/README.md

@@ -1,112 +1,194 @@
 # @hasna/workflows
 
-Universal graph workflow app: a graph language (with `while` nodes), a
-three-table store, session WAL with torn-run repair, memoization, a secrets
-write-gate, a claims/leases daemon, and four lane adapters (claude, codex,
-cursor, grok) — one domain implementation, four interface surfaces.
-
-## Surfaces
-
-| surface | bin / export | what it is |
-|---|---|---|
-| CLI | `workflows` | init, validate, graph (render), run (--context/--input/--idempotency-key), runs list/show/cancel/resume/events, nodes list/show, sessions list/pull, machines list/status, lanes list/probe, daemon start/status/stop, memos list/clear, resume (interrupted-run restore), serve, repair (+ version, health, info) |
-| MCP | `workflows-mcp` | stdio MCP server for coding agents (7 tools incl. workflows_validate, workflows_run, workflows_runs_list, workflows_lanes_list) |
-| Serve | `workflows-serve` (or `workflows serve`) | HTTP server (`/health`, `/ready`, `/version`, authenticated `/trigger`, `/openapi.json`); binds `127.0.0.1` by default; `/trigger` requires `WORKFLOWS_API_KEY` + Bearer token |
-| SDK | `./sdk` (`@hasna/workflows/sdk`) | importable module surface (exports `WorkflowsService`, `createWorkflowsService`, `createRequestHandler`, `workflowsTools`, `callWorkflowTool`) |
-
-All three bins answer `--version` / `--help` before binding or serving.
-
-## The graph language (v1)
-
-A workflow is a JSON graph with five node types — `start`, `step`, `decision`,
-`while`, `end` — one `start`, at least one `end`, explicit edges only
-(`next`/`then`/`else`), and no explicit cycles: repetition lives in the `while`
-node's condition, which is REQUIRED to carry a finite `maxIterations` bound.
-`validate` reports every rule violation with a dotted path. Conditions are a
-bounded expression language (comparisons, `and`/`or`/`not`, parens, dotted
-paths like `steps.build.exitCode`, and the loop counter `i`).
-
-```json
-{
-  "name": "retry-until-green",
-  "version": "1.0.0",
-  "nodes": [
-    { "id": "start", "type": "start", "next": "w" },
-    { "id": "w", "type": "while", "condition": "steps.check.ok != true",
-      "body": ["work", "check"], "maxIterations": 5, "next": "done" },
-    { "id": "work", "type": "step", "lane": "claude", "prompt": "fix it" },
-    { "id": "check", "type": "step", "command": "bun test" },
-    { "id": "done", "type": "end" }
-  ]
-}
+Workflows executes bounded graphs and records their runs, nodes and results. The CLI,
+stdio MCP server and `@hasna/workflows/sdk` use the hosted HTTP API. Their default
+authority is `https://api.hasna.com/workflows/v1`. A missing credential or an
+unreachable service fails visibly; clients never create a local application database.
+
+## Set up with your agent
+
+Copy this prompt to your agent:
+
+> Install the published `@hasna/workflows` package. Connect its `workflows-mcp`
+> stdio server using this harness's supported MCP configuration. Target
+> `https://api.hasna.com/workflows/v1` and use this station's own supported
+> credential resolver. Run `workflows setup` with your credential owner's environment
+> projection, then verify `workflows whoami`, `workflows ready --json` and
+> `workflows runs list --json`, then call `workflows_ready` through the harness.
+> Finish only when those real consumers work. Never copy a credential from another
+> station or fall back to a local database.
+
+Raw setup is also available:
+
+```sh
+npm install --prefix <retained-version-runtime> @hasna/workflows
+workflows --help
+workflows setup
+workflows whoami
+workflows ready --json
+workflows runs list --json
 ```
 
-## Execution model
-
-- **Store**: exactly three SQLite tables — `runs`, `run_nodes`, `memos`
-  (input-hash memoization across runs).
-- **Session WAL**: append-only JSONL journal with per-entry sha256 checksums;
-  torn tails are truncated and reported on replay.
-- **Torn-run repair**: a run left `running` with no live claim is marked
-  `interrupted` (attempts + 1, up to a bound) or failed; `repair` exposes it.
-  An interrupted run continues from its durable cursor either via the daemon
-  (which dispatches interrupted runs) or via top-level `resume <run-id>`,
-  which restores it and reuses memoized node outputs.
-- **Daemon**: fencing-tokened, expiring, WAL-recorded claims; heartbeat and
-  release are fencing-checked; the reaper expires stale leases, repairs torn
-  runs, dispatches pending + interrupted runs, and advances each run ONE step
-  per bounded cycle (maxDispatchPerCycle / maxStepsPerCycle / maxCycles /
-  maxIterations — every invocation carries a finite budget).
-- **Secrets write-gate**: no node output, run result, or context containing a
-  credential-shaped value is ever persisted; the write is refused with the
-  path and detector named.
-- **Lanes**: exactly four adapters — claude (@anthropic-ai/claude-agent-sdk),
-  codex (@openai/codex-sdk), cursor (@cursor/sdk, local mode), grok (no xAI
-  Grok SDK exists on npm — measured; local grok CLI). Each falls back to its
-  local CLI and reports LANE_DEPENDENCY_MISSING (exit 127) when neither
-  substrate exists.
-
-## Usage
-
-```bash
-workflows --version
-workflows init                 # creates workflows/ + sessions/ + workflows.db and scaffolds a sample graph
-workflows validate graph.json
-workflows graph graph.json     # render (text | --format dot | --format json)
-workflows run graph.json --context '{"repo":"x"}' --input go=yes --idempotency-key k1
-workflows runs list
-workflows runs show <run-id>
-workflows runs events <run-id> # the run's WAL event stream
-workflows nodes show <run-id> <node-id>
-workflows sessions pull        # session WAL state (entries, torn, live claims)
-workflows machines status      # this machine's store/WAL/daemon status
-workflows lanes probe claude   # wired-vs-not-ready-with-reason maturity check
-workflows resume <run-id>      # restore an INTERRUPTED run from its durable cursor
-workflows daemon start --once  # or a continuous reap loop
-workflows memos clear --yes
-workflows serve                # HTTP server (same as workflows-serve)
-workflows-mcp                  # stdio MCP server
-workflows-serve                # HTTP server, port from HASNA_WORKFLOWS_PORT (default 8790)
+The shared `@hasna/contracts` resolver owns credentials. It supports the canonical
+`HASNA_WORKFLOWS_API_KEY` / `HASNA_WORKFLOWS_API_URL` environment names and the
+`WORKFLOWS_` aliases, its owner-only disk tier at
+`~/.hasna/workflows/config/credentials`, documented Hasna home/profile overrides,
+and its supported macOS Keychain tier. Keep API keys out of commands, logs and MCP
+configuration. A credential bound to one authority is refused at another authority.
+Legacy unbound internal credentials stay bound to the Hasna gateway.
+
+`workflows setup` reads a key projected into `HASNA_WORKFLOWS_API_KEY`, verifies
+one authenticated API read, writes owner-only credentials atomically, and verifies
+another read through the disk tier. It refuses a selected override, pointer or
+profile. Replacing different credentials requires `--replace`; the exact original
+is preserved and read back before replacement. `workflows whoami` works offline and
+reports the authority, credential source and calling agent without printing a key.
+
+For personal sign-in, `workflows login` verifies and stores a key projected by
+your credential owner into `HASNA_WORKFLOWS_API_KEY`. A supplied key can also be
+piped into `workflows login --with-api-key`; never put a key in arguments.
+This API-key-only server does not offer a browser or device sign-in flow.
+`workflows logout` removes only the active credential that login stored,
+preserves its readable original and keeps the API URL. It leaves setup-owned,
+environment, pointer and other-profile credentials with their owners. Environment
+credentials still set produce a non-zero result and name their source.
+A supplied key remains valid on the server until its credential owner revokes it;
+`--revoke` signs out locally and reports that individual-key revocation is unavailable.
+
+An explicit URL can include or omit `/v1`; the client adds it exactly once:
+
+```sh
+workflows --api-url https://api.hasna.com/workflows/v1 runs list --json
 ```
 
+For self-hosting, supply your own HTTPS URL and its paired credential using the
+resolver. Loopback HTTP is permitted for isolated development. Remote HTTP and
+redirects carrying credentials are refused.
+
+## HTTP SDK
+
+The SDK works in Node and Bun:
+
 ```ts
-import { createWorkflowsService } from "@hasna/workflows/sdk";
+import { createWorkflowsClient } from "@hasna/workflows/sdk";
 
-const svc = createWorkflowsService();
-console.log(svc.health());
+const workflows = createWorkflowsClient();
+const readiness = await workflows.ready();
+const runs = await workflows.listRuns({ limit: 100 });
 ```
 
-## Configuration
+Its typed operations are generated from the server's OpenAPI document using
+`@hasna/contracts`, with the same credential-bound transport as the CLI and MCP.
+`bun run check:sdk` refuses stale generated code; `bun run generate:sdk` updates it.
 
-| variable | meaning | default |
-|---|---|---|
-| `HASNA_WORKFLOWS_PORT` / `WORKFLOWS_PORT` | serve port | 8790 |
-| `HASNA_WORKFLOWS_HOST` / `WORKFLOWS_HOST` | serve bind host | 127.0.0.1 |
-| `HASNA_WORKFLOWS_DATA_DIR` / `WORKFLOWS_DATA_DIR` | data directory | `~/.hasna/workflows` (the @hasna/paths XDG data home `~/.local/share/hasna/workflows` is adopted once `HASNA_DATA_HOME` is set or the store is migrated there) |
+`createWorkflowsClient({ apiUrl })` provides an explicit authority override. Its
+run API includes `triggerRun`, `getRun`, `listNodes`, `events`, `cancelRun` and
+`resumeRun`. Trigger idempotency keys cover the entire stored history and bind to
+the graph, context and cycle budget. Reusing a key for a different request returns
+HTTP 409. Run context cannot contain the reserved `__wf` or `steps` fields.
+
+A step's optional `cwd` names its working directory on the server executing the
+workflow. It applies to shell commands and model lanes; prefer an absolute path.
+Codex prompts keep their native repository, sandbox and approval defaults. Supply
+`cwd` for work in an existing trusted repository. For a prompt that needs no file
+changes and may run outside a repository, explicitly set `codexMode: "read-only"`:
+
+```ts
+import { createWorkflowsClient, type WorkflowGraph } from "@hasna/workflows/sdk";
+
+const workflows = createWorkflowsClient();
+const graph: WorkflowGraph = {
+  name: "read-only-answer", version: "1",
+  nodes: [
+    { id: "start", type: "start", next: "answer" },
+    { id: "answer", type: "step", lane: "codex", codexMode: "read-only",
+      prompt: "Return the requested answer without changing files.", next: "end" },
+    { id: "end", type: "end" },
+  ],
+};
+await workflows.triggerRun(graph, {}, { idempotencyKey: "read-only-answer-1" });
+```
+
+This explicit mode uses Codex's read-only sandbox, permits a nonrepository
+directory and refuses approval escalation. It applies only to Codex prompt steps;
+shell commands cannot select it. An empty Codex response fails the step even when
+the native process exits successfully. Memoization distinguishes the working
+directory, lane and execution mode.
+
+## MCP
+
+Register `workflows-mcp` as a stdio command in Codex, Claude Code, OpenCode, Sumi,
+Cursor or another MCP harness. Use the harness's supported configuration writer;
+keep existing servers and machine-owned credentials intact. Initialization,
+`tools/list`, graph validation and version inspection require no credential.
+Hosted tools resolve this station's credential when invoked. No token belongs in
+the harness configuration.
+`--stdio` is accepted. Run tools require a stable `idempotencyKey`. Each tool accepts
+an optional `agent`; otherwise identity comes from the native harness context or
+the station. CLI and SDK callers may also set their agent explicitly.
+
+## Server and migration
+
+`workflows-serve` owns execution and persistence. `HASNA_WORKFLOWS_HOST`,
+`HASNA_WORKFLOWS_PORT`, `HASNA_WORKFLOWS_DATA_DIR` and
+`HASNA_WORKFLOWS_API_KEY` configure the server. Set
+`HASNA_WORKFLOWS_DATABASE_URL` to its PostgreSQL database and optionally
+`HASNA_WORKFLOWS_DATABASE_SCHEMA` (default `workflows`). Alias names remain supported;
+database URL aliases must agree. Storage and mode environment selectors never
+enable local fallback. Run `workflows-serve init-db` explicitly to create a fresh
+schema; normal startup and readiness never migrate storage.
+Use durable storage for the data directory and one deployed executor; ephemeral
+container storage is unsuitable. Model lanes require the selected harness's
+native subscription on the executor. They do not inherit paid model API keys.
+
+When the server sits behind an authenticated gateway, set
+`HASNA_WORKFLOWS_ORIGIN_AUTH` to the gateway's scoped origin identity. It must be
+32 to 256 ASCII letters, digits, underscores or hyphens. All API routes, including
+legacy aliases, then require `x-hasna-origin-auth`; only unversioned `/health` and
+`/ready` remain public. The origin identity never replaces caller Bearer authentication.
+
+The versioned API serves health, readiness, version, graph validation, triggers,
+run details, nodes, events, cancellation, resume and inspection routes under `/v1`.
+Legacy unversioned server routes remain aliases. Readiness returns HTTP 503 unless
+authentication and the actual storage schema are available. Cancellation fences
+late results. Resume executes the pinned graph from the saved cursor. A timeout
+whose cancellation is unconfirmed cannot automatically retry or resume.
+PostgreSQL advisory ownership is shared between executors. A lost connection
+leaves a durable execution hold for operator reconciliation; it never silently
+restarts a potentially active command. Deploy one executor with its preserved
+journal so that all event reads use the same authoritative history.
+
+The server stores runs, node history and memo results in three PostgreSQL tables,
+with an append-only session journal in its durable data directory. Journal writers
+serialize through a SQLite mutex that contains no application tables. Before torn-tail
+repair, the exact original is copied and read back at
+`session.wal.preserved-<sha256>`. The required `bun run test:pg` gate uses a fresh
+`WORKFLOWS_TEST_DATABASE_URL` and proves actual storage and HTTP execution. It fails
+when the database is not configured. The ordinary test suite reports these cases
+as skipped when no test database is supplied.
+
+Existing embedded applications import `createWorkflowsService` from
+`@hasna/workflows` and require Bun. The `./sdk` export now denotes the HTTP client.
+Server-only maintenance commands use `workflows-serve admin ...`; operator
+maintenance never selects the client's hosted credentials or changes its target.
+
+An embedded server example:
+
+```ts
+import { createWorkflowsService } from "@hasna/workflows";
+const service = createWorkflowsService({ storageBackend: "sqlite", dataDir: "/srv/workflows", apiKey: process.env.HASNA_WORKFLOWS_API_KEY });
+console.log(service.health());
+```
 
-The server data backend is sqlite (default) or postgresql when
-`HASNA_WORKFLOWS_DATABASE_URL` is set.
+A workflow graph contains one start node, steps or decisions, optional bounded
+while loops, and an end node. `workflows init workflow.json` writes a sample graph
+without creating application state. `workflows validate workflow.json` and
+`workflows graph workflow.json` work offline. `workflows run workflow.json`
+executes on the configured server, and `workflows runs events <run-id>` reads its
+durable execution history.
 
-## License
+Lanes support Claude, Codex, Cursor in local mode, and a Grok CLI when installed.
+A wired substrate is distinct from verified sign-in and usable model capacity;
+missing substrate or authentication fails visibly.
 
-Apache-2.0
+A [Hasna](https://hasna.com) product.