Agentprism Workflows

AgentPrism Workflows

Run dynamic, multi-agent workflow scripts — agent(), parallel(), pipeline() — over real coding agents (Claude Code, OpenAI Codex, OpenCode, and pi), with deterministic journaling, resume, and git-worktree isolation.

Your agent authors a small JavaScript script (export const meta, then call agent() / parallel() / pipeline()); the engine runs it in a sandboxed realm, fanning each agent() call out to an Agent Client Protocol (ACP) backend. It's available two ways:

• As a TypeScript SDK — @automatalabs/workflows — embed the runner in your own program.
• As a stdio MCP server — @automatalabs/mcp-server, built on the SDK — expose workflow and repl tools to any MCP host (Claude Code, Zed, …).

> The @automatalabs/* packages are published on npm (except @automatalabs/repl-engine, unreleased at 0.0.0 while its repl tool ships inside @automatalabs/mcp-server) — see [Install](#install). Two are user-facing: the @automatalabs/workflows SDK and the @automatalabs/mcp-server stdio server.

---

Why AgentPrism

Real harnesses, driven over an open protocol

Each agent() call runs on a shipped coding agent — Claude Code, Codex, OpenCode, or pi — driven over ACP, rather than a reimplementation of an agent loop around raw model APIs. You get each backend's own tool loop, permissions, and context management, plus the auth you already have on your machine (~/.claude/.credentials.json, ~/.codex/auth.json, opencode auth login, provider API keys, or pi's ~/.pi/agent/auth.json). When the harness improves, your workflows improve with no code change here.

Many agents, one workflow

The backend is chosen per agent() call: a claude/opus[1m] review step, a codex/gpt-5.6-sol implementation step, an opencode/zai/glm-5.2 planning step, a backend-default pi research step, and a custom browser QA agent can share one script, hand each other structured results, and be swapped independently. Any ACP server registers as a named backend — the built-ins are defaults, not a boundary.

Have your agent write the workflow

You describe the workflow in plain language; your agent designs it with the right APIs, validates it, and runs it. Two ways to arm the agent:

• Agent skill — install the bundled authoring skill into any skills-capable agent CLI:

``bash npx skills add agentprism/agentprism-workflows ``

• MCP prompt — on prompt-capable MCP hosts, invoke the author-workflow prompt served by @automatalabs/mcp-server (in Claude Code it surfaces as a slash command, with an optional task argument). It injects the same authoring guide, so the agent targets the DSL that will actually execute the script.

A representative ask:

> Implement the spec in docs/specs/my-feature.md as a robust workflow of sequential stages. For each stage, have gpt-5.6-sol implement at xhigh effort and claude opus verify it at xhigh — it should re-run the builds and tests itself instead of trusting the implementer's claims — with the two going back and forth until the stage is green. Then a single final review phase that returns its findings; the workflow shouldn't loop back at all once it reaches the final review. Validate the workflow before launching it, then run it in the background and see it through to the end.

From an ask like that, the agent picks the primitives — gate() fix-loops with the reviewer's feedback threaded into fresh attempts, structured-output verdicts, self-contained prompts, per-call model routing and effort via configOptions — and the validator (static parse → mock dry run → per-harness config probe) proves the script's structure and its model/config choices for zero tokens before any real run.

Durable runs — resume without re-spending tokens

Scripts run in a deterministic realm and every agent() call is journaled under an identity hash. A new resumeFromRunId execution replays unchanged completed calls even after insertions or reordering; ambiguous or mismatched calls run live. Filesystem/environment drift is reported as provenance instead of vetoing replay. Provider quota and authentication walls don't fail the run either: the run pauses, keeps the interrupted ACP session reopenable, and on resume reattaches to continue that exact turn when its call index, identity, execution inputs, backend, cwd, and reopen capability still match. Any correspondence uncertainty fails to a fresh live call, while completed calls retain ordinary journal replay.

> Resume rule: replay is content-addressed and fail-to-live on correspondence: a completed call replays when its identity and input fingerprint match uniquely. Filesystem or world state never gates replay. > > args is not itself part of an agent() identity. New args can raise an orchestration-only loop cap while earlier calls keep replaying; when args change a prompt or another hashed/runner-visible input, only corresponding calls miss. New-format reuse requires exact cwd, compatible format/metadata/manifest admission, and unambiguous identity/input correspondence—not a purity annotation. Identity hits spend zero current provider tokens. See the [incremental resume API](docs/api.md#content-addressed-incremental-resume) for matching, reports, legacy fallback, and checkpoints.

Compact reader/experiment fan-out:

const [audit, experiment] = await parallel([
  () => agent("Audit src/api without changing files.", {
    label: "audit:api",
  }),
  () => agent("Try the worker fix in isolation; return a unified diff.", {
    label: "try:worker", isolation: "worktree",
  }),
]);

The worktree's edits are discarded; return them as data. Both completed calls replay from their journal identity without a filesystem-safety annotation.

Structured output as validated objects

agent({ schema }) returns a schema-validated object, not text to parse. Claude and Codex use their agent-specific schema channels. Pi, OpenCode, and eligible custom ACP agents get a client-hosted StructuredOutput MCP tool injected automatically when they advertise HTTP MCP support. The runner still validates and re-prompts on mismatch, so the same API works for schema channels, tool capture, and validated final-text fallback.

The full ACP spec, enforced by the build

Every client-side ACP method is served (fs/*, terminal/*, permission requests, elicitation, MCP-over-ACP) and the agent-side surface — session modes, session lifecycle, auth/providers — is driven, not stubbed. A coverage manifest keyed off the SDK's method constants breaks the build on protocol drift; the separate executable extension matrix tracks vendor _session/steering support without misclassifying it as standard ACP. The end-to-end suite covers real Claude, Codex, OpenCode, and pi providers when gated, including a Claude/Codex native-steering smoke, plus a credential-free pi leg through pi-acp's injected runtime.

Controls for unattended runs

Per-run agent and concurrency limits, per-call git worktree isolation, per-call timeouts and retries, and checkpoint() — a deterministic, journaled human gate with three modes. A live SDK confirm callback or MCP elicitation collects the reply immediately; without a live channel, the default mode takes default ?? true (or headless: "abort" aborts), so detached runs never hang by default. Authors can opt into a durable pause with headless: "pause": the run returns status: "paused" plus checkpointContext, the host resumes with checkpointReplies, and the decision is journaled and replayed without re-asking. For watching those runs from the outside, @automatalabs/agentprism-otel attaches to any WorkflowManager and exports OpenTelemetry traces (run → agent → tool call) plus token, cost, and duration metrics.

---

How it works

One process plays two protocol roles at once: it's an MCP server (or a library) that accepts a workflow script, and an ACP client that drives one or more agent subprocesses to execute each agent() call.

   your program  ──or──  MCP host (Claude Code / Zed / …)
        │  runDynamicWorkflow(script)      calls tool "workflow"
        ▼
┌──────────────────────────────────────────────┐
│  AgentPrism orchestrator                      │
│   • the deterministic engine runs the script  │
│   • ACP CLIENT → drives agent servers         │
└──────────────────────────────────────────────┘
        │  session/new or resume/load, then session/prompt … (ACP over stdio)
        ▼
   claude-agent-acp / codex-acp / opencode acp / pi-acp   (long-lived, pooled subprocesses)
        │  → real agents; paused occurrences may reopen their recorded session

The deterministic engine (sandboxed vm realm, parallel/pipeline, journal/resume, worktree isolation) is independent of how a single agent runs and of how the tool is exposed. See [docs/design-notes.md](docs/design-notes.md) for the full protocol-level design.

The MCP server also exposes a second, interactive route: the repl tool. Instead of running a deterministic script to completion, it holds a persistent QuickJS-in-WASM VM per project (the [@automatalabs/repl-engine](packages/repl-engine) tier), and the client's own agent writes live JavaScript that spawns subagents over the same ACP path — workspace state (bindings, pending calls, checkpoints, logged values) persisting between tool calls and across daemon restarts. Workflows is the batch orchestrator; repl is the live steering plane. See [The repl tool](packages/mcp-server/README.md#the-repl-tool).

---

Requirements

• Node.js ≥ 22 and pnpm ≥ 10 (see .nvmrc / packageManager).
• A backend agent CLI, authenticated on your machine:
• Claude — via the bundled @agentclientprotocol/claude-agent-acp; auth from ~/.claude/.credentials.json or ANTHROPIC_API_KEY (the orchestrator inherits your environment).
• Codex — via @automatalabs/codex-acp (+ the @openai/codex binary, installed as a dependency); auth from ~/.codex/auth.json.
• OpenCode — supported but not bundled. Install the opencode CLI on PATH or add opencode-ai to your own project (its platform binaries are large), then authenticate with opencode auth login.
• pi — via the bundled @automatalabs/pi-acp; auth from the selected provider's API key or pi's ~/.pi/agent/auth.json.

You only need auth for the backend(s) you actually call.

---

Install

From npm

pnpm add @automatalabs/workflows        # the SDK
# or, to run the MCP server:
pnpm add @automatalabs/mcp-server

From source (for development)

git clone  agentprism-workflows
cd agentprism-workflows
pnpm install      # installs deps + fetches backend binaries
pnpm build        # tsc -b across all packages

---

Packages

These are the packages you interact with directly. The first two are the primary user-facing entry points — start with one of them; the third is a standalone backend server:

| Package | What it is | |---|---| | @automatalabs/workflows | The canonical public SDK — a thin facade that runs workflow scripts programmatically over the default ACP backend, and re-exports the supported engine + backend integration surface. Start here. | | @automatalabs/mcp-server | The stdio MCP server (bin: agentprism-workflow) exposing the workflow tool (foreground/background run, await, resume, inspect, stop) and the repl tool (a persistent JavaScript REPL for live subagent orchestration) — built on @automatalabs/workflows and @automatalabs/repl-engine. | | @automatalabs/pi-acp | The standalone stdio ACP server (bin: pi-acp) embedding the pi coding agent in-process; exact-pinned and spawned by the first-class pi backend. |

One optional integration package attaches to the SDK's manager surface:

| Package | What it is | |---|---| | @automatalabs/agentprism-otel | OpenTelemetry traces and metrics for a WorkflowManager; peer-depends only on @opentelemetry/api and no-ops when the host has no OTel SDK. |

The five packages below are internal building blocks. Most are composed by the SDK (@automatalabs/workflows → workflow-engine, acp-agents, shared-types); the exceptions are @automatalabs/repl-engine, which depends on the SDK and is composed by the MCP server (which registers its repl tool), and @automatalabs/codex-acp, which is spawned by acp-agents. You normally don't depend on any of them directly: @automatalabs/workflows is the public entry point for the supported orchestration surface.

| Package | What it is | |---|---| | @automatalabs/acp-agents | The ACP client + Claude/Codex/OpenCode/pi/custom backends (the AgentRunner implementation, connection pooling, auth/session lifecycle, structured output, permissions, usage). Internal — public entry is @automatalabs/workflows. | | @automatalabs/workflow-engine | The deterministic engine: the script realm, parallel/pipeline, journal/resume, and worktree isolation. Internal — public entry is @automatalabs/workflows. | | @automatalabs/repl-engine | The REPL orchestrator engine: a persistent JavaScript REPL in a capability-free QuickJS-in-WASM VM (workspace lifecycle, eval + job drain, per-VM memory limits, per-eval interrupts, trap-free completion reads, the append-only call store and enveloped snapshots). Its repl MCP tool is registered in mcp-server (the roadmap's repl-orchestrator, phase E — implemented; the package itself is unreleased at 0.0.0); it depends on workflows, acp-agents (subagents are ACP sessions), and shared-types. | | @automatalabs/codex-acp | The workspace fork of agentclientprotocol/codex-acp (imported with full history) — the ACP server the Codex backend spawns, baking turn-level outputSchema forwarding into its shipped dist. Consumed by @automatalabs/acp-agents as workspace:*; you never depend on it directly. | | @automatalabs/shared-types | The AgentRunner seam + shared types the others compose against. Internal — public entry is @automatalabs/workflows. |

Dependency direction: mcp-server → { workflows, repl-engine, shared-types }; workflows → { workflow-engine, acp-agents, shared-types }; acp-agents → { codex-acp, pi-acp, shared-types }; repl-engine → { workflows, acp-agents, shared-types }. The SDK (workflows) is the single facade that composes the deterministic engine and the ACP backend, which meet only at the AgentRunner seam in shared-types. The engine never names a backend; the agents never know they're inside a workflow. acp-agents spawns the bundled codex-acp / pi-acp ACP servers as its Codex and pi backends. repl-engine composes the QuickJS-in-WASM shim with workflows (for the shared per-project key) and acp-agents (the REPL's subagents are ACP sessions against the same backends the SDK drives), and ships its repl tool in mcp-server.

---

Quickstart — SDK

Run a workflow script. The default backend is the ACP runner (createAcpRunner()), so this drives real agents and needs backend auth.

import { runDynamicWorkflow } from "@automatalabs/workflows";

const script = `
  export const meta = {
    name: "repo-scan",
    description: "describe a repo as JSON, three ways in parallel",
    phases: [{ title: "Fan" }],
  };

  const SCHEMA = {
    type: "object",
    additionalProperties: false,
    required: ["repo", "fileCount"],
    properties: { repo: { type: "string" }, fileCount: { type: "number" } },
  };

  phase("Fan");
  const results = 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 }),
  ]);
  return results;
`;

const run = await

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [agentprism](https://github.com/agentprism)
- **Source:** [agentprism/agentprism-workflows](https://github.com/agentprism/agentprism-workflows)
- **License:** Apache-2.0
- **Homepage:** https://agentprism.com

Install and usage instructions live in the source repository linked above.