@automatalabs/workflows 0.30.1 → 0.31.0

package/README.md

@@ -15,10 +15,10 @@ If you want to expose a `workflow` tool to an MCP host (Claude Code, Zed, …),
 you want to embed the runner in your own program, use this one.
 
 It is a **programmatic library**, not an MCP stdio server. It is a thin facade over the engine +
-ACP packages and adds one convenience helper, `runDynamicWorkflow`, which defaults the agent
-backend to ACP. 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.
+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.
 
 ---
 
@@ -116,6 +116,27 @@ 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).
 
+### Substitution testing (isolation mode)
+
+Record a normal managed run, then re-run its recorded script with one selected step live while all
+other calls are served from the recording:
+
+```ts
+import { runIsolation } from "@automatalabs/workflows";
+
+const isolated = await runIsolation({
+  baselineRunId: recorded.runId,
+  live: [{ label: "step-2", model: "codex/gpt-5.3-codex" }],
+});
+
+const target = isolated.report.calls.find((call) => call.mode === "live-target");
+console.log(isolated.status, target?.recordedUsage, target?.liveUsage);
+```
+
+The SDK defaults the live runner to ACP and disposes it; pass `runner` to inject and retain your own.
+See the [Isolation mode API](../../docs/api.md#isolation-mode) for baseline admissibility, target
+selection, typed refusals, report semantics, and the lower-level `createReplayRunner` composition.
+
 ### b) `createAcpRunner().run(...)` — drive a single agent
 
 Skip the script realm entirely and call one agent directly. The runner is the default ACP
@@ -612,6 +633,8 @@ size is `AGENTPRISM_ACP_POOL_SIZE` (or `AcpPoolOptions.size`).
 ```ts
 // ── Run entry & helper ──
 runDynamicWorkflow,           // (script, { args?, runner?, exec? }) => Promise<WorkflowRunResult>
+runIsolation,                 // ACP-defaulted single-target substitution over a recorded run
+createReplayRunner,           // backend-neutral in-memory replay composition primitive
 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)
@@ -639,7 +662,10 @@ WorkflowError, WorkflowErrorCode, isWorkflowError, isProviderUsageLimit, isAuthR
 AGENTPRISM_PERSISTENCE_ROOT_ENV,
 
 // ── Types ──
-RunDynamicWorkflowOptions, WorkflowRunOptions, AgentOptions, ExecOptions,
+RunDynamicWorkflowOptions, RunIsolationSdkOptions, RunIsolationOptions, IsolationRunResult,
+IsolationTarget, ReplayRunnerOptions, ReplayRunner, ReplayObservation, ReplayReport,
+ReplayCallReport, ReplayDivergenceEvent, ResolvedIsolationTarget,
+WorkflowRunOptions, AgentOptions, ExecOptions, CheckpointCallContext,
 MockAnswerJson, MockAnswerSequence, MockAnswerRule, MockAnswers,
 ValidatedMockAnswerUse, ValidatedMockAnswerRule, UnusedMockAnswer, ValidatedMockAnswers,
 ValidateWorkflowOptions, ValidateWorkflowReport, ValidatedAgentCall, ValidatedCheckpoint,
@@ -647,7 +673,7 @@ WorkflowManagerOptions, CheckpointOptions, WorkflowRunResult, WorkflowRunFallbac
 WorkflowCheckpointTaken, WorkflowCheckpointSource, WorkflowSnapshot,
 WorkflowPathOptions, RunPersistence, RunPersistenceOptions,
 AcpPoolOptions, AcpRunnerOptions, AgentRunner, RunOptions, AgentResult, AgentUsage, JournalEntry,
-AgentSessionRef, AgentSessionRecord, WorkflowBackendConfig,
+AgentSessionRef, AgentSessionRecord, WorkflowBackendConfig, WorkflowCallRecord, WorkflowRecordedError,
 InteractiveSessionOptions, InteractiveTurn, PermissionResolver,
 AuthResolver, AuthContext, AuthResolution, AuthMethodDescriptor, AuthCapableRunner,
 ProviderCapableRunner,        // duck-type gate for the MCP provider tools (providers/list|set|disable)

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, WorkflowDir, WorkflowManagerOptions } from "@automatalabs/workflow-engine";
-import type { AgentRunner, WorkflowBackendConfig, WorkflowRunResult } from "@automatalabs/shared-types";
+import type { AgentRunner, WorkflowRunResult } from "@automatalabs/shared-types";
+import { type ScriptBackendApproval } from "./script-backends.js";
 export { runWorkflow, parseWorkflowScript, redactText, truncateUtf8 } from "@automatalabs/workflow-engine";
+export { runIsolation, createReplayRunner, type RunIsolationSdkOptions } from "./isolation.js";
+export type { RunIsolationOptions, IsolationRunResult, ReplayRunnerOptions, ResolvedIsolationTarget, IsolationTarget, ReplayRunner, ReplayObservation, ReplayReport, ReplayCallReport, ReplayDivergenceEvent, CheckpointCallContext, WorkflowCallRecord, WorkflowRecordedError, } from "./isolation.js";
 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 { MockAnswerJson, MockAnswerRule, MockAnswers, MockAnswerSequence, UnusedMockAnswer, ValidateWorkflowOptions, ValidateWorkflowReport, ValidatedAgentCall, ValidatedCheckpoint, ValidatedMockAnswerRule, ValidatedMockAnswers, ValidatedMockAnswerUse, } from "./validate.js";
@@ -78,9 +81,7 @@ export declare class WorkflowManager extends EngineWorkflowManager {
  * runDynamicWorkflow THROWS with guidance rather than running a script whose declared
  * dependencies were dropped.
  */
-export type ScriptBackendApproval = boolean | ((backend: {
-    name: string;
-} & WorkflowBackendConfig) => boolean | Promise<boolean>);
+export type { ScriptBackendApproval } from "./script-backends.js";
 /** 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":"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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

@@ -2,18 +2,22 @@
 // @automatalabs/workflows — the importable SDK for the AgentPrism dynamic-workflow
 // orchestrator. A FACADE re-export barrel: it re-exports the clean public surface of
 // the three engine packages, adds the SDK-level WorkflowManager ACP-event bridge, and
-// adds ONE convenience helper (`runDynamicWorkflow`) that defaults the AgentRunner seam
-// to the ACP backend. It is SEPARATE from @automatalabs/mcp-server (the stdio MCP server)
+// adds ACP-defaulted convenience helpers for ordinary and isolation runs. It is
+// SEPARATE from @automatalabs/mcp-server (the stdio MCP server)
 // and stays a PURE library — it pulls in neither @modelcontextprotocol/sdk nor zod.
 //
 // The DSL globals available INSIDE a workflow script (agent, parallel, pipeline, …) are
 // 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 { openWorkflowDir, parseWorkflowScript, WorkflowError, WorkflowErrorCode, WorkflowManager as EngineWorkflowManager, } from "@automatalabs/workflow-engine";
+import { openWorkflowDir, parseWorkflowScript, WorkflowManager as EngineWorkflowManager, } from "@automatalabs/workflow-engine";
+import { approveScriptBackends } from "./script-backends.js";
 // ── Engine: run entry, script parsing, the managed-run lifecycle, and the
 //    option/result + error types the host composes against. ──
 export { runWorkflow, parseWorkflowScript, redactText, truncateUtf8 } from "@automatalabs/workflow-engine";
+// ── Isolation mode: deterministic substitution testing over a recorded run. The SDK
+//    wrapper defaults the live target runner to ACP and owns that runner's disposal. ──
+export { runIsolation, createReplayRunner } from "./isolation.js";
 // ── 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
@@ -200,7 +204,10 @@ export async function runDynamicWorkflow(script, opts = {}) {
     }
     let exec = opts.exec;
     if (declared && Object.keys(declared).length > 0) {
-        exec = { ...(exec ?? {}), scriptBackends: await approveScriptBackends(declared, opts.allowScriptBackends) };
+        exec = {
+            ...(exec ?? {}),
+            scriptBackends: await approveScriptBackends(declared, opts.allowScriptBackends, "runDynamicWorkflow"),
+        };
     }
     const owned = opts.runner === undefined;
     const runner = opts.runner ?? createAcpRunner();
@@ -214,22 +221,3 @@ export async function runDynamicWorkflow(script, opts = {}) {
             await runner.dispose();
     }
 }
-/** Resolve the embedder's approval policy over the declared backends; throw with guidance when
- *  approval is missing or any backend is declined (an unapproved dependency must abort, never
- *  silently reroute). */
-async function approveScriptBackends(declared, approval) {
-    const names = Object.keys(declared).join(", ");
-    if (approval === undefined || approval === false) {
-        throw new WorkflowError(`script declares custom ACP backends (meta.backends: ${names}) — these spawn commands on this machine and require explicit approval. ` +
-            `Pass allowScriptBackends: true (or a per-backend approval callback) to runDynamicWorkflow, ` +
-            `or thread an approved registry yourself via exec.scriptBackends.`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false });
-    }
-    if (approval === true)
-        return declared;
-    for (const [name, config] of Object.entries(declared)) {
-        if (!(await approval({ name, ...config }))) {
-            throw new WorkflowError(`script backend "${name}" (command: ${config.command}) was declined by the allowScriptBackends callback — aborting the run`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false });
-        }
-    }
-    return declared;
-}

package/dist/isolation.d.ts

@@ -0,0 +1,24 @@
+import { createReplayRunner } from "@automatalabs/workflow-engine";
+import type { CheckpointCallContext, IsolationRunResult, IsolationTarget, ReplayCallReport, ReplayDivergenceEvent, ReplayObservation, ReplayReport, ReplayRunner, ReplayRunnerOptions, ResolvedIsolationTarget, RunIsolationOptions } from "@automatalabs/workflow-engine";
+import type { AgentRunner, WorkflowCallRecord, WorkflowRecordedError } from "@automatalabs/shared-types";
+import { type ScriptBackendApproval } from "./script-backends.js";
+type OwnedRunner = AgentRunner & {
+    dispose: () => Promise<void>;
+};
+type DefaultRunnerFactory = () => OwnedRunner;
+/** Test-only injection point for the owned default runner. Deliberately absent from the package barrel. */
+export declare function __setDefaultRunnerFactoryForTests(factory: DefaultRunnerFactory | undefined): void;
+export interface RunIsolationSdkOptions extends Omit<RunIsolationOptions, "runner" | "scriptBackends"> {
+    /** Omitted => createAcpRunner(), disposed after the run. */
+    runner?: AgentRunner;
+    /** Approval policy for the recording script's declared meta.backends. */
+    allowScriptBackends?: ScriptBackendApproval;
+}
+/**
+ * Execute an isolation run with the SDK's ACP-defaulted runner and script-backend
+ * approval policy. Caller-supplied runners remain caller-owned.
+ */
+export declare function runIsolation<T = unknown>(opts: RunIsolationSdkOptions): Promise<IsolationRunResult<T>>;
+export { createReplayRunner };
+export type { CheckpointCallContext, IsolationRunResult, IsolationTarget, ReplayCallReport, ReplayDivergenceEvent, ReplayObservation, ReplayReport, ReplayRunner, ReplayRunnerOptions, ResolvedIsolationTarget, RunIsolationOptions, WorkflowCallRecord, WorkflowRecordedError, };
+//# sourceMappingURL=isolation.d.ts.map

package/dist/isolation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isolation.d.ts","sourceRoot":"","sources":["../src/isolation.ts"],"names":[],"mappings":"AACA,OAAO,EACL,kBAAkB,EAMnB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EACV,qBAAqB,EACrB,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,EACpB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EACV,WAAW,EACX,kBAAkB,EAClB,qBAAqB,EACtB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAyB,KAAK,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAEzF,KAAK,WAAW,GAAG,WAAW,GAAG;IAAE,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC;AAClE,KAAK,oBAAoB,GAAG,MAAM,WAAW,CAAC;AAI9C,2GAA2G;AAC3G,wBAAgB,iCAAiC,CAAC,OAAO,EAAE,oBAAoB,GAAG,SAAS,GAAG,IAAI,CAEjG;AAED,MAAM,WAAW,sBACf,SAAQ,IAAI,CAAC,mBAAmB,EAAE,QAAQ,GAAG,gBAAgB,CAAC;IAC9D,4DAA4D;IAC5D,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,yEAAyE;IACzE,mBAAmB,CAAC,EAAE,qBAAqB,CAAC;CAC7C;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,CAAC,GAAG,OAAO,EAC5C,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CA0ChC;AAED,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAC9B,YAAY,EACV,qBAAqB,EACrB,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,GACtB,CAAC"}

package/dist/isolation.js

@@ -0,0 +1,54 @@
+import { createAcpRunner } from "@automatalabs/acp-agents";
+import { createReplayRunner, createRunPersistence, parseWorkflowScript, runIsolation as runEngineIsolation, WorkflowError, WorkflowErrorCode, } from "@automatalabs/workflow-engine";
+import { approveScriptBackends } from "./script-backends.js";
+let defaultRunnerFactory = createAcpRunner;
+/** Test-only injection point for the owned default runner. Deliberately absent from the package barrel. */
+export function __setDefaultRunnerFactoryForTests(factory) {
+    defaultRunnerFactory = factory ?? createAcpRunner;
+}
+/**
+ * Execute an isolation run with the SDK's ACP-defaulted runner and script-backend
+ * approval policy. Caller-supplied runners remain caller-owned.
+ */
+export async function runIsolation(opts) {
+    let recording;
+    try {
+        const persistence = createRunPersistence(opts.cwd ?? process.cwd(), undefined, {
+            persistenceRoot: opts.persistenceRoot,
+        });
+        recording = persistence.load(opts.baselineRunId);
+    }
+    catch (error) {
+        if (error instanceof WorkflowError)
+            throw error;
+        throw new WorkflowError(error instanceof Error ? error.message : String(error), WorkflowErrorCode.PERSISTENCE_ERROR, { recoverable: false });
+    }
+    let declared;
+    if (recording && typeof recording.script === "string") {
+        try {
+            declared = parseWorkflowScript(recording.script).meta.backends;
+        }
+        catch {
+            // The engine owns malformed-recording diagnosis and will reject it with its
+            // typed preflight error after reloading the same persisted bytes.
+        }
+    }
+    const scriptBackends = declared && Object.keys(declared).length > 0
+        ? await approveScriptBackends(declared, opts.allowScriptBackends, "runIsolation")
+        : undefined;
+    const owned = opts.runner === undefined;
+    const runner = opts.runner ?? defaultRunnerFactory();
+    try {
+        const { allowScriptBackends: _approval, ...engineOptions } = opts;
+        return await runEngineIsolation({
+            ...engineOptions,
+            runner,
+            ...(scriptBackends === undefined ? {} : { scriptBackends }),
+        });
+    }
+    finally {
+        if (owned)
+            await runner.dispose();
+    }
+}
+export { createReplayRunner };

package/dist/script-backends.d.ts

@@ -0,0 +1,7 @@
+import type { WorkflowBackendConfig } from "@automatalabs/shared-types";
+export type ScriptBackendApproval = boolean | ((backend: {
+    name: string;
+} & WorkflowBackendConfig) => boolean | Promise<boolean>);
+/** Resolve explicit host approval for script-declared command-spawning backends. */
+export declare function approveScriptBackends(declared: Record<string, WorkflowBackendConfig>, approval: ScriptBackendApproval | undefined, helperName: "runDynamicWorkflow" | "runIsolation"): Promise<Record<string, WorkflowBackendConfig>>;
+//# sourceMappingURL=script-backends.d.ts.map

package/dist/script-backends.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"script-backends.d.ts","sourceRoot":"","sources":["../src/script-backends.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAExE,MAAM,MAAM,qBAAqB,GAC7B,OAAO,GACP,CAAC,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,qBAAqB,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;AAExF,oFAAoF;AACpF,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,EAC/C,QAAQ,EAAE,qBAAqB,GAAG,SAAS,EAC3C,UAAU,EAAE,oBAAoB,GAAG,cAAc,GAChD,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAyBhD"}

package/dist/script-backends.js

@@ -0,0 +1,20 @@
+import { WorkflowError, WorkflowErrorCode } from "@automatalabs/workflow-engine";
+/** Resolve explicit host approval for script-declared command-spawning backends. */
+export async function approveScriptBackends(declared, approval, helperName) {
+    const names = Object.keys(declared).join(", ");
+    if (approval === undefined || approval === false) {
+        const guidance = helperName === "runDynamicWorkflow"
+            ? "Pass allowScriptBackends: true (or a per-backend approval callback) to runDynamicWorkflow, or thread an approved registry yourself via exec.scriptBackends."
+            : "Pass allowScriptBackends: true (or a per-backend approval callback) to runIsolation.";
+        throw new WorkflowError(`script declares custom ACP backends (meta.backends: ${names}) — these spawn commands on this machine and require explicit approval. ` +
+            guidance, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false });
+    }
+    if (approval === true)
+        return declared;
+    for (const [name, config] of Object.entries(declared)) {
+        if (!(await approval({ name, ...config }))) {
+            throw new WorkflowError(`script backend "${name}" (command: ${config.command}) was declined by the allowScriptBackends callback — aborting the run`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false });
+        }
+    }
+    return declared;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automatalabs/workflows",
-  "version": "0.30.1",
+  "version": "0.31.0",
   "license": "Apache-2.0",
   "engines": {
     "node": ">=22"
@@ -31,9 +31,9 @@
   },
   "dependencies": {
     "typebox": "1.3.2",
-    "@automatalabs/shared-types": "0.18.0",
-    "@automatalabs/workflow-engine": "0.19.1",
-    "@automatalabs/acp-agents": "0.25.0"
+    "@automatalabs/shared-types": "0.19.0",
+    "@automatalabs/workflow-engine": "0.20.0",
+    "@automatalabs/acp-agents": "0.25.1"
   },
   "scripts": {
     "build": "tsc -b",