README
¶
Agent Workflow
A Go controller for single-user Claude/Codex workflows on Linux and macOS. It supports durable workflow admission, guarded recovery, command steps, bounded iterations, worker mailboxes, isolated Git workspaces, and GitHub publication.
Embedding Go applications can also register typed application actions with durable provenance, checkpoint validation, and receipt-based mutation recovery.
The portable PR maintenance example uses ordinary YAML and container-backed Python helpers with the stock CLI. The controller owns native agent sessions and recovery; the example owns PR policy, retained allowances, evidence checks and guarded publication receipts. Its guide documents explicit setup, recovery and changes from the earlier Go application.
Release status: implementation candidate, not yet production certified. See release evidence and outstanding gates. Live evidence is recorded separately for each provider and authentication route. Initial production certification targets Linux amd64 only. Linux arm64 and macOS remain available for deterministic build/test validation, with live certification deferred; see the enforceable support matrix.
Build and run
Requires Go 1.26+. Install only the providers selected by your roles. The SDK
bridge also requires Node 22+ and npm ci --prefix bridge/claude.
make build
./bin/agent-workflow validate workflows/parallel-review.yml
./bin/agent-workflow run --input task='Review this repository' workflows/parallel-review.yml
Flags precede the workflow reference. --workspace DIR selects a workspace
containing agents.yml and workflows/. --config FILE selects a configuration
relative to that workspace. Agent tasks use the canonical agent/run interface;
the former agent: shorthand and agent/<role> actions are rejected. Successful
text, response, structured results and usage outputs remain available.
Provider terminal status, version and queue timing are also recorded.
run starts a workspace controller when necessary, admits the request durably,
and waits for its result. Disconnecting the client or reaching its --timeout
leaves admitted work running. Use --detach for an immediate JSON handle.
--request-id ID makes admission retries return the same run; reusing the ID
with different inputs is rejected. Controller configuration changes require a
controller restart. --foreground provides an attached execution path with
exclusive workspace ownership and a whole-run deadline.
For CI, start the controller explicitly and retain its process until work ends:
agent-workflow controller --workspace .
# In another process:
agent-workflow run --workspace . --detach workflows/parallel-review.yml
Default execution capacity is four across jobs, reusable workflows, and live
workers. The controller admits at most 128 queued runs and runs at most four
workflows concurrently. Each controller execution has a 30-minute deadline.
These server limits are also configurable through the Go API. The CLI client's
--timeout defaults to 30 minutes; use 0 to disable its wait deadline.
Roles and authentication
agents:
claude:
provider: claude-cli
model: sonnet
permission-mode: dontAsk
codex:
provider: codex-app-server
sandbox: workspace-write
authentication:
mode: native
Supported providers:
| Provider | Authentication | Live worker sessions |
|---|---|---|
claude-cli / claude |
Installed Claude's native login | No; fresh process per call |
codex-cli / codex |
Installed Codex's native login | No; fresh process per call |
claude-sdk |
Native subscription-token reference, or gateway URL/API-key reference | Yes |
codex-app-server |
Explicit native or api-key credential reference |
Session transport implemented; managed worker policy is not yet certified |
The native CLI adapters are trusted-host compatibility adapters. They retain
provider-owned authentication and native configuration. They are not a
filesystem isolation boundary. Claude plan/dontAsk permissions do not provide
a Codex filesystem sandbox. The engine rejects live worker creation on a backend
that cannot enforce its managed role policy.
An engine-owned Claude SDK role is configured as follows:
agents:
reviewer:
provider: claude-sdk
bridge: bridge/claude/bridge.mjs
model: sonnet
instructions: [roles/reviewer.md]
tools: [Read, Glob, Grep]
limits:
max-turns: 16
max-depth: 4
max-queued-messages: 16
turn-timeout: 10m
max-output-bytes: 1048576
authentication:
mode: native
credential-env: CLAUDE_CODE_OAUTH_TOKEN
For an agent you run under your own Claude subscription, export the token from
claude setup-token as CLAUDE_CODE_OAUTH_TOKEN. Native SDK authentication uses
that environment reference by default; credential-env can select another token
variable. It preserves the engine-owned home/configuration directory and managed
tool policy. It does not import your native settings, skills, plugins or login
cache. See Anthropic's SDK token guidance.
API-key authentication remains available with mode: gateway, an explicit
endpoint and credential-env. The endpoint can be Anthropic directly
(https://api.anthropic.com); a separate proxy service is optional. Credentials
are environment references, never inline YAML values. Native SDK authentication
rejects endpoint and credential-file settings to keep the selected route explicit.
Instruction files resolve relative to the configuration file and their contents are pinned in the admitted snapshot. SDK roles disable filesystem settings, native skills, plugins, agent discovery, and unapproved MCP servers; provider managed restrictions remain applicable. Native delegation and discovery tools are rejected. SDK repair calls receive no tools and no original task prompt. Bridge protocol 2 negotiates the pinned SDK before effects and supports correlated callbacks and graceful interruption with a five-second guardian fallback. The bridge assigns its own session title and disables auto-memory/consolidation; provider-native structured-output attempts are limited to one, leaving repair under the engine's durable tool-free phase.
For Codex direct credentials, select authentication.mode: api-key and provide
credential-env. The app-server authenticates through its native login API and
uses engine-owned provider state. Custom Codex endpoints are not implemented.
Native app-server authentication references a provider-owned auth.json through
an engine-owned file-store link; set authentication.credential-file explicitly
or use the native CODEX_HOME/auth.json default. Writable provider state and
HOME remain private to the run/session owner. Keychain-only app-server login
is not supported by this route; the native CLI compatibility adapter retains its
provider-owned login behavior. Raw app-server arguments and managed tool subsets
are rejected until their policy is certified for the pinned upstream version.
API keys, gateway credentials, and workflow secrets are never written to the
SQLite snapshot. Native provider authentication stores remain provider-owned.
command, args, workspace, and model remain available for CLI adapters.
Agent-level relative workspaces resolve against the configuration directory;
with.workspace resolves against the workflow workspace and overrides the role.
instructions, tools, and authentication management apply to session
backends; legacy CLI configuration continues to be provider-owned.
Shared network runtime
On Linux with an operator-enabled BPF LSM and cgroup v2, an explicitly prepared rootful Podman runtime can contain network effects for local and container execution:
execution:
network-runtime: development
A global selection also applies to stdio MCP servers and cannot be weakened by
role execution overrides. Admission pins the runtime identity across resume;
missing or unhealthy runtimes reject engine admission. The standalone
agent-workflow-runtime launcher uses the same Go boundary for ordinary Codex
sessions. An explicitly installed, enabled and trusted Codex plugin restores
routing values inside covered local POSIX shell tools while preserving native
profiles, authentication, approval and sandbox settings. The operator-enabled
BPF LSM socket boundary prevents host Unix API fallback when hooks are skipped
or routing values disappear. Admission rejects saved TCP/SSH container API
routes. Hosts require the documented kernel support and explicit socket-boundary
enrollment; authentication sockets require explicit identity enrollment.
See operator setup, plugin coverage, forwarding and recovery.
Containers
Workflows can declare shared jobs.<id>.container images and sibling
uses: docker://IMAGE steps. Ordinary Ubuntu/Python images receive the packaged
Linux guardian automatically. Optional action-v1 helpers use inline/named
schemas, durable lifecycle recovery and retained workflow-local files. See
container authoring and recovery and the
portable examples.
Session backends can select:
execution:
mode: container
runtime: podman # docker also supported
image: registry/image@sha256:REPLACE_WITH_DIGEST
writable: false # explicitly enable for writers
The same policy can be configured at top level as execution: for command
steps and roles that omit an execution policy. A role with an explicit execution
mode overrides that default. cleanup: strict applies to all inherited roles;
on macOS it requires containers. Native macOS execution provides process-group
cleanup. Native Linux execution additionally supervises detached descendants.
Container images must carry guardian protocol label
agent-workflow.guardian-protocol=1 and include
/usr/local/bin/agent-workflow-guardian. SDK images also carry matching SDK and
bridge-protocol labels and include the Linux bridge/dependencies in the image;
host macOS node_modules are never mounted into a Linux VM. Explicit positive
uid/gid settings can select a non-root mapping; Podman defaults to keep-id.
PID 1 verifies readable/writable mounts and UID access before workload effects.
Image distribution and Docker/Podman host certification remain release gates.
Images must already exist locally and be pinned by digest. No image is pulled
implicitly. Containers receive a read-only root filesystem, bounded resources,
a private temporary filesystem, the selected independent repository, private
provider session state, the SDK bridge if needed, and explicit provider auth.
Host homes, SSH agents, GitHub environment credentials, and Docker sockets are
not mounted. A host lifetime guardian verifies ownership labels before removing the
container. A non-root Linux PID 1 also monitors a private controller heartbeat;
it requires a changing heartbeat before effects and stops work when ownership
ends, including when the host runtime is unavailable. Native Codex container authentication requires an explicit
authentication.credential-file referencing its provider-owned auth.json.
A host worktree's shared .git administration is rejected. Use
workspace/create with independent: true for container writers. Reviewer
snapshots are independent repositories; configure their container roles with
writable: false to enforce read-only access.
Durable execution and recovery
SQLite at .agent-workflow/state.db is authoritative, using WAL and FULL
synchronous durability. The engine records the workflow closure, definition
hashes, resolved roles, nonsecret inputs, Git baseline when needed, and secret
references before admission. It records attempts before effects and completion
before dependents. A workspace lock prevents competing controllers, and
conditional run claims prevent competing resume requests.
agent-workflow status RUN_ID
agent-workflow list
agent-workflow logs --follow RUN_ID
agent-workflow attempts RUN_ID
agent-workflow task-state RUN_ID
agent-workflow cancel RUN_ID
agent-workflow resume --retry-uncertain RUN_ID
agent-workflow resume --request-id recovery-1 --retry-uncertain --detach RUN_ID
agent-workflow export RUN_ID
agent-workflow export --artifact ARTIFACT_ID RUN_ID > stdout.txt
agent-workflow stop
agent-workflow cleanup RUN_ID
status, list, logs, and artifact inspection work without the controller.
Container helpers can opt into durable logical claims, allowances and absolute
deadlines with run --task-group GROUP. Replacement runs must supply the same
explicit group; resume retains its admitted group. task-state RUN_ID inspects
that group's retained state without starting the controller. See
task state for the scoped Python client, reconciliation,
continuation provenance and cleanup contract.
Each supervised invocation is journaled with its originating generation and logical/physical identity. Containers are created inert, their identity is committed, then attached-started with stdin/stdout intact. Startup and background reconciliation inspect exact runtime identity and ownership labels. Failed inspection never proves absence. Unresolved cleanup blocks conflicting admission while cancellation and inspection remain available:
agent-workflow invocations RUN_ID
GET /runs/RUN_ID/invocations returns pending records; ?all=true includes
completed records. Native guardians leave durable completion acknowledgements;
cleanup never signals a stored host PID. A lost create response does not start
the container automatically. Runtime recovery retries cleanup, preserving the
original attempt and uncertainty history.
Resume uses the saved definitions rather than current YAML. Completed steps and
successful jobs are retained. A stopped owner leaves active runs
needs_attention; no effect is replayed automatically. Inspect the workspace and
attempts before using --retry-uncertain, which explicitly permits uncertain failed or
interrupted effects to run again. A checkpointed completed task awaiting schema
repair is resumed as formatting only and does not require replaying its actions.
Control reusable workflows through their
originating run. Their execution capacity and workspace ownership are shared.
Resume is durably queued before its 202 acknowledgement and uses the same
execution owner as a new run. Status includes execution_generation and, on
failure, failure_class. Optional --request-id deduplicates resume within one
run; reusing it with a different retry acknowledgement is rejected. Each accepted
generation retains its own acknowledgement and cancellation history. Missing
resume credentials or failed preflight become inspectable needs_attention
outcomes. Workers are closed and joined before terminal status is published.
CLI list, worker --operation list, and worker --operation messages return
compact {items, next_cursor} pages. Use --limit (default 100, maximum 1,000)
and pass next_cursor back with --cursor. Individual status/result commands
retain full results. HTTP list endpoints opt into pagination with limit or
cursor; calls without these parameters and existing Go list methods retain
their legacy array shapes.
Existing schema-1 through schema-12 databases upgrade transactionally when the controller (or a
foreground execution/cleanup command) holds the workspace lock. The upgrade
retains .agent-workflow/state.pre-v13.db, a consistent database-only backup
including committed WAL records. Verify upgraded inspection and deterministic
execution before manually removing this backup. Inspection opens storage read
only and asks for an explicit controller upgrade when the schema is older;
newer unsupported schemas are rejected. Stop the owner before restoring any
database. A database backup alone does not include managed repositories or
provider session state and cannot guarantee session recovery.
Git commits and publication have additional durable intents and reconciliation. A lost PR-create response is reconciled against the exact head, base, and commit. If the create result remains uncertain and no matching PR can be found, creation stops for manual attention rather than issuing another create request.
Legacy .agent-workflow/runs/*.json records remain readable through status;
they cannot resume. FileStore remains available to library callers for JSON
exports/checkpoints, without durable replay semantics.
Use --secret-env NAME=ENV_VARIABLE for workflow secrets. A background controller
must have those variables in its own environment. Resume requires credentials
to be available again. Known secrets are redacted in persisted results and
artifacts. Admission rejects credential literals in definitions or nonsecret
inputs instead of modifying their replay semantics. State files and sockets use
0600; newly created state directories use 0700.
Durable external input
Use uses: input/wait with required with.prompt and with.evidence-id and an
optional JSON with.payload to ask a durable question. Engines advertise
durable-external-input-v1 through Go capabilities and controller health.
Waiting releases execution and controller capacity after independent work drains.
Accepted answers automatically queue continuation; interrupt preserves questions
and answers while pausing continuation until resume. cancel invalidates gates.
Inspect with agent-workflow inputs RUN_ID and submit JSON with
agent-workflow answer --gate GATE --evidence-id EVIDENCE --answer-id DELIVERY --answer-file answer.json RUN_ID (- reads stdin). Synchronous execution prints
the suspended handle and exits with status 2. Steps expose answer, answer_id,
gate_id, and evidence_id. See durable external input
for the controller API, embedding contract, evidence revalidation, restart and
backup semantics, and the preparation → wait → re-preparation pattern.
Retention and recovery backups
cleanup RUN_ID records removal intent/progress before removing owned Git
workspaces, clones, provider state, invocation files and database records.
Interrupted cleanup is resumable by repeating the command. cleanup-status RUN_ID
inspects its journal, including the completion tombstone after deletion.
Retiring runs cannot resume. Cleanup requires stopped execution and resolved
invocation cleanup, holds exclusive ownership, and leaves caller files, other
origins and provider-owned native authentication untouched. Ownership-path
symlinks are rejected; native authentication links inside removed provider state
are removed without following them.
Stop the controller before database maintenance:
agent-workflow stop
agent-workflow backup --workspace . /private/backups/state.db
agent-workflow bundle --workspace . /private/backups/recovery.tar.gz
agent-workflow restore --workspace . /private/backups/state.db
Backup captures committed WAL records consistently. Restore validates integrity
and supported schema, preserves a pre-restore database, and installs atomically.
Runnable/failed/canceled restored records are quarantined as needs_attention;
effects may have occurred after the snapshot. Inspect the external state and
use an explicit uncertain-retry acknowledgement. Restored mailboxes are
quarantined and pending entries are retained as interrupted, requiring a new
explicit send rather than replay.
Database-only backup preserves records and immutable helper manifests. Portable
helper recovery also requires the referenced assets/ files; bundle includes
verified committed assets and preserves executable modes. Session recovery also requires matching
managed workspaces and engine-owned provider state. Recovery bundles contain
those engine-owned paths and exclude native credential files and references.
They are private sensitive archives, not publication artifacts. Restore files at
matching managed paths and restore their database through the command; caller
Git administration and native provider credential stores remain separate.
MCP exposes controller_stop, database_backup, database_bundle and
database_restore; maintenance still requires the controller to have stopped.
Workflow syntax
Existing manual/workflow-call inputs, reusable jobs, needs, if, sequential
steps, outputs, continue-on-error, and structured output contracts continue to
work. YAML parsing rejects duplicate keys, aliases, unknown fields, and cycles.
The small expression grammar supports paths, literals, comparisons, not, and
and; it does not add general scripting, parentheses, OR, or expression functions.
Agent and command steps can declare onError fallback, onFailure reporting,
and bounded finally cleanup lists. See YAML step failure handlers
for output replacement, expression scope, cancellation, and durable recovery.
YAML jobs also support nested parallel and sequence step blocks for local
fan-out/fan-in. Branches read a snapshot of completed incoming results; following
steps can consume named branch results after a successful join. Leaf operations
share the host execution capacity, and durable resume retains completed work.
See YAML control flow for syntax, result scope,
cancellation, and recovery semantics.
YAML conversation steps let declared roles exchange messages in persistent
sessions, with one designated finisher and shared turn, message, and time limits.
The result uses the existing structured-output contracts and named step paths.
See YAML conversations for syntax, adapter
requirements, permissions, and durable recovery.
Named step results
Successfully completed agent results have concise paths:
jobs:
review:
steps:
- id: decision
uses: agent/run
with:
agent: reviewer.toml
prompt: Review the change.
output:
format: json
schema:
type: object
properties: {approved: {type: boolean}}
required: [approved]
- uses: agent/run
with:
agent: reporter.toml
prompt: 'Approved: ${{ steps.decision.approved }}'
publish:
needs: [review]
steps:
- uses: agent/run
with:
agent: reporter.toml
prompt: 'Review: ${{ needs.review.steps.decision.text }}'
steps.<id>.<field> reads a field from the validated structured object, including
nested paths. steps.<id>.text reads the original text result. The outputs,
status, and error names retain their legacy meanings, and text is reserved
for the text result. Read a colliding structured field explicitly through
steps.<id>.outputs.structured.<field>. Existing mappings and expressions keep
their meaning; a whole steps.<id> value retains its original metadata shape.
Structured arrays and scalars remain available through outputs.structured.
Within a job only preceding completed steps are available; job outputs and
repeat.until can use all completed steps in that attempt. A declared direct
dependency exposes needs.<job>.steps.<id>.<field> without a job output alias.
Only callable workflow output expressions can use the workflow-wide form
jobs.<job>.steps.<id>.<field>. Unknown producers, forward references, and
references outside these scopes are rejected before execution. New data aliases
fail explicitly for skipped or failed steps, absent result fields, or a missing
text/structured result; legacy outputs, status, and error access keeps its
existing behavior. Cross-job steps paths also allow these explicit metadata
fields and report missing fields as errors.
Repeated step jobs expose the final attempt's retained steps to dependents.
Reusable workflow internals remain private, including ordered for-each jobs;
consume their declared workflow outputs or ordered item outputs instead.
Aliases derive from the existing retained results, so resume uses admitted
definitions and checkpointed values, with the same redaction and replay rules.
Commands and bounded iterations
jobs:
check:
repeat:
max-attempts: 3
until: ${{ steps.check.outputs.exit_code == 0 }}
steps:
- id: check
argv: [go, test, ./...]
timeout: 5m
continue-on-error: true
argv executes directly. Shell execution requires both run and an explicit
shell, for example shell: sh. working-directory and positive-duration
timeout are supported. Outputs include exit_code, stdout, and stderr;
stdout/stderr are also durable artifacts. Each stream is limited to 16 MiB.
Arguments must render to strings; use interpolation such as
'attempt=${{ iteration.number }}' when including a number in an argument.
iteration.number starts at one; iteration.previous starts as an empty object
and then contains the previous status, outputs, and steps. Repeat conditions can
also inspect iteration.outputs and iteration.status. Reusable workflow jobs
can repeat. The engine retains all attempt history and fails on exhaustion.
max-attempts must be 1–100; the development example uses three fix cycles.
Reusable jobs also support dynamic iteration with ordered results:
jobs:
reviewers:
uses: workflows/reviewer.yml
for-each:
items: ${{ inputs.reviewers }}
key: item.id
concurrency: 3 # optional; defaults to one
with:
reviewer: ${{ item }}
ordinal: ${{ iteration.number }}
identity: ${{ iteration.key }}
items is a literal array or a whole expression returning an array. key is
an expression returning a nonempty unique string for each item. All identities
and call inputs are validated and pinned before starting any child. Literal item
payloads remain data, including strings containing expression delimiters.
for-each requires uses and cannot combine with repeat. YAML and Go are
supported; the browser preserves and validates YAML without guided iteration
controls. Optional concurrency is a positive integer, pinned with the plan;
omitting it preserves sequential execution. At most that many item controllers
run concurrently. Their agent invocations, commands and container execution use
the existing shared host/provider capacity. Registered Go action dispatch does
not acquire an execution lease; handlers may overlap across active items and can
start and wait for engine workers, whose invocations share execution capacity.
Retained bindings and checkpoint validation may also run while a later agent or
command holds capacity. The item bound limits active child workflows; each
child's own job and block concurrency still applies. The
iteration controller occupies no execution slot while waiting for children.
Results retain input order regardless of completion order. A blocking failure or
durable input suspension stops new item admission, cancels active siblings, and
joins them before exposing the partial aggregate. Already completed siblings stay
immutable; interrupted siblings require the normal guarded resume. A genuine
failure during sibling cleanup takes precedence over a safe input suspension.
The job exposes outputs.items in configured order and outputs.complete.
Each item retains its key, one-based number, physical attempt and child ID,
outputs, child jobs, failure class and reason. Outcomes are completed,
exhausted, provider_failure, interrupted, and pending. Completion requires
at least one completed item, no unresolved provider failure, and no pending or
interrupted item. Empty and all-exhausted lists have complete: false;
exhaustion remains an explicit skip. A classified provider failure fails the job
while permitting later items; a caller can inspect the aggregate with a dependent
job condition. continue-on-error never hides integrity, ownership, cleanup,
instruction, checkout or storage failures.
Adapters classify recoverable provider errors with workflows.ErrProviderFailure
or workflows.ErrUsageExhausted (wrapped with a reason). Arbitrary errors are
blocking failures. Registered actions supply binding and evidence guards; use
those guards before provider work. The engine revalidates retained action
bindings and evidence before each item and provider dispatch, and before reuse.
It never infers evidence validity from provider text.
Explicit resume reuses validated completed items and creates fresh physical
children for exhausted, failed or interrupted items. The normal
--retry-uncertain acknowledgement still applies. Successful runs containing
exhausted skips can be reopened. Prior attempts and completed results remain
immutable. Changed ordered lists, payloads, resolved inputs, definitions or action
contracts require a new run; definitions are always taken from the admitted
snapshot. Dependent aggregates are invalidated on retry. Read-only aggregation
can refresh; changed inputs to completed mutations or commands block replay.
Within item retries, registered mutations retain a stable logical operation
identity: validated completed effects are reused, and uncertain effects require
reconciliation proof of completion or no effect before proceeding.
The engine advertises ordered-dynamic-iteration-v1 through Capabilities() and
controller health. Embedders must supply the optional IterationJournal
extension (implemented by SQLite schema 9). It pins plans, appends item admission
and terminal observations, binds ordinary step inputs through BeginInput, and
fences every write against the originating execution owner. Nested controllers retain a
stable logical checkpoint namespace across physical ancestor retries, preserving
completed inner items and completed command/action effects. A committed child
completion recovers a lost parent/item checkpoint without repeating its work.
Schema upgrades use the existing exclusive lock and private pre-upgrade backup.
Legacy JSON stores cannot execute iteration workflows.
Native agent tasks
Use agent/run with a native Codex TOML definition. Paths resolve relative to
this workflow; the configured codex runtime must use codex-app-server.
jobs:
review:
steps:
- id: review
uses: agent/run
with:
agent: ../.codex/agents/reviewer.toml
prompt: Review the change.
input: {focus: correctness}
output:
format: json
repair-attempts: 0
schema: {type: object, required: [approved], properties: {approved: {type: boolean}}}
Definitions support name, description, developer_instructions, model, and
model_reasoning_effort. Admission captures the definition and effective runtime
settings. An explicit definition creates an independent agent; use
${{ steps.review.outputs.agent }} as another task's with.agent to continue
its session. Identity survives retries and execution generations.
See agent tasks and event hooks for the supported TOML
subset, typed inputs, completion verification, six ordered hook lists, and
recovery rules. Quote date-like prompts such as "2026-11-06". Removed forms
agent: ROLE and uses: agent/ROLE are rejected.
Structured output uses native schemas on session backends and strict-object
contracts on current CLI backends, followed by engine validation.
output.repair-attempts: 0 disables repair. The older
repair_attempts and repairAttempts spellings retain their legacy defaults.
Verified tool-free repair is currently available only through claude-sdk;
other backends fail validation without repeating the implementation task.
Completed task output and repair admission/results are checkpointed separately.
Explicit resume can retry a bounded formatting phase using cached task output,
including after a lost terminal checkpoint, without running implementation again.
Attempt records retain task_attempt_id, original outputs, and repair history.
Reported cost_usd is included when the provider supplies it; native Codex
subscription usage has no dollar figure. Deduplicate cached task usage by
task_attempt_id when aggregating resumed attempt records.
YAML workflows can reuse a workflow-local output schema:
schemas:
Review:
type: object
required: [approved]
additionalProperties: false
properties:
approved: {type: boolean}
jobs:
review:
steps:
- uses: agent/run
with:
agent: reviewer.toml
prompt: Review the change.
output: {format: json, schema: Review, repair-attempts: 0}
- uses: agent/run
with:
agent: reviewer.toml
prompt: Review the tests.
output: {schema: Review}
output.schema accepts a literal schema name or the existing inline mapping.
Named contracts use the same output validation and repair controls as equivalent
inline contracts; format: json is optional when schema is present. Names use
the job-ID identifier syntax. Every declaration is validated, even when unused,
and unknown names fail before any workflow effects. Reusable workflow files
have independent schema maps: they neither import nor override caller schemas.
Admission expands names into the durable definition snapshot, so resume uses
the admitted contract even after source files change.
Named declarations accept the output validator's supported subset: a single
type (object, array, string, integer, number, boolean, or null),
properties, required, additionalProperties (boolean or schema), items,
enum, RE2 pattern, minLength, maxLength, maxItems, and minimum, plus
title, description, and $comment. Object, array, and length constraints
require the corresponding explicit type; minimum requires number or
integer. Length/item bounds are positive integers (minLength also accepts
zero); maxLength follows the existing validator's UTF-8 byte limit. Required
names must be nonempty, unique strings without surrounding whitespace. Schema
references such as $ref, composition, boolean schemas, union types, and other
keywords are rejected with a field path. Existing inline schema admission
retains its historical behavior. After expansion, schema strings interpolate
through the same step expressions as inline schemas. The YAML editor preserves
declarations and references during visual edits and export; complete constraint
admission remains a host check.
Development and publication
develop.yml runs planning, bounded implementation/test/
review cycles through develop-iteration.yml,
final checks and two final reviews, and GitHub publication. Its native Codex
definitions separate planning, implementation, correctness review and security
review instructions. All tasks use the configured codex runtime and its shared
security policy. To run the implementation example, deliberately configure that
runtime with sandbox: workspace-write; the default configuration is read-only.
Definition instructions do not establish separate sandbox permissions.
Enable publication only for a deliberate allowlisted repository:
publication:
repository: owner/disposable-repository
base: main
remote: origin
checks: [test]
reviewers: [review_one, review_two]
Controller actions are workspace/create, workspace/snapshot,
workspace/integrate, git/commit, and github/pr. workspace/create defaults
to a detached worktree at the admitted baseline; independent: true creates a
separate clone. workspace/snapshot creates an independent fixed-commit clone.
Integration cherry-picks completed writer commits serially and retains conflicts.
Commits reconcile a durable action footer after uncertain completion. Caller
worktree changes and branch position are preserved.
Publication requires a clean managed workspace at the supplied commit, the exact
configured GitHub remote, every configured check reporting checked_commit, and
at least two distinct review jobs reporting clean: true and reviewed_commit
for that commit. Workflow definitions are trusted to report those results
honestly. The publisher creates a run-specific branch, pushes without force,
reconciles one PR per run, and never merges. A push-negotiation guard rejects unexpected advertised remote changes and preserves existing pre-push hooks. Unexpected remote changes stop it.
MCP and worker controls
# Codex registration:
codex mcp add agent-workflow -- /absolute/path/agent-workflow mcp --workspace /repo
# Claude registration:
claude mcp add --transport stdio agent-workflow -- /absolute/path/agent-workflow mcp --workspace /repo
The stdio server uses the official Go MCP SDK and starts the workspace controller if necessary. Protocol output stays on stdout; diagnostics go to stderr. Tools expose workflow discovery/start, status/events/cancel/resume, artifact listing/retrieval, and worker spawn/send/status/wait/interrupt/close. Starts and sends return durable handles. Waits are bounded to 20 seconds and can be polled. MCP disconnection does not cancel admitted work.
Workers have stable IDs, parent links, provider session IDs, ordered durable mailboxes, and deduplicated message request IDs. Default limits are 64 workers, depth eight, 64 queued messages per worker, 32 turns per root worker, 30 minutes per turn, and 16 MiB output. Child grants are reserved from the parent's remaining budget and tools must be a subset of the parent's policy. Interrupted owner-loss turns are retained without automatic replay; worker recovery requires an explicit acknowledgement. Run cancellation closes all its workers.
agent-workflow worker --operation spawn --run RUN_ID --role reviewer --turns 8
agent-workflow worker --operation send --run RUN_ID --worker WORKER_ID \
--request-id message-1 --message 'Review the fixed snapshot'
agent-workflow worker --operation messages --run RUN_ID --worker WORKER_ID
agent-workflow worker --operation interrupt --run RUN_ID --worker WORKER_ID
agent-workflow worker --operation close --run RUN_ID --worker WORKER_ID
agent-workflow worker --operation resume --retry-uncertain --run RUN_ID --worker WORKER_ID
External MCP facade waits do not use execution capacity. Claude SDK roles can also use controller-brokered worker tools and explicitly configured external MCP servers. Provider-supplied arguments cannot choose another run or parent. Child native tools, MCP grants, workspace, execution boundary, and runtime limits remain within role and parent policy.
Configure servers and exact grants explicitly:
mcp-servers:
lookup:
transport: streamable-http
endpoint: https://tools.example.invalid/mcp
timeout: 30s
headers-env:
Authorization: WORKFLOW_LOOKUP_AUTH
# Add these fields to a claude-sdk role:
# mcp-grants:
# - {server: engine, tool: worker_spawn}
# - {server: engine, tool: worker_send}
# - {server: engine, tool: worker_status}
# - {server: engine, tool: worker_wait}
# - {server: engine, tool: worker_interrupt}
# - {server: engine, tool: worker_close}
# - {server: lookup, tool: search}
Stdio servers use transport: stdio, command, explicit args, and optional
environment-env mappings from server variable names to controller credential
references. HTTP headers-env works the same way. These credentials stay in the
broker/server environment. Omitted grants authorize no tools; wildcards are
rejected. Tool descriptions, object schemas (2020-12 or unspecified dialect),
and catalog fingerprints are pinned at admission and checked on resume.
The broker journals calls before dispatch, caches identical completed calls,
rejects conflicting call identities, and reserves child grants once. Lost
external responses remain uncertain and are never replayed automatically.
Inspect them with agent-workflow tool-calls RUN_ID or
GET /runs/RUN_ID/tool-calls; ?all=true includes completed and denied calls.
An uncertain call prevents terminal success. Explicit uncertain retry admits a
new attempt without erasing the earlier call or claiming its effect succeeded.
Capacity handoff is invocation-wide: the SDK must report the model stream stopped and every active native tool stopped or waiting for controller permission before its lease can suspend. Results reacquire capacity before provider work resumes. Native tool hooks also obtain capacity before effects. Suspended invocations are bounded at 128 per controller. Deterministic tests cover workflow → child → grandchild execution at capacity one and actual pinned-SDK multi-tool callbacks. Codex's managed-policy and quiescence capabilities remain an explicit release gate; another backend is never substituted automatically.
Usage accounting
agent-workflow usage RUN_ID, GET /runs/RUN_ID/usage, and MCP run_usage
return normalized totals plus provider/model and invocation detail. Status adds
normalized_usage; existing raw usage and cost_usd outputs are unchanged.
Input totals include Claude cache reads/creation. Cached input remains a separate
reported subset. Provider thread counters are recorded as observations/deltas,
not repeatedly added snapshots. Cached task checkpoints retain their originating
identity; formatting repairs and worker turns count separately.
Unknown dollar cost is null, with known_cost_usd showing only reported
amounts. Lost final observations retain partial tokens and complete: false.
Provider-reported usage from failed calls is retained. Schema upgrades backfill
available historical observations without changing snapshots or attempts.
No pricing lookups, billing estimates, or spending-budget enforcement are added.
Operations and development
/health remains liveness/compatibility metadata. /ready checks storage writes,
scheduler heartbeat, cleanup prerequisites, private state permissions, and state
and temporary filesystem capacity independently. Unavailable prerequisites return
explicit admission errors; cancellation and inspection remain usable.
/metrics serves queue depth/age, occupied/suspended slots, worker/run states,
failures, cleanup backlog, and storage errors over the existing private socket.
Metric labels contain no run IDs or prompts. Controller JSON logs rotate at
10 MiB with three retained files.
controller:
max-queued: 128
max-active-runs: 4
run-timeout: 30m
min-free-bytes: 67108864
min-free-inodes: 128
# temporary-directory: /private/workflow-tmp
The byte/inode defaults apply independently to both filesystems. An explicit zero disables that threshold. Doctor reports effective cleanup guarantees, dependency versions, capacity and state permission checks, and unresolved invocations. Protocol tests and production certification are reported separately.
init creates the initial role configuration and embedded example workflows
without overwriting existing files.
doctor checks versions/capabilities, cached native login status, gateway model
endpoint reachability/authentication, container runtime/image availability, the
Git baseline, and state write permission. A cached native login can still be
rejected by the model service; an actual live probe requires a separate budget.
Provider preflight rejects unavailable executable/credential references before
admission. cleanup removes terminal originating-run records and their reusable
children, artifacts/mailboxes/intents, registered worktrees, and independent
workspace clones. It preserves caller files and refuses active/uncertain groups.
Cleanup is refused while a controller owns the workspace.
make test # deterministic race tests, no model calls or credentials
make check # vet and workflow validation
make build
agent-workflow bridge setup --directory bridge/claude
node --check bridge/claude/bridge.mjs
# Actual pinned SDK against a local fake API; no upstream model calls:
AGENT_WORKFLOW_SDK_TEST=1 go test ./pkg/clirunner -run 'TestSDK(Bridge|Broker|Conversation)AgainstFakeGateway'
# Optional Linux container conformance using an already available pinned image:
AGENT_WORKFLOW_CONTAINER_IMAGE=sha256:IMAGE_ID go test ./pkg/clirunner -run TestContainer
Pull requests, merge queues (merge_group: checks_requested), and pushes to
main run four CI jobs: Native Linux AMD64, Workflow validation (actionlint),
Workflow UI Chromium, and the Required aggregate. Native checks include race
tests, vet, workflow validation, release-tooling tests, binary builds, bridge
syntax, and the pinned-SDK fake gateway. Chromium runs flow synchronization,
types, unit tests, package and packed-consumer builds, and the complete browser
project. Required rejects failed, cancelled, or skipped prerequisites.
The full pre-release workflow runs manually
and as a mandatory release gate on the tagged commit. It retains all four native
platforms with archive build/smoke/verification, bounded filesystem exhaustion,
genuine Docker and rootless Podman on both Linux architectures, and
Chromium/Firefox/WebKit. Its distinct Pre-release Required aggregate requires
every prerequisite to succeed before release archives, images, or publication
can proceed. Full validation has no nightly or main-push trigger and creates no
release candidates or tags. See release operations.
Enable Require merge queue for main when adopting this workflow, retaining
Required as the required status check. The queue runs the same Linux AMD64
and Chromium checks as PRs and main pushes.
Live tests and publication pilots are separate from deterministic tests and require explicit budgets and a disposable repository. Shared hosting, Windows runtime support, cron/webhook dispatch, non-Codex native agent definitions, automatic conflict resolution, and automatic merge remain outside scope.
The original schema/expression/output foundations came from PicoClaw; see NOTICE and LICENSE. Runtime bindings and orchestration are standalone Go implementations.
The sole supported publication path is the signed-tag .github/workflows/release.yml
pipeline. It requires deterministic checks, both provider E2E phases and human
certification against immutable same-run evidence before publication. Credential
setup, signing, approval, retry and recovery procedures: release operations.
The independent workflow viewer and editor provides React components,
plain JavaScript mounts, and a standalone browser bundle for authoring workflow YAML.
Run make ui-install ui-check ui-test ui-browser-test for deterministic UI validation,
or npm run dev --prefix ui to explore the repository examples locally.
Documentation
¶
Overview ¶
Package agentworkflow contains the example definitions distributed with the CLI.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Examples embed.FS
Examples are immutable at build time and copied by init without overwriting workspace definitions.
Functions ¶
This section is empty.
Types ¶
This section is empty.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
agent-workflow
command
|
|
|
agent-workflow-guardian
command
The image entrypoint is handled by pkg/process initialization so the same guardian protocol is available to the controller and the small worker binary.
|
The image entrypoint is handled by pkg/process initialization so the same guardian protocol is available to the controller and the small worker binary. |
|
agent-workflow-runtime
command
agent-workflow-runtime explicitly prepares/owns a shared Linux network runtime.
|
agent-workflow-runtime explicitly prepares/owns a shared Linux network runtime. |
|
workflow-conformance
command
workflow-conformance runs explicitly requested real-provider scenarios only.
|
workflow-conformance runs explicitly requested real-provider scenarios only. |
|
conformance
|
|
|
network-runtime/fixture
command
Standalone, model-free fixture for the explicit privileged network acceptance.
|
Standalone, model-free fixture for the explicit privileged network acceptance. |
|
examples
|
|
|
receipt-recovery
command
Command receipt-recovery demonstrates caller-driven registered-action recovery using only a local controller, SQLite, and a deliberately non-idempotent fake.
|
Command receipt-recovery demonstrates caller-driven registered-action recovery using only a local controller, SQLite, and a deliberately non-idempotent fake. |
|
internal
|
|
|
engine
Package engine connects the production provider, worker and broker adapters.
|
Package engine connects the production provider, worker and broker adapters. |
|
socketfence
Package socketfence installs the operator-enabled Unix API boundary.
|
Package socketfence installs the operator-enabled Unix API boundary. |
|
testutil
Package testutil provides disposable fixtures for deterministic tests.
|
Package testutil provides disposable fixtures for deterministic tests. |
|
pkg
|
|
|
containerapi
Package containerapi reconciles runtime objects using exact ownership labels.
|
Package containerapi reconciles runtime objects using exact ownership labels. |
|
controller
Package controller owns durable workflow admission independently of clients.
|
Package controller owns durable workflow admission independently of clients. |
|
development
Package development implements controller-owned Git and publication actions.
|
Package development implements controller-owned Git and publication actions. |
|
prfix
Package prfix materializes PR maintenance as ordinary workflows.
|
Package prfix materializes PR maintenance as ordinary workflows. |
|
runtimeexec
Package runtimeexec shares invocation ownership across agent and command steps.
|
Package runtimeexec shares invocation ownership across agent and command steps. |
|
runtimeexec/network
Package network implements the explicitly prepared shared network runtime.
|
Package network implements the explicitly prepared shared network runtime. |