@automatalabs/workflows 0.41.0 → 0.43.0

package/README.md

@@ -11,14 +11,15 @@ or a registered custom ACP agent — driving the actual 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.
+Its CLI can also delegate to a build-time embedded copy of that server with the `mcp` subcommand,
+so an MCP host can expose the `workflow` tool without a separate package install. The standalone
+MCP server package remains independently published, while programs embedding the runner continue
+to use this package's workflow/runner APIs.
 
-It is a **programmatic library**, not an MCP stdio server. It is a thin facade over the engine +
-ACP packages and adds ACP-defaulted helpers for ordinary runs (`runDynamicWorkflow`) and
-substitution tests (`runIsolation`). The ACP layer does use `@modelcontextprotocol/sdk` internally
-when it hosts the optional StructuredOutput tool for eligible agents; consumers still interact
-through this SDK's workflow/runner APIs rather than MCP server schemas.
+The SDK itself remains a thin programmatic facade over the engine + ACP packages, with
+ACP-defaulted helpers for ordinary runs (`runDynamicWorkflow`) and substitution tests
+(`runIsolation`). The ACP layer also uses `@modelcontextprotocol/sdk` internally when it hosts the
+optional StructuredOutput tool for eligible agents.
 
 ---
 
@@ -117,21 +118,21 @@ Every script **must** begin with `export const meta = { name, description, phase
 statement, and must be **deterministic** — `Date.now()`, `Math.random()`, and `new Date()` are
 unavailable inside the realm (they would break journal replay on resume).
 
-Replay-safe read-only/worktree fan-out is explicit:
+Completed reader/worktree calls both use ordinary journal replay:
 
 ```js
 const [audit, experiment] = await parallel([
   () => agent("Audit src/api without changing files.", {
-    label: "audit:api", resume: { filesystem: "read-only" },
+    label: "audit:api",
   }),
   () => agent("Try the worker fix in isolation; return a unified diff.", {
-    label: "try:worker", isolation: "worktree", resume: { filesystem: "read-only" },
+    label: "try:worker", isolation: "worktree",
   }),
 ]);
 ```
 
-The worktree and edits are discarded; return the diff as data. The declaration is required for
-content-addressed reuse in both arms—worktree isolation alone is not a safety proof. See the
+The worktree and edits are discarded; return the diff as data. Replay requires matching journal
+identity/input facts, not a filesystem-safety declaration. See the
 [incremental resume API](../../docs/api.md#content-addressed-incremental-resume).
 
 ### Substitution testing (isolation mode)
@@ -303,7 +304,7 @@ boolean).
 
 Resume guarantees journal/script replay integrity and checkpoint-reply targeting only. It never
 assumes or guarantees that the filesystem, external systems, agent output semantics, or any other
-part of the world stayed fresh between runs. If an unsafe prefix must run live, a supplied reply is
+part of the world stayed fresh between runs. If a prior correspondence miss runs live, a supplied reply is
 injected only when execution reaches the exact recorded checkpoint call site with the same
 checkpoint identity and inputs; content-only matching is insufficient after that live prefix. A
 reply that is not applied is reported in `resumeReport` and terminal summaries. Authors who want a
@@ -352,15 +353,15 @@ Run results expose `effectiveLimits`; inspect status exposes the same values as
 agent rows carry their resolved `timeoutMs` plus `errorCode`.
 
 `exec.resumeFromRunId` asks the manager to admit a terminal source, persist a self-contained seed
-under a new run ID, and match safe calls by exact path/hash or unique hash+input fingerprint.
+under a new run ID, and match completed calls by exact path/hash or unique hash+input fingerprint.
 Every allocated call receives a terminal manifest row even when the run halts around it. A
 non-result occurrence remains live on resume and stays in the identity seed as an ambiguity
-blocker until reached, so completed siblings on either side can replay safely. Uncertain,
-ambiguous, or unsafe calls run live. Current-environment and Node/V8 differences are
+blocker until reached, so completed siblings on either side can replay. Uncertain,
+ambiguous, or mismatched calls run live. Filesystem/current-environment and Node/V8 differences are
 reported as provenance without changing admission or matching. Identity hits preserve
 script-visible logical budget debit while adding zero current provider usage; replayed session
 records are rebound to the current call index/label/phase. `resumePolicy: "positional"` requests
-index/prefix matching but cannot bypass new-format format/metadata/manifest/input/safety checks. The distinct
+index/prefix matching but cannot bypass new-format format/metadata/manifest/input checks. The distinct
 same-ID `resume()` and low-level `resumeJournal` paths remain permanently legacy positional and
 emit no `resumeReport`. See the [full contract](../../docs/api.md#content-addressed-incremental-resume).
 Operational limits are resolved from the new execution's `exec` options and manager defaults, not
@@ -369,9 +370,8 @@ copied from the source run; pass the desired timeout/retry/concurrency values ag
 neither replay identity nor the execution-input fingerprint and may change without invalidating
 completed calls or interrupted-turn continuation.
 
-Crash snapshots reconciled to `paused` / `interrupted` without a terminal environment use the
-`crash-residue` positional bridge with legacy hash-stable prefix eligibility. Normally settled
-sources with an input-fingerprint format below 2 use the
+Current-format crash snapshots reconciled to `paused` / `interrupted` use identity correspondence
+even without terminal-environment capture. Sources with an input-fingerprint format below 2 use the
 `inputs-format-legacy` positional bridge. That bridge also accepts ancestor-scoped rows carried by a
 ≤0.23 resume hop when the ancestor run still exists in the same persistence directory; nested and deleted-run scopes stay live. Engine
 package versions are persisted and surfaced as diagnostics but never gate replay. Every new-run
@@ -544,7 +544,7 @@ Semantics worth knowing:
   is always treated as a verbatim script, never a name.
 - **Versioning is git's job.** Same-ID `resume()` reloads the exact persisted script. A new
   `resumeFromRunId` execution can use an edited script: changed calls run live, while uniquely
-  matching safety-marked calls may move and replay after admission.
+  matching completed calls may move and replay after admission.
 - **`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.
 
@@ -621,7 +621,7 @@ 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`). `options.resume: { filesystem: "read-only" }` is the author safety declaration for content-addressed replay. |
+| `agent(prompt, options?)` | Run ONE subagent to completion; returns its result (text, or the validated object with `options.schema`). The legacy `options.resume` annotation is accepted but replay-neutral. |
 | `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. |
@@ -779,6 +779,36 @@ formatHarnessConfigReport(report); // the CLI's human table
 
 ---
 
+## Launching the MCP server — `agentprism-workflows mcp`
+
+Register the bundled stdio server directly from the workflows package; no separate
+`@automatalabs/mcp-server` installation is required:
+
+```json
+{
+  "mcpServers": {
+    "agentprism-workflow": {
+      "command": "npx",
+      "args": ["-y", "@automatalabs/workflows", "mcp"]
+    }
+  }
+}
+```
+
+For the source inner loop, build workflows before launching its compiled CLI:
+
+```bash
+pnpm --filter @automatalabs/workflows build
+node packages/workflows/dist/cli.js mcp
+```
+
+If the embedded bundle is absent in a monorepo checkout, the command falls back to the built
+`packages/mcp-server/dist/cli.js`. A root `pnpm build` therefore also supports development before
+running `node packages/workflows/dist/cli.js mcp`. The independently published
+`@automatalabs/mcp-server` package and `agentprism-workflow` bin remain available.
+
+---
+
 ## Structured output
 
 Pass a JSON Schema to `agent({ schema })` (in a script) or `runner.run(prompt, { schema })` (direct)

package/dist/cli.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
-// The @automatalabs/workflows bin (`agentprism-workflows`). Two subcommands:
+// The @automatalabs/workflows bin (`agentprism-workflows`). Three subcommands:
 //
 //   agentprism-workflows validate <workflow-file> [options]
 //   agentprism-workflows config [harness ...] [options]
+//   agentprism-workflows mcp
 //
 // validate checks a workflow script without spending tokens: static parse (meta literal,
 // syntax, direct nondeterministic call expressions), then a dry run over an in-process
@@ -13,7 +14,12 @@
 // config runs that same no-prompt probe standalone — no script needed — and prints each
 // requested harness's advertised config-option catalog (model ids, effort levels, modes,
 // …). See ./config.ts for the programmatic API (`probeHarnessConfig`).
+//
+// mcp delegates stdio unchanged to the MCP server embedded at build time. In a source
+// checkout without that bundle, it falls back to the separately built mcp-server entry.
+import { spawn } from "node:child_process";
 import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { constants as osConstants } from "node:os";
 import { resolve } from "node:path";
 import { openWorkflowDir } from "@automatalabs/workflow-engine";
 import { validateWorkflowScript, formatValidateReport } from "./validate.js";
@@ -27,6 +33,7 @@ Commands:
                                     catalog (model ids, effort levels, modes, …) so
                                     model/configOptions values come from the live
                                     catalog, not guesswork
+  mcp                               launch the embedded AgentPrism stdio MCP server
 
 Run \`agentprism-workflows <command> --help\` for that command's options.`;
 const USAGE = `Usage: agentprism-workflows validate <workflow-file-or-name> [options]
@@ -90,6 +97,13 @@ Options:
   -h, --help          show this help
 
 Exit codes: 0 all probed · 1 at least one probe failed · 3 usage error`;
+const MCP_USAGE = `Usage: agentprism-workflows mcp
+
+Launches the embedded AgentPrism MCP server over stdio. stdin and stdout are reserved
+for JSON-RPC framing and are inherited unchanged by the server process.
+
+Options:
+  -h, --help          show this help`;
 let activeCommand = "";
 function fail(message) {
     const hint = activeCommand === "" ? "agentprism-workflows --help" : `agentprism-workflows ${activeCommand} --help`;
@@ -143,6 +157,86 @@ async function mainConfig(rest) {
     writeFileSync(process.stdout.fd, json ? `${JSON.stringify(report, null, 2)}\n` : `${formatHarnessConfigReport(report)}\n`);
     process.exitCode = report.exitCode;
 }
+async function mainMcp(rest) {
+    if (rest.length === 1 && (rest[0] === "-h" || rest[0] === "--help")) {
+        process.stdout.write(`${MCP_USAGE}\n`);
+        process.exit(0);
+    }
+    if (rest.length > 0)
+        fail(`mcp does not accept arguments (received: ${rest.join(" ")})`);
+    const bundlePath = resolve(import.meta.dirname, "mcp-server.js");
+    const monorepoFallbackPath = resolve(import.meta.dirname, "../../mcp-server/dist/cli.js");
+    const serverPath = existsSync(bundlePath)
+        ? bundlePath
+        : existsSync(monorepoFallbackPath)
+            ? monorepoFallbackPath
+            : undefined;
+    if (serverPath === undefined) {
+        fail(`MCP server bundle not found at ${bundlePath}, and the monorepo fallback is not built. ` +
+            "Run `pnpm --filter @automatalabs/workflows build` to create the bundle, or run `pnpm build` at the repository root.");
+    }
+    await new Promise((resolvePromise) => {
+        const child = spawn(process.execPath, [serverPath], { stdio: "inherit" });
+        const forwardedSignals = ["SIGINT", "SIGTERM"];
+        let settled = false;
+        let cleaned = false;
+        const forwarders = new Map();
+        const cleanup = () => {
+            if (cleaned)
+                return;
+            cleaned = true;
+            for (const [signal, forward] of forwarders)
+                process.off(signal, forward);
+            child.off("error", onError);
+            child.off("exit", onExit);
+        };
+        const finish = (action) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            action();
+            resolvePromise();
+        };
+        const onError = (error) => {
+            finish(() => {
+                process.stderr.write(`mcp server failed to start: ${error.message}\n`);
+                process.exitCode = 1;
+            });
+        };
+        const onExit = (code, signal) => {
+            finish(() => {
+                if (signal === null) {
+                    process.exitCode = code ?? 1;
+                    return;
+                }
+                // Preserve signal termination for callers (shells, npx, and MCP hosts). Set a
+                // conventional nonzero fallback first in case re-raising is unsupported here.
+                process.exitCode = 128 + (osConstants.signals[signal] ?? 1);
+                try {
+                    process.kill(process.pid, signal);
+                }
+                catch (error) {
+                    process.stderr.write(`mcp server exited on ${signal}, but the parent could not re-raise it: ${error instanceof Error ? error.message : String(error)}\n`);
+                }
+            });
+        };
+        for (const signal of forwardedSignals) {
+            const forward = () => {
+                try {
+                    child.kill(signal);
+                }
+                catch (error) {
+                    process.stderr.write(`could not forward ${signal} to the mcp server: ${error instanceof Error ? error.message : String(error)}\n`);
+                }
+            };
+            forwarders.set(signal, forward);
+            process.on(signal, forward);
+        }
+        child.once("error", onError);
+        child.once("exit", onExit);
+    });
+}
 async function main(argv) {
     const [command, ...rest] = argv;
     if (command === undefined || command === "-h" || command === "--help") {
@@ -153,8 +247,12 @@ async function main(argv) {
         activeCommand = "config";
         return mainConfig(rest);
     }
+    if (command === "mcp") {
+        activeCommand = "mcp";
+        return mainMcp(rest);
+    }
     if (command !== "validate")
-        fail(`unknown command "${command}" — the commands are: validate, config`);
+        fail(`unknown command "${command}" — the commands are: validate, config, mcp`);
     activeCommand = "validate";
     let file;
     let json = false;