@automatalabs/workflows 0.20.2 → 0.21.0

package/README.md

@@ -263,6 +263,47 @@ testable without a live agent — pass a stub runner.
 
 ---
 
+## Loading workflows from folders — `openWorkflowDir`
+
+Integrators who keep a versioned folder of workflow scripts don't need to hand-roll
+`readFileSync` plumbing or a `loadSavedWorkflow` resolver:
+
+```ts
+import { openWorkflowDir, runDynamicWorkflow } from "@automatalabs/workflows";
+
+const flows = openWorkflowDir("./workflows");        // or ["./workflows", teamDir] — first hit wins
+
+flows.list();               // [{ name, file, meta }] — meta parsed per call, browsable by a UI
+flows.read("review-pr");    // name → script string; throws with searched dirs + did-you-mean
+flows.resolve;              // (name) => string | undefined — IS a loadSavedWorkflow resolver
+
+const run = await runDynamicWorkflow("review-pr", {  // a NAME works when `workflows` is set
+  workflows: flows,                                  // also accepts "./workflows" or [dir, dir]
+  args: { pr: 42 },
+});
+```
+
+Semantics worth knowing:
+
+- **Construction does no I/O** — nothing is created, nothing is scanned or cached. Every method
+  reads the filesystem at call time, so a long-lived view always reflects the current working
+  tree (a cached scan would serve stale scripts after a `git checkout`/pull/save). Missing
+  directories simply contribute nothing.
+- **The filename stem is the name** (`review-pr.workflow.js` or `review-pr.js` ⇒ `review-pr`),
+  mirroring the agentType registry convention; across dirs the first hit wins, within a dir
+  `.workflow.js` beats `.js`.
+- **`workflows` also wires nested calls**: with the option set, `workflow("<name>")` inside the
+  script resolves from the same view. (Without it, `runDynamicWorkflow` has no saved-workflow
+  resolver and nested names cannot resolve.) A top-level string containing `export const meta`
+  is always treated as a verbatim script, never a name.
+- **Versioning is git's job.** A run persists its script content, so `resume()` replays the exact
+  script that started the run even if the file changed since; an edited file simply cache-misses
+  from the first changed call on the next fresh run.
+- **`resolve()` validates name shape strictly** (one flat path segment) — inline nested scripts
+  fall through to verbatim parsing, and path traversal out of the configured dirs is impossible.
+
+---
+
 ## Listening in on the live ACP stream (events)
 
 `createAcpRunner()` returns an `AcpAgentRunner` with a **typed event bus**. Subscribe with
