agentworkflow

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2026 License: MIT Imports: 1 Imported by: 0

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

View Source
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.
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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL