@automatalabs/workflows 0.1.1 → 0.1.2

package/README.md

@@ -0,0 +1,342 @@
+# @automatalabs/workflows
+
+The programmatic **SDK** for AgentPrism — run dynamic, multi-agent **workflow scripts**
+(`agent()` / `parallel()` / `pipeline()` / …) over real coding-agent backends through the
+[Agent Client Protocol](https://agentclientprotocol.com) (ACP).
+
+You author a small JavaScript **script** (a string), the engine runs it in a deterministic,
+journaled, resumable realm, and every `agent()` call inside it is fanned out to a pooled ACP
+backend — **Claude** (`claude-agent-acp`) or **Codex** (`codex-acp`) — driving the actual agent
+subprocess to completion.
+
+This package is the **canonical SDK** that the stdio MCP server
+[`@automatalabs/mcp-server`](https://www.npmjs.com/package/@automatalabs/mcp-server) is built on.
+If you want to expose a `workflow` tool to an MCP host (Claude Code, Zed, …), use that package; if
+you want to embed the runner in your own program, use this one.
+
+It is a **pure library**: it pulls in neither `@modelcontextprotocol/sdk` nor `zod`. It is a thin
+facade that re-exports the clean public surface of the engine + ACP packages and adds one
+convenience helper, `runDynamicWorkflow`, which defaults the agent backend to ACP.
+
+---
+
+## Install
+
+```bash
+pnpm add @automatalabs/workflows
+```
+
+> The backend ACP servers ship as transitive dependencies and are spawned for you on demand; you
+> do not install or start them separately.
+
+---
+
+## Requirements
+
+- **Node.js ≥ 22.**
+- **Backend auth** — the SDK spawns the ACP backend as a child process that inherits your
+  `process.env`, so it uses whatever credentials those agents already use:
+  - **Claude** — a logged-in Claude Code install (`~/.claude`) **or** `ANTHROPIC_API_KEY` in the
+    environment.
+  - **Codex** — a logged-in Codex install (`~/.codex`).
+
+You only need auth for the backend(s) your scripts actually route to. The default backend is
+Claude (override with `AGENTPRISM_DEFAULT_BACKEND`; see [Backend selection](#backend-selection)).
+
+---
+
+## Core API
+
+### a) `runDynamicWorkflow(script, opts?)` — run a script to a terminal result
+
+The one-call entry point. It builds a one-off `WorkflowManager` whose agent backend defaults to
+`createAcpRunner()` and runs the script to a **terminal** `WorkflowRunResult`. It never throws for
+an ordinary pause/fail/abort — read `result.status` directly.
+
+```ts
+import { runDynamicWorkflow } from "@automatalabs/workflows";
+
+const script = `
+  export const meta = {
+    name: "repo-scan",
+    description: "describe a repo as JSON, two ways in parallel",
+    phases: [{ title: "Fan" }],
+  };
+
+  const SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["repo", "fileCount"],
+    properties: { repo: { type: "string" }, fileCount: { type: "number" } },
+  };
+
+  phase("Fan");
+  log("scanning " + args.repo);
+  return await parallel([
+    () => agent("Report this repo as JSON {repo, fileCount}.", { label: "a1", schema: SCHEMA }),
+    () => agent("Report this repo as JSON {repo, fileCount}.", { label: "a2", schema: SCHEMA }),
+  ]);
+`;
+
+const run = await runDynamicWorkflow(script, { args: { repo: "agentprism" } });
+
+run.status;      // "completed" | "paused" | "failed" | "aborted"
+run.result;      // [{ repo, fileCount }, …] — the script's return value (schema-validated)
+run.tokenUsage;  // { input, output, total, cost, … } | undefined
+run.runId;       // stable id; pass back to resume a paused run from its journal
+```
+
+Options (`RunDynamicWorkflowOptions`):
+
+| field    | type           | meaning |
+|----------|----------------|---------|
+| `args`   | `unknown`      | The value handed to the script's `args` global. |
+| `runner` | `AgentRunner`  | Swap the backend (or stub it in tests). Omitted ⇒ `createAcpRunner()`. |
+| `exec`   | `ExecOptions`  | Per-run controls forwarded to the manager: `tokenBudget`, `agentTimeoutMs`, `concurrency`, `agentRetries`, `signal`, `onProgress`, `confirm`, … |
+
+```ts
+const run = await runDynamicWorkflow(script, {
+  args: { repo: "agentprism" },
+  exec: {
+    tokenBudget: 200_000,
+    concurrency: 4,
+    onProgress: (snapshot) => console.error(snapshot.doneCount, "/", snapshot.agentCount),
+  },
+});
+```
+
+Every script **must** begin with `export const meta = { name, description, phases? }` as its first
+statement, and must be **deterministic** — `Date.now()`, `Math.random()`, and `new Date()` are
+unavailable inside the realm (they would break journal replay on resume).
+
+### b) `createAcpRunner().run(...)` — drive a single agent
+
+Skip the script realm entirely and call one agent directly. The runner is the default ACP
+`AgentRunner`. With a `schema`, `run()` returns the **validated object**; without one, it returns
+the assistant's final **text**.
+
+```ts
+import { createAcpRunner } from "@automatalabs/workflows";
+
+const runner = createAcpRunner();           // optional: { size } pool option, default 1
+try {
+  const data = await runner.run("Summarize this repo as JSON {summary}.", {
+    schema: {
+      type: "object", additionalProperties: false,
+      required: ["summary"], properties: { summary: { type: "string" } },
+    },
+    model: "opus",          // routes to Claude; e.g. "gpt-5-codex" routes to Codex
+    cwd: process.cwd(),     // absolute working dir for the agent's session
+  });
+  // data is the schema-validated object (not text)
+
+  const text = await runner.run("Name this repo in one word.");  // no schema ⇒ string
+} finally {
+  await runner.dispose();   // close the pooled backend processes when you're done
+}
+```
+
+`run(prompt, options?)` accepts the seam's `RunOptions`: `schema`, `model`, `tier`, `cwd`,
+`instructions`, `label`, `toolNames` / `disallowedToolNames`, `signal`, `mcpServers`, and the
+out-of-band telemetry callbacks `onUsage` / `onModelResolved` / `onModelFallback` / `onHistory`.
+Token/cost usage is delivered via `onUsage` (it may never fire — ACP usage is experimental), never
+via the return value.
+
+> The ACP server **process** is pooled and reused across `run()` calls; each `run()` opens and
+> closes one **session** on it. Call `dispose()` once at shutdown to tear the pool down. Pool size
+> is `AcpPoolOptions.size` (default 1) or `AGENTPRISM_ACP_POOL_SIZE`.
+
+### c) `WorkflowManager` — stateful / resumable runs
+
+`runDynamicWorkflow` is a thin wrapper over a fresh `WorkflowManager`. Construct one yourself to
+keep run state across calls, persist journals, and **resume** a paused run.
+
+```ts
+import { WorkflowManager, createAcpRunner } from "@automatalabs/workflows";
+
+const manager = new WorkflowManager({ agent: createAcpRunner() });
+
+const run = await manager.runSync(script, { repo: "agentprism" }, { tokenBudget: 200_000 });
+
+if (run.status === "paused") {
+  // A pause carries a journal of every completed agent() call. Re-hydrate it and re-run the
+  // SAME script: the unchanged prefix is replayed from the journal, the rest runs live.
+  const persisted = manager.getPersistence().load(run.runId);
+  const resumeJournal = new Map(persisted?.journal?.map((e) => [e.index, e]) ?? []);
+  const finished = await manager.runSync(script, { repo: "agentprism" }, { resumeJournal });
+  console.log(finished.status); // "completed", typically
+}
+```
+
+`runSync(script, args?, exec?)` always resolves to a terminal `WorkflowRunResult`. A run **pauses**
+(rather than fails) on a provider usage limit or a headless `checkpoint()`; both are resumable as
+above. `WorkflowManagerOptions` lets you set a default `agent`, `concurrency`, `cwd`, a
+`loadSavedWorkflow` resolver (enables nested `workflow('name')`), and per-agent timeout/retry
+defaults.
+
+### d) Bring your own backend — implement the `AgentRunner` seam
+
+`AgentRunner` is the single, frozen coupling point between the engine and any backend. Implement
+its one method and inject it anywhere a runner is accepted (`runDynamicWorkflow({ runner })`,
+`new WorkflowManager({ agent })`, or `runSync(script, args, { agent })`).
+
+```ts
+import {
+  runDynamicWorkflow,
+  type AgentRunner,
+  type RunOptions,
+  type AgentResult,
+} from "@automatalabs/workflows";
+import type { TSchema } from "typebox";
+
+const echoRunner: AgentRunner = {
+  async run<S extends TSchema | undefined>(prompt: string, options?: RunOptions<S>) {
+    // schema present ⇒ return the validated object; absent ⇒ return text.
+    options?.onUsage?.({ input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0, cost: 0 });
+    return `echo: ${prompt}` as AgentResult<S>;
+  },
+};
+
+const run = await runDynamicWorkflow(script, { runner: echoRunner });
+```
+
+Seam contract (summarized): `run()` returns the **raw** value (schema ⇒ validated object, no schema
+⇒ string) — never an envelope; usage flows out-of-band via `options.onUsage`; on failure **throw**
+(ideally a `WorkflowError` so `instanceof` holds across packages); honor `options.signal` but do
+**not** implement your own timeout (the engine owns timeout/abort). This makes the SDK fully
+testable without a live agent — pass a stub runner.
+
+---
+
+## The in-script DSL
+
+The orchestration primitives are **not importable symbols**. They are **globals injected into the
+script's `vm` realm**, available only **inside** the script string you pass to
+`runDynamicWorkflow` / `runSync`. There is nothing to import to obtain them. Their shapes are
+documented for editor IntelliSense by the **ambient `dsl.d.ts`** shipped with this package (it
+ships no runtime code).
+
+| global | what it does |
+|--------|--------------|
+| `agent(prompt, options?)` | Run ONE subagent to completion; returns its result (text, or the validated object with `options.schema`). |
+| `parallel(thunks)` | Run an array of **thunks** (`() => Promise`) concurrently; resolves in input order. |
+| `pipeline(items, ...stages)` | Map `items` through sequential async stages, concurrently across items. |
+| `workflow(nameOrScript, args?)` | Run a saved (or inline) workflow nested in this run, sharing its limiter/budget. |
+| `verify(item, options?)` | Adversarial verification panel — N reviewers vote whether `item` is real/correct. |
+| `judgePanel(attempts, options?)` | LLM-judge panel — score candidates against a rubric, return the best. |
+| `loopUntilDry(options)` | Repeat a round, collecting deduped new items until it dries up. |
+| `completenessCheck(args, results)` | Ask a critic what is still missing. |
+| `retry(thunk, options?)` | Bounded retry until `until(result)` holds. |
+| `gate(thunk, validator, options?)` | Validate-and-feed-back loop until it passes. |
+| `checkpoint(text, options?)` | Deterministic, journaled human gate (headless takes a default). |
+| `phase(title, options?)` | Open a named phase (optional soft token sub-budget). |
+| `log(message)` | Append a line to the run log. |
+| `args` | The input bag passed in via `{ args }`. |
+| `budget` | Live token-budget view: `budget.total`, `budget.spent()`, `budget.remaining()`. |
+
+(`console.log/info/warn/error` route to `log` too.) Pass these primitives **thunks**, not
+promises — `parallel([() => agent("a"), () => agent("b")])`, not `parallel([agent("a"), …])`.
+
+---
+
+## Structured output
+
+Pass a JSON Schema to `agent({ schema })` (in a script) or `runner.run(prompt, { schema })` (direct)
+and the result is a **validated object** instead of text. The backend constrains output natively
+(Claude `outputFormat`; Codex strict `outputSchema`), then the value is coerced and validated
+client-side (typebox `Convert` → `Check`); on a miss the runner re-prompts a bounded number of
+times before failing with a non-recoverable `SCHEMA_NONCOMPLIANCE`.
+
+A **plain JSON Schema object literal** works everywhere (this is the only option inside a script —
+no schema-builder is injected into the realm):
+
+```json
+{
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["title", "score"],
+  "properties": {
+    "title": { "type": "string" },
+    "score": { "type": "number" }
+  }
+}
+```
+
+In TypeScript you may instead build the schema with [typebox](https://github.com/sinclairzx81/typebox)
+(`Type.Object({ … })`) for static result typing. Two helpers convert a typebox schema to the exact
+wire JSON Schema each backend expects:
+
+```ts
+import { toJsonSchema, toStrictJsonSchema } from "@automatalabs/workflows";
+import { Type } from "typebox";
+
+const schema = Type.Object({ title: Type.String(), score: Type.Number() });
+toJsonSchema(schema);        // plain JSON Schema (Claude outputFormat)
+toStrictJsonSchema(schema);  // OpenAI-strict-normalized (Codex outputSchema)
+```
+
+---
+
+## Backend selection
+
+The backend for each agent is chosen from its `model` (preferred) or `tier` string:
+
+- **Provider prefix** — `anthropic/…` or `claude/…` ⇒ Claude; `openai/…` or `codex/…` ⇒ Codex.
+- **Bare id** — matched by pattern: `codex` / `gpt` / `openai` / `o<digit>` ⇒ Codex;
+  `claude` / `opus` / `sonnet` / `haiku` / `anthropic` ⇒ Claude.
+- **No match / no spec** — the default backend: `AGENTPRISM_DEFAULT_BACKEND` (`claude` | `codex`,
+  default `claude`).
+
+```ts
+import { selectBackend } from "@automatalabs/workflows";
+
+selectBackend({ model: "opus" }).id;          // "claude"
+selectBackend({ model: "gpt-5-codex" }).id;    // "codex"
+selectBackend({ model: "anthropic/claude-sonnet" }).id; // "claude"
+```
+
+Within a provider, the model spec selects the concrete model on the session (Claude `_meta` model /
+Codex config). Per-backend pool size is `AGENTPRISM_ACP_POOL_SIZE` (or `AcpPoolOptions.size`).
+
+---
+
+## Exports
+
+```ts
+// ── Run entry & helper ──
+runDynamicWorkflow,           // (script, { args?, runner?, exec? }) => Promise<WorkflowRunResult>
+runWorkflow,                  // the bare engine run (no status trio)
+parseWorkflowScript,          // parse a script's meta + body
+WorkflowManager,              // stateful / resumable run manager
+
+// ── ACP backend ──
+createAcpRunner,              // () => AcpAgentRunner (the default AgentRunner)
+AcpAgentRunner,               // class — implements AgentRunner over ACP
+selectBackend,                // pick Claude vs Codex from a model/tier spec
+ClaudeBackend, CodexBackend,  // the concrete backends
+toJsonSchema, toStrictJsonSchema,
+
+// ── Errors ──
+WorkflowError, WorkflowErrorCode, isWorkflowError, isProviderUsageLimit,
+
+// ── Types ──
+RunDynamicWorkflowOptions, WorkflowRunOptions, AgentOptions, ExecOptions,
+WorkflowManagerOptions, CheckpointOptions, WorkflowRunResult, WorkflowSnapshot,
+AcpPoolOptions, AgentRunner, RunOptions, AgentResult, AgentUsage, JournalEntry,
+```
+
+(The DSL globals — `agent`, `parallel`, `pipeline`, … — are **not** exported; they are realm
+globals documented by the ambient `dsl.d.ts`.)
+
+---
+
+## See also
+
+- **[`@automatalabs/mcp-server`](https://www.npmjs.com/package/@automatalabs/mcp-server)** — the
+  stdio MCP server built on this SDK. It wraps the same engine + ACP backend behind a single
+  `workflow` tool (bin: `agentprism-workflow`) for any MCP host. Use it when you want the
+  **MCP-tool route** instead of embedding the runner in code.
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 import type { ExecOptions } from "@automatalabs/workflow-engine";
 import type { AgentRunner, WorkflowRunResult } from "@automatalabs/shared-types";
 export { runWorkflow, parseWorkflowScript, WorkflowManager } from "@automatalabs/workflow-engine";
-export type { WorkflowRunOptions, AgentOptions, ExecOptions, WorkflowManagerOptions, CheckpointOptions, WorkflowRunResult, } from "@automatalabs/workflow-engine";
+export type { WorkflowRunOptions, AgentOptions, ExecOptions, WorkflowManagerOptions, CheckpointOptions, WorkflowRunResult, WorkflowSnapshot, } from "@automatalabs/workflow-engine";
 export { WorkflowError, WorkflowErrorCode, isWorkflowError, isProviderUsageLimit, } from "@automatalabs/workflow-engine";
 export { createAcpRunner, AcpAgentRunner, selectBackend, ClaudeBackend, CodexBackend, toJsonSchema, toStrictJsonSchema, } from "@automatalabs/acp-agents";
 export type { AcpPoolOptions } from "@automatalabs/acp-agents";
 export type { AgentRunner, RunOptions, AgentResult, AgentUsage } from "@automatalabs/shared-types";
+export type { JournalEntry } from "@automatalabs/shared-types";
 /** Options for {@link runDynamicWorkflow}. */
 export interface RunDynamicWorkflowOptions {
     /**

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAIjF,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAClG,YAAY,EACV,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,oBAAoB,GACrB,MAAM,+BAA+B,CAAC;AAIvC,OAAO,EACL,eAAe,EACf,cAAc,EACd,aAAa,EACb,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAI/D,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAEnG,8CAA8C;AAC9C,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,+EAA+E;IAC/E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,kGAAkG;IAClG,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,yBAA8B,GACnC,OAAO,CAAC,iBAAiB,CAAC,CAE5B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAIjF,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAClG,YAAY,EACV,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,oBAAoB,GACrB,MAAM,+BAA+B,CAAC;AAIvC,OAAO,EACL,eAAe,EACf,cAAc,EACd,aAAa,EACb,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAI/D,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACnG,YAAY,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D,8CAA8C;AAC9C,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,+EAA+E;IAC/E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,kGAAkG;IAClG,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,yBAA8B,GACnC,OAAO,CAAC,iBAAiB,CAAC,CAE5B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automatalabs/workflows",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -24,9 +24,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@automatalabs/shared-types": "0.1.1",
-    "@automatalabs/workflow-engine": "0.1.1",
-    "@automatalabs/acp-agents": "0.1.1"
+    "@automatalabs/shared-types": "0.1.2",
+    "@automatalabs/workflow-engine": "0.1.2",
+    "@automatalabs/acp-agents": "0.1.2"
   },
   "scripts": {
     "build": "tsc -b",