@@ -353,6 +394,42 @@ promises — `parallel([() => agent("a"), () => agent("b")])`, not `parallel([ag
 
 ---
 
+## Validating scripts — `agentprism-workflows validate`
+
+The package ships a bin that validates a workflow script **without spending tokens or spawning
+any agent process** — no backend auth needed:
+
+```bash
+npx @automatalabs/workflows validate my-workflow.js --args '{"target":"src/"}'
+```
+
+Two passes: a **static parse** (the `meta` literal, syntax, the determinism blocklist), then a
+**dry run** — the script executes in the real engine realm while every `agent()` call is served
+by an in-process mock `AgentRunner` that fabricates schema-conforming results. The dry run
+catches what a parse can't: thunk-vs-promise mistakes, reference errors, broken plumbing between
+calls. Checkpoints take their headless defaults; script-declared `meta.backends` are treated as
+approved (with a warning that real runs require approval). The report lists every agent call with
+its backend attribution, every checkpoint, and warnings; exit codes are `0` valid, `1` parse
+failure, `2` dry-run failure, `3` usage error.
+
+Flags: `--args <json>` / `--args-file <path>`, `--workflows-dir <dir>` (repeatable — validate by
+NAME and resolve nested `workflow("<name>")` calls from your folder), `--parse-only`,
+`--cwd <dir>`, `--token-budget <n>` (exercise `budget`-guarded paths; the mock reports 1000
+tokens per call), `--max-agents <n>`, `--timeout-ms <n>`, `--json`.
+
+The same check is available programmatically — it never throws for an invalid script:
+
+```ts
+import { validateWorkflowScript } from "@automatalabs/workflows";
+
+const report = await validateWorkflowScript(script, { args: { target: "src/" } });
+report.ok;                 // parse ok AND dry run completed
+report.dryRun?.agentCalls; // [{ label, phase, model, backend, schema }, …]
+report.warnings;           // approval reminders, phase mismatches, headless-abort checkpoints, …
+```
+
+---
+
 ## Structured output
 
 Pass a JSON Schema to `agent({ schema })` (in a script) or `runner.run(prompt, { schema })` (direct)
@@ -422,6 +499,10 @@ Within a provider, the model spec selects the concrete model through ACP session
 runDynamicWorkflow,           // (script, { args?, runner?, exec? }) => Promise<WorkflowRunResult>
 runWorkflow,                  // the bare engine run (no status trio)
 parseWorkflowScript,          // parse a script's meta + body
+validateWorkflowScript,       // token-free parse + mock-runner dry run (the `validate` CLI's core)
+fabricateFromSchema,          // the dry run's JSON-Schema value fabricator
+formatValidateReport,         // render a ValidateWorkflowReport as CLI text
+openWorkflowDir,              // read-only view over folders of workflow scripts (name = filename stem)
 WorkflowManager,              // stateful / resumable run manager
 
 // ── ACP backend ──
@@ -442,6 +523,7 @@ AGENTPRISM_PERSISTENCE_ROOT_ENV,
 
 // ── Types ──
 RunDynamicWorkflowOptions, WorkflowRunOptions, AgentOptions, ExecOptions,
+ValidateWorkflowOptions, ValidateWorkflowReport, ValidatedAgentCall, ValidatedCheckpoint,
 WorkflowManagerOptions, CheckpointOptions, WorkflowRunResult, WorkflowSnapshot,
 WorkflowPathOptions, RunPersistence, RunPersistenceOptions,
 AcpPoolOptions, AgentRunner, RunOptions, AgentResult, AgentUsage, JournalEntry,
@@ -459,6 +541,25 @@ globals documented by the ambient `dsl.d.ts`.)
 
 ---
 
+## Skill for AI agents that write workflows
+
+The repository publishes an **agent skill** — a self-contained, backend-agnostic authoring guide
+in the standard `SKILL.md` format — at
+[`skills/agentprism-workflow-authoring/`](https://github.com/VikashLoomba/agentprism-workflows/tree/main/skills/agentprism-workflow-authoring).
+Install it into whatever coding agent you use (Claude Code, Codex, Cursor, OpenCode, …) with the
+[skills](https://skills.sh) CLI:
+
+```bash
+npx skills add VikashLoomba/agentprism-workflows
+```
+
+It teaches the full script DSL: routing each `agent()` call to a different ACP backend inside one
+script, structured outputs across all backends, `checkpoint()` gates, budgets, worktree
+isolation, and the determinism rules that make runs resumable. `reference.md` alongside it holds
+the exhaustive option tables.
+
+---
+
 ## See also
 
 - **[`@automatalabs/mcp-server`](https://www.npmjs.com/package/@automatalabs/mcp-server)** — the

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+// The @automatalabs/workflows bin (`agentprism-workflows`). One subcommand:
+//
+//   agentprism-workflows validate <workflow-file> [options]
+//
+// Validates a workflow script without spending tokens: static parse (meta literal,
+// syntax, determinism blocklist), then a dry run over an in-process mock AgentRunner
+// that fabricates schema-conforming results — no ACP process is spawned. See
+// ./validate.ts for the programmatic API (`validateWorkflowScript`).
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { openWorkflowDir } from "@automatalabs/workflow-engine";
+import { validateWorkflowScript, formatValidateReport } from "./validate.js";
+const USAGE = `Usage: agentprism-workflows validate <workflow-file-or-name> [options]
+
+Validates an AgentPrism workflow script without spending tokens:
+  1. static parse — the meta literal, syntax, and the determinism blocklist
+  2. dry run — the script executes against a mock agent backend that fabricates
+     schema-conforming results; no ACP process is spawned, no tokens are spent,
+     and checkpoints resolve to their headless defaults
+
+Options:
+  --args <json>          the script's \`args\` global for the dry run (a JSON value)
+  --args-file <path>     read the args JSON from a file instead
+  --workflows-dir <dir>  a directory of workflow scripts (repeatable; precedence in
+                         the order given). Enables validating by NAME (filename stem)
+                         and resolves nested workflow("<name>") calls in the dry run
+  --parse-only           static parse only; skip the dry run
+  --cwd <dir>            base cwd for the dry run (default: a throwaway temp dir;
+                         point it at a real repo only if you want worktree isolation
+                         to create — and clean up — real git worktrees)
+  --token-budget <n>     set budget.total so budget-guarded paths execute
+                         (the mock backend reports 1000 tokens per agent call)
+  --max-agents <n>       cap dry-run agent calls
+  --timeout-ms <n>       dry-run wall-clock limit (default 30000)
+  --json                 print the machine-readable report to stdout
+  -h, --help             show this help
+
+Notes:
+  - without --workflows-dir, nested workflow("<saved-name>") calls fail in the dry
+    run (no saved-workflow resolver); nested INLINE script strings always validate
+  - script-declared meta.backends are treated as approved for the dry run, but the
+    report reminds you that real runs require explicit approval
+
+Exit codes: 0 valid · 1 parse/static failure · 2 dry-run failure · 3 usage error`;
+function fail(message) {
+    process.stderr.write(`${message}\n\nRun \`agentprism-workflows validate --help\` for usage.\n`);
+    process.exit(3);
+}
+function parseIntFlag(name, raw) {
+    const value = Number(raw);
+    if (raw === undefined || !Number.isFinite(value) || value <= 0)
+        fail(`${name} expects a positive number`);
+    return Math.floor(value);
+}
+async function main(argv) {
+    const [command, ...rest] = argv;
+    if (command === undefined || command === "-h" || command === "--help") {
+        process.stdout.write(`${USAGE}\n`);
+        process.exit(command === undefined ? 3 : 0);
+    }
+    if (command !== "validate")
+        fail(`unknown command "${command}" — the only command is: validate`);
+    let file;
+    let json = false;
+    const workflowDirs = [];
+    const options = {};
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        switch (arg) {
+            case "-h":
+            case "--help":
+                process.stdout.write(`${USAGE}\n`);
+                process.exit(0);
+                break;
+            case "--json":
+                json = true;
+                break;
+            case "--parse-only":
+                options.dryRun = false;
+                break;
+            case "--args":
+                try {
+                    options.args = JSON.parse(rest[++i] ?? "");
+                }
+                catch {
+                    fail("--args expects a JSON value (quote it for your shell)");
+                }
+                break;
+            case "--args-file":
+                try {
+                    options.args = JSON.parse(readFileSync(resolve(rest[++i] ?? ""), "utf8"));
+                }
+                catch (error) {
+                    fail(`--args-file: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                break;
+            case "--workflows-dir":
+                workflowDirs.push(resolve(rest[++i] ?? fail("--workflows-dir expects a directory")));
+                break;
+            case "--cwd":
+                options.cwd = resolve(rest[++i] ?? fail("--cwd expects a directory"));
+                break;
+            case "--token-budget":
+                options.tokenBudget = parseIntFlag("--token-budget", rest[++i]);
+                break;
+            case "--max-agents":
+                options.maxAgents = parseIntFlag("--max-agents", rest[++i]);
+                break;
+            case "--timeout-ms":
+                options.timeoutMs = parseIntFlag("--timeout-ms", rest[++i]);
+                break;
+            default:
+                if (arg.startsWith("-"))
+                    fail(`unknown option "${arg}"`);
+                if (file !== undefined)
+                    fail("exactly one workflow file expected");
+                file = arg;
+        }
+    }
+    if (file === undefined)
+        fail("missing <workflow-file-or-name>");
+    const flows = workflowDirs.length > 0 ? openWorkflowDir(workflowDirs) : undefined;
+    if (flows)
+        options.workflows = flows;
+    // The positional is a file path first; with --workflows-dir it may also be a NAME.
+    let script;
+    if (existsSync(resolve(file))) {
+        try {
+            script = readFileSync(resolve(file), "utf8");
+        }
+        catch (error) {
+            fail(`cannot read ${file}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    else if (flows) {
+        try {
+            script = flows.read(file); // throws with searched dirs + closest matches
+        }
+        catch (error) {
+            fail(error instanceof Error ? error.message : String(error));
+        }
+    }
+    else {
+        fail(`cannot read ${file}: no such file (pass --workflows-dir to validate by name)`);
+    }
+    const report = await validateWorkflowScript(script, options);
+    process.stdout.write(json ? `${JSON.stringify(report, null, 2)}\n` : `${formatValidateReport(report)}\n`);
+    process.exit(report.exitCode);
+}
+main(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(`validate crashed: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+    process.exit(3);
+});

package/dist/index.d.ts

@@ -1,8 +1,11 @@
 import { WorkflowManager as EngineWorkflowManager } from "@automatalabs/workflow-engine";
 import type { AcpEventName, AcpRunnerEventMap } from "@automatalabs/acp-agents";
-import type { ExecOptions, WorkflowManagerOptions } from "@automatalabs/workflow-engine";
+import type { ExecOptions, WorkflowDir, WorkflowManagerOptions } from "@automatalabs/workflow-engine";
 import type { AgentRunner, WorkflowBackendConfig, WorkflowRunResult } from "@automatalabs/shared-types";
 export { runWorkflow, parseWorkflowScript } from "@automatalabs/workflow-engine";
+export { openWorkflowDir, type WorkflowDir, type WorkflowDirEntry, type OpenWorkflowDirOptions, } from "@automatalabs/workflow-engine";
+export { validateWorkflowScript, fabricateFromSchema, formatValidateReport, MOCK_TOKENS_PER_AGENT } from "./validate.js";
+export type { ValidateWorkflowOptions, ValidateWorkflowReport, ValidatedAgentCall, ValidatedCheckpoint, } from "./validate.js";
 export type { WorkflowRunOptions, AgentOptions, ExecOptions, WorkflowManagerOptions, CheckpointOptions, WorkflowRunResult, WorkflowSnapshot, WorkflowPathOptions, RunPersistence, RunPersistenceOptions, } from "@automatalabs/workflow-engine";
 export { AGENTPRISM_PERSISTENCE_ROOT_ENV, WorkflowError, WorkflowErrorCode, isWorkflowError, isProviderUsageLimit, } from "@automatalabs/workflow-engine";
 export { createAcpRunner, AcpAgentRunner, InteractiveSession, selectBackend, ClaudeBackend, CodexBackend, CustomAcpBackend, AGENT_METHODS, CLIENT_METHODS, AGENT_METHOD_COVERAGE, CLIENT_METHOD_COVERAGE, ACP_AUTH_REQUIRED_ERROR_CODE, clientCapabilitiesFor, adaptPromptContent, resolveBackendRegistry, BACKENDS_ENV, toJsonSchema, toStrictJsonSchema, } from "@automatalabs/acp-agents";
@@ -89,6 +92,14 @@ export interface RunDynamicWorkflowOptions {
     exec?: ExecOptions;
     /** Approval policy for script-declared `meta.backends` (see {@link ScriptBackendApproval}). */
     allowScriptBackends?: ScriptBackendApproval;
+    /**
+     * A workflow directory view (or dir path(s) to open one over) serving saved workflows
+     * by name. When set, the first argument may be a workflow NAME instead of a script
+     * (resolver first, verbatim-script fallback — the engine's own nested-workflow rule),
+     * and nested `workflow("<name>")` calls resolve from the same view (it is wired into
+     * the run's `loadSavedWorkflow`).
+     */
+    workflows?: string | string[] | WorkflowDir;
 }
 /**
  * Run a dynamic workflow script to a TERMINAL result, with the AgentRunner seam

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -10,10 +10,19 @@
 // vm-realm globals, NOT importable symbols; they are documented for author IntelliSense
 // in ./dsl.d.ts (referenced above), not exported here.
 import { ACP_CROSS_CUTTING_EVENT_NAMES, createAcpRunner } from "@automatalabs/acp-agents";
-import { parseWorkflowScript, WorkflowError, WorkflowErrorCode, WorkflowManager as EngineWorkflowManager, } from "@automatalabs/workflow-engine";
+import { openWorkflowDir, parseWorkflowScript, WorkflowError, WorkflowErrorCode, WorkflowManager as EngineWorkflowManager, } from "@automatalabs/workflow-engine";
 // ── Engine: run entry, script parsing, the managed-run lifecycle, and the
 //    option/result + error types the host composes against. ──
 export { runWorkflow, parseWorkflowScript } from "@automatalabs/workflow-engine";
+// ── Workflow directory view: openWorkflowDir("./workflows") binds a read-only,
+//    per-call-fresh view over folders of versioned workflow scripts (name = filename
+//    stem). `view.resolve` IS a loadSavedWorkflow resolver; runDynamicWorkflow accepts
+//    the view (or dir paths) via `workflows` to serve top-level names AND nested
+//    workflow("<name>") calls. ──
+export { openWorkflowDir, } from "@automatalabs/workflow-engine";
+// ── Token-free script validation: static parse + mock-runner dry run. Also the core of
+//    the `agentprism-workflows validate` CLI (./cli.ts). ──
+export { validateWorkflowScript, fabricateFromSchema, formatValidateReport, MOCK_TOKENS_PER_AGENT } from "./validate.js";
 export { AGENTPRISM_PERSISTENCE_ROOT_ENV, WorkflowError, WorkflowErrorCode, isWorkflowError, isProviderUsageLimit, } from "@automatalabs/workflow-engine";
 // ── ACP backend: the default AgentRunner implementation, interactive sessions, backend
 //    selection, the concrete backends (built-in + custom registry), the pool/runner options,
@@ -158,12 +167,22 @@ function toAgentEventPayload(name, event) {
  * for an ordinary pause/fail — so the caller can read `result.status` directly.
  */
 export async function runDynamicWorkflow(script, opts = {}) {
+    // Saved-workflow view: `script` may be a workflow NAME when `workflows` is set. A real
+    // script always contains the mandatory `export const meta` head, so anything without it
+    // is treated as a name and resolved via read() — which throws a diagnosable error
+    // (searched dirs + closest matches) instead of the engine's parse error on a bare name.
+    const flows = opts.workflows === undefined
+        ? undefined
+        : typeof opts.workflows === "string" || Array.isArray(opts.workflows)
+            ? openWorkflowDir(opts.workflows, { cwd: opts.cwd })
+            : opts.workflows;
+    const resolvedScript = flows !== undefined && !script.includes("export const meta") ? flows.read(script) : script;
     // Script-declared backends need explicit approval BEFORE the run. A malformed script is
     // deliberately not diagnosed here — runSync re-parses and throws the engine's own parse
     // error (its pre-existing contract), so the approval gate never masks a parse message.
     let declared;
     try {
-        declared = parseWorkflowScript(script).meta.backends;
+        declared = parseWorkflowScript(resolvedScript).meta.backends;
     }
     catch {
         declared = undefined;
@@ -174,9 +193,9 @@ export async function runDynamicWorkflow(script, opts = {}) {
     }
     const owned = opts.runner === undefined;
     const runner = opts.runner ?? createAcpRunner();
-    const manager = new WorkflowManager({ agent: runner, cwd: opts.cwd });
+    const manager = new WorkflowManager({ agent: runner, cwd: opts.cwd, loadSavedWorkflow: flows?.resolve });
     try {
-        return await manager.runSync(script, opts.args, exec);
+        return await manager.runSync(resolvedScript, opts.args, exec);
     }
     finally {
         manager.dispose();

package/dist/validate.d.ts

@@ -0,0 +1,84 @@
+import type { WorkflowDir } from "@automatalabs/workflow-engine";
+import type { WorkflowMeta } from "@automatalabs/shared-types";
+export interface ValidateWorkflowOptions {
+    /** The `args` global handed to the script during the dry run. */
+    args?: unknown;
+    /** A workflow directory view (or dir path(s)) serving saved workflows by name, so
+     *  nested `workflow("<name>")` calls resolve during the dry run instead of failing. */
+    workflows?: string | string[] | WorkflowDir;
+    /** Base cwd for the dry run. Default: a throwaway temp dir (so `isolation: "worktree"`
+     *  degrades to a no-op instead of creating real worktrees in a repo). */
+    cwd?: string;
+    /** false => static parse only, no dry run. Default true. */
+    dryRun?: boolean;
+    /** Set budget.total for the dry run so budget-guarded paths execute. The mock runner
+     *  reports 1000 tokens per agent call. */
+    tokenBudget?: number;
+    /** Cap on dry-run agent calls (defaults to the engine's own cap). */
+    maxAgents?: number;
+    /** Dry-run wall-clock limit. Default 30_000 ms. */
+    timeoutMs?: number;
+}
+/** One agent() call observed during the dry run, with its backend attribution. */
+export interface ValidatedAgentCall {
+    label: string;
+    phase?: string;
+    /** The model spec the call requested (undefined = the run/session default). */
+    model?: string;
+    tier?: string;
+    mode?: string;
+    /** Which backend the spec routes to: "claude" | "codex" | "opencode" | a custom backend
+     *  name (suffixed " (script-declared)" when it comes from meta.backends) | "default". */
+    backend: string;
+    /** True when the call requested structured output. */
+    schema: boolean;
+}
+export interface ValidatedCheckpoint {
+    prompt: string;
+    kind: string;
+    /** The reply the dry run took (the checkpoint's headless default). */
+    reply: unknown;
+}
+export interface ValidateWorkflowReport {
+    /** True when the parse succeeded AND the dry run (if performed) completed. */
+    ok: boolean;
+    /** 0 = valid; 1 = parse/static failure; 2 = dry-run failure. */
+    exitCode: 0 | 1 | 2;
+    parse: {
+        ok: boolean;
+        error?: string;
+        meta?: WorkflowMeta;
+    };
+    dryRun?: {
+        ok: boolean;
+        status: string;
+        reason?: string;
+        /** True when the run was cut off by ValidateWorkflowOptions.timeoutMs. */
+        timedOut: boolean;
+        agentCalls: ValidatedAgentCall[];
+        checkpoints: ValidatedCheckpoint[];
+        phasesVisited: string[];
+        logs: string[];
+        durationMs: number;
+        /** The script's return value, composed from fabricated agent results. */
+        result?: unknown;
+    };
+    warnings: string[];
+}
+/**
+ * Fabricate a value that structurally satisfies a JSON Schema — the dry run's stand-in
+ * for a real agent's structured output. Deterministic and intentionally simple: first
+ * enum/anyOf variant, `true` booleans (so ok-gates terminate), `mock-<field>` strings.
+ */
+export declare function fabricateFromSchema(schema: unknown, hint?: string, depth?: number): unknown;
+/** Tokens the mock runner reports per agent call, so `--token-budget` exercises
+ *  budget-guarded script paths deterministically. */
+export declare const MOCK_TOKENS_PER_AGENT = 1000;
+/**
+ * Validate a workflow script: parse it, then (by default) dry-run it against a mock
+ * AgentRunner. Never throws for an invalid script — read `report.ok` / `report.exitCode`.
+ */
+export declare function validateWorkflowScript(script: string, options?: ValidateWorkflowOptions): Promise<ValidateWorkflowReport>;
+/** Render a ValidateWorkflowReport as the human-readable CLI output. */
+export declare function formatValidateReport(report: ValidateWorkflowReport): string;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,KAAK,EAA2B,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAExF,MAAM,WAAW,uBAAuB;IACtC,iEAAiE;IACjE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;2FACuF;IACvF,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,WAAW,CAAC;IAC5C;6EACyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;8CAC0C;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,kFAAkF;AAClF,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;6FACyF;IACzF,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,8EAA8E;IAC9E,EAAE,EAAE,OAAO,CAAC;IACZ,gEAAgE;IAChE,QAAQ,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpB,KAAK,EAAE;QACL,EAAE,EAAE,OAAO,CAAC;QACZ,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,YAAY,CAAC;KACrB,CAAC;IACF,MAAM,CAAC,EAAE;QACP,EAAE,EAAE,OAAO,CAAC;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,0EAA0E;QAC1E,QAAQ,EAAE,OAAO,CAAC;QAClB,UAAU,EAAE,kBAAkB,EAAE,CAAC;QACjC,WAAW,EAAE,mBAAmB,EAAE,CAAC;QACnC,aAAa,EAAE,MAAM,EAAE,CAAC;QACxB,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,yEAAyE;QACzE,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,CAAC;IACF,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,SAAU,EAAE,KAAK,SAAI,GAAG,OAAO,CA2DvF;AAcD;qDACqD;AACrD,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAqB1C;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,sBAAsB,CAAC,CAwLjC;AAMD,wEAAwE;AACxE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,CAgC3E"}

package/dist/validate.js

@@ -0,0 +1,326 @@
+// Token-free validation for workflow scripts: a static parse (meta literal, syntax,
+// determinism blocklist) followed by an optional DRY RUN — the script executes for real
+// in the engine's deterministic realm, but every agent() call is served by an in-process
+// mock AgentRunner that fabricates schema-conforming results. No ACP process is spawned,
+// no tokens are spent, checkpoints resolve to their headless defaults, and run state is
+// journaled nowhere (journaling off + a throwaway persistence root for the run lease).
+//
+// This is the programmatic core behind `agentprism-workflows validate` (see ./cli.ts).
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { openWorkflowDir, WorkflowManager, parseWorkflowScript } from "@automatalabs/workflow-engine";
+import { resolveBackendRegistry, selectBackend } from "@automatalabs/acp-agents";
+/**
+ * Fabricate a value that structurally satisfies a JSON Schema — the dry run's stand-in
+ * for a real agent's structured output. Deterministic and intentionally simple: first
+ * enum/anyOf variant, `true` booleans (so ok-gates terminate), `mock-<field>` strings.
+ */
+export function fabricateFromSchema(schema, hint = "value", depth = 0) {
+    if (depth > 16)
+        return null;
+    if (!schema || typeof schema !== "object")
+        return `mock-${hint}`;
+    const s = schema;
+    if (s.const !== undefined)
+        return s.const;
+    if (Array.isArray(s.enum) && s.enum.length > 0)
+        return s.enum[0];
+    if (s.default !== undefined)
+        return s.default;
+    const variants = s.anyOf ?? s.oneOf ?? s.allOf;
+    if (Array.isArray(variants) && variants.length > 0)
+        return fabricateFromSchema(variants[0], hint, depth + 1);
+    let type = s.type;
+    if (Array.isArray(type))
+        type = type[0];
+    if (type === undefined) {
+        if (s.properties)
+            type = "object";
+        else if (s.items)
+            type = "array";
+        else
+            return `mock-${hint}`;
+    }
+    switch (type) {
+        case "object": {
+            const out = {};
+            const props = (s.properties ?? {});
+            for (const [name, sub] of Object.entries(props))
+                out[name] = fabricateFromSchema(sub, name, depth + 1);
+            for (const name of Array.isArray(s.required) ? s.required : []) {
+                if (!(name in out))
+                    out[name] = `mock-${name}`;
+            }
+            return out;
+        }
+        case "array": {
+            const min = typeof s.minItems === "number" ? s.minItems : 1;
+            const count = Math.min(Math.max(min, 1), 3);
+            return Array.from({ length: count }, (_x, i) => fabricateFromSchema(s.items, `${hint}-${i + 1}`, depth + 1));
+        }
+        case "string": {
+            if (s.format === "uri" || s.format === "url")
+                return "https://example.invalid/mock";
+            if (s.format === "date-time")
+                return "2024-01-01T00:00:00Z";
+            if (s.format === "date")
+                return "2024-01-01";
+            let value = `mock-${hint}`;
+            if (typeof s.minLength === "number" && value.length < s.minLength) {
+                value = value.padEnd(s.minLength, "x");
+            }
+            if (typeof s.maxLength === "number" && value.length > s.maxLength) {
+                value = value.slice(0, s.maxLength);
+            }
+            return value;
+        }
+        case "integer":
+        case "number": {
+            if (typeof s.minimum === "number")
+                return s.minimum;
+            if (typeof s.maximum === "number" && s.maximum < 1)
+                return s.maximum;
+            return 1;
+        }
+        case "boolean":
+            return true;
+        case "null":
+            return null;
+        default:
+            return `mock-${hint}`;
+    }
+}
+/** Tokens the mock runner reports per agent call, so `--token-budget` exercises
+ *  budget-guarded script paths deterministically. */
+export const MOCK_TOKENS_PER_AGENT = 1000;
+function attributeBackend(model, tier, declared) {
+    const spec = model ?? tier;
+    if (!spec)
+        return "default";
+    const head = spec.split("/")[0].replace(/\[[^\]]*\]\s*$/, "").trim().toLowerCase();
+    if (declared && Object.keys(declared).some((name) => name.toLowerCase() === head)) {
+        return `${head} (script-declared)`;
+    }
+    try {
+        const registry = resolveBackendRegistry(declared);
+        return selectBackend({ model, tier }, registry).id;
+    }
+    catch {
+        return "default";
+    }
+}
+/**
+ * Validate a workflow script: parse it, then (by default) dry-run it against a mock
+ * AgentRunner. Never throws for an invalid script — read `report.ok` / `report.exitCode`.
+ */
+export async function validateWorkflowScript(script, options = {}) {
+    const warnings = [];
+    let meta;
+    try {
+        meta = parseWorkflowScript(script).meta;
+    }
+    catch (error) {
+        return {
+            ok: false,
+            exitCode: 1,
+            parse: { ok: false, error: error instanceof Error ? error.message : String(error) },
+            warnings,
+        };
+    }
+    const declaredBackends = meta.backends && Object.keys(meta.backends).length > 0 ? meta.backends : undefined;
+    if (declaredBackends) {
+        warnings.push(`script declares custom backends (${Object.keys(declaredBackends).join(", ")}) — real runs must approve them ` +
+            `(allowScriptBackends / exec.scriptBackends / AGENTPRISM_ALLOW_SCRIPT_BACKENDS=1); the dry run treats them as approved`);
+    }
+    if (options.dryRun === false) {
+        return { ok: true, exitCode: 0, parse: { ok: true, meta }, warnings };
+    }
+    // Throwaway directories: the run cwd (unless the caller pins one) so worktree isolation
+    // no-ops, and a private persistence root so the run lease never touches the real store.
+    const ownedCwd = options.cwd === undefined;
+    const baseCwd = options.cwd ?? mkdtempSync(join(tmpdir(), "agentprism-validate-"));
+    const persistenceRoot = mkdtempSync(join(tmpdir(), "agentprism-validate-state-"));
+    const mockMeta = new Map();
+    const runner = {
+        async run(_prompt, runOptions = {}) {
+            const label = runOptions.label ?? "";
+            mockMeta.set(label, {
+                tier: runOptions.tier,
+                mode: runOptions.mode,
+                schema: runOptions.schema !== undefined,
+            });
+            runOptions.onUsage?.({
+                input: MOCK_TOKENS_PER_AGENT - 250,
+                output: 250,
+                cacheRead: 0,
+                cacheWrite: 0,
+                total: MOCK_TOKENS_PER_AGENT,
+                cost: 0,
+            });
+            if (runOptions.schema !== undefined)
+                return fabricateFromSchema(runOptions.schema);
+            return `[dry-run] mock output for ${runOptions.label ?? "agent"}`;
+        },
+    };
+    const agentCalls = [];
+    const checkpoints = [];
+    const controller = new AbortController();
+    let timedOut = false;
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, timeoutMs);
+    timer.unref?.();
+    const flows = options.workflows === undefined
+        ? undefined
+        : typeof options.workflows === "string" || Array.isArray(options.workflows)
+            ? openWorkflowDir(options.workflows)
+            : options.workflows;
+    const manager = new WorkflowManager({
+        agent: runner,
+        cwd: baseCwd,
+        journaling: false,
+        persistenceRoot,
+        loadSavedWorkflow: flows?.resolve,
+    });
+    manager.on("agentStart", (event) => {
+        const extra = mockMeta.get(event.label) ?? mockMeta.get("") ?? { schema: false };
+        agentCalls.push({
+            label: event.label,
+            phase: event.phase,
+            model: event.model,
+            tier: extra.tier,
+            mode: extra.mode,
+            backend: attributeBackend(event.model, extra.tier, declaredBackends),
+            schema: extra.schema,
+        });
+    });
+    try {
+        const run = await manager.runSync(script, options.args, {
+            journaling: false,
+            signal: controller.signal,
+            tokenBudget: options.tokenBudget,
+            maxAgents: options.maxAgents,
+            scriptBackends: declaredBackends,
+            confirm: async (promptText, checkpointOptions) => {
+                const opts = (checkpointOptions ?? {});
+                if (opts.headless === "abort") {
+                    warnings.push(`checkpoint "${truncate(promptText, 60)}" sets headless: "abort" — unattended runs will fail at it`);
+                }
+                // Mirror the engine's headless resolution exactly: the declared default, else true.
+                const reply = opts.default ?? true;
+                checkpoints.push({ prompt: promptText, kind: opts.kind ?? "confirm", reply });
+                return reply;
+            },
+        });
+        // agentStart fires BEFORE the mock records its options, so backfill attribution for
+        // any call whose mock metadata arrived after the event (same tick ordering).
+        for (const call of agentCalls) {
+            const extra = mockMeta.get(call.label);
+            if (extra) {
+                call.tier = extra.tier;
+                call.mode = extra.mode;
+                call.schema = extra.schema;
+                call.backend = attributeBackend(call.model, extra.tier, declaredBackends);
+            }
+        }
+        const ok = run.status === "completed";
+        if (!ok && flows === undefined && run.reason?.includes("must be the first statement") && /\bworkflow\s*\(/.test(script)) {
+            warnings.push('the failure looks like a nested workflow("<name>") call on a bare name — provide workflow dirs ' +
+                "(ValidateWorkflowOptions.workflows / --workflows-dir) so names resolve during the dry run");
+        }
+        if (ok) {
+            if (agentCalls.length === 0 && checkpoints.length === 0) {
+                warnings.push("the script completed without a single agent() or checkpoint() call");
+            }
+            const declaredPhases = (meta.phases ?? []).map((p) => p.title);
+            // A phase counts as used via phase() OR via a per-call agent({ phase }) assignment.
+            const visited = new Set([...(run.phases ?? []), ...agentCalls.flatMap((c) => (c.phase ? [c.phase] : []))]);
+            for (const title of declaredPhases) {
+                if (!visited.has(title))
+                    warnings.push(`meta.phases declares "${title}" but no phase("${title}") or agent({ phase }) used it`);
+            }
+            if (declaredPhases.length > 0) {
+                for (const title of visited) {
+                    if (!declaredPhases.includes(title))
+                        warnings.push(`phase "${title}" is used but meta.phases does not declare it`);
+                }
+            }
+        }
+        return {
+            ok,
+            exitCode: ok ? 0 : 2,
+            parse: { ok: true, meta },
+            dryRun: {
+                ok,
+                status: run.status,
+                reason: timedOut ? `dry run exceeded ${timeoutMs}ms and was aborted` : run.reason,
+                timedOut,
+                agentCalls,
+                checkpoints,
+                phasesVisited: run.phases ?? [],
+                logs: run.logs ?? [],
+                durationMs: run.durationMs,
+                result: run.result,
+            },
+            warnings,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+        try {
+            rmSync(persistenceRoot, { recursive: true, force: true });
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+        if (ownedCwd) {
+            try {
+                rmSync(baseCwd, { recursive: true, force: true });
+            }
+            catch {
+                /* best-effort cleanup */
+            }
+        }
+    }
+}
+function truncate(text, max) {
+    return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+/** Render a ValidateWorkflowReport as the human-readable CLI output. */
+export function formatValidateReport(report) {
+    const lines = [];
+    if (report.parse.ok) {
+        const meta = report.parse.meta;
+        const phases = meta?.phases?.length ? `${meta.phases.length} declared phase(s)` : "no declared phases";
+        const backends = meta?.backends ? `, ${Object.keys(meta.backends).length} script-declared backend(s)` : "";
+        lines.push(`✓ parse     "${meta?.name}" — ${phases}${backends}`);
+    }
+    else {
+        lines.push(`✗ parse     ${report.parse.error}`);
+    }
+    const dry = report.dryRun;
+    if (dry) {
+        const summary = `${dry.agentCalls.length} agent call(s), ${dry.checkpoints.length} checkpoint(s), ${dry.durationMs}ms`;
+        lines.push(dry.ok ? `✓ dry run   completed — ${summary}` : `✗ dry run   ${dry.status} — ${dry.reason ?? "unknown failure"} (${summary})`);
+        for (const call of dry.agentCalls) {
+            const spec = call.model ?? (call.tier ? `tier=${call.tier}` : "(default model)");
+            const bits = [call.phase ? `[${call.phase}]` : undefined, spec, `→ ${call.backend}`, call.schema ? "(schema)" : undefined, call.mode ? `mode=${call.mode}` : undefined]
+                .filter(Boolean)
+                .join("  ");
+            lines.push(`    • ${call.label}  ${bits}`);
+        }
+        for (const cp of dry.checkpoints) {
+            lines.push(`    ◆ checkpoint [${cp.kind}] "${truncate(cp.prompt, 60)}" → ${JSON.stringify(cp.reply)}`);
+        }
+    }
+    else if (report.parse.ok) {
+        lines.push("- dry run   skipped (--parse-only)");
+    }
+    for (const warning of report.warnings)
+        lines.push(`  ! ${warning}`);
+    lines.push(report.ok ? "result: valid" : "result: INVALID");
+    return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automatalabs/workflows",
-  "version": "0.20.2",
+  "version": "0.21.0",
   "license": "Apache-2.0",
   "engines": {
     "node": ">=22"
@@ -13,6 +13,9 @@
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "agentprism-workflows": "./dist/cli.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -27,9 +30,9 @@
     "access": "public"
   },
   "dependencies": {
+    "@automatalabs/workflow-engine": "0.10.0",
     "@automatalabs/shared-types": "0.12.1",
-    "@automatalabs/workflow-engine": "0.9.1",
-    "@automatalabs/acp-agents": "0.20.2"
+    "@automatalabs/acp-agents": "0.20.4"
   },
   "scripts": {
     "build": "tsc -b",