xdog / Packages / flow / Reference

A reference to the current workflow JSON schema, the type system, condition operators, the runtime container a run returns, the xdog-flow CLI, and every check that runs at load time. A workflow is one JSON object executed directly by the runtime or compiled to Python — both agree field-for-field.

JSON schema

Workflow (top level)

A workflow is one JSON object with a valid entry frontier. An empty graph is not a runnable workflow; declare nodes and their explicit edges. entry is optional — when omitted, the run starts from every node that depends only on $in (multi-entry, run in parallel).

Node

A node is an agent (SDK or external CLI), script (Python), human signal gate, or opaque subflow. type defaults to agent. An agent node must not set code or run; a script node must set exactly one of them.

Port

A port is a bare string (a required string port) or an object. A structured output port lets an agent fan its submit_result result across several ports and lets an edge map a sub-field with a type check.

Edge

An edge moves data from a source node's output ports to a destination node's input ports. An empty map is a pure control edge (ordering only). $in is source-only; $output is sink-only.

Type system

Every port carries a JSON Schema (a bare name implies a required string port). The wire format is type-native: a port value is the live Python value — a script node reads its inputs as that value and returns the value directly, with no stringify/parse round-trip. An edge is type-checked at load time: the source and destination port types must match (a JSONPath sub-field is checked against the source schema when it can be resolved). $in seeds without explicit schemas are untyped, so their outgoing edges are exempt from source-type checks. Explicit in_schema enables seed type checks; fan-out from $in requires an explicit array schema. Consumer inference supplies the derived subflow input signature, not universal static typing of every seed.

Interpolation & conditions (JSONPath)

A prompt or a condition operand may embed {{ <jsonpath> }} placeholders, resolved against the node's inputs (or, for an edge when, the source node's output ports): {{ $.topic }} for a whole port, {{ $.plan.tasks[0] }} for a nested field. An unresolved path yields the empty string. The same jsonpath-ng evaluator runs in both the interpreter and the generated module.

Condition operators

An edge's when is a condition tree evaluated against the source node's output ports. value and text support {{ $.port }} JSONPath interpolation.

Every {{ $.key }} operand root is checked at load time against the source node's output ports (strict interpolation), so a typo fails validation.

Runtime container and process result

The Python execute() API returns an ExecResult with an internal runtime container. CLI and generated Python process boundaries print a stable envelope:

{
  "success": true,
  "message": "Workflow completed",
  "output": {},
  "context": {
    "workflow": "demo",
    "runId": null,
    "startTime": "...",
    "endTime": "...",
    "durationMs": 42,
    "tokensUsed": 0,
    "lastNode": "finish"
  }
}

Failures use the same shape with success:false, an error message, empty output, and a non-zero process exit code. The ExecResult.runtime container is:

CLI — xdog-flow

Commands that take a workflow accept .json or .svg with embedded JSON. Scheduling lifecycle commands use installed names, not workflow files; test also accepts a companion suite or directory. Use COMMAND --help for flags.

• xdog-flow validate <config> — Load and validate a workflow; prints OK or the first error. --json reports a machine-readable error envelope. Loading may import custom code; it is not guaranteed side-effect-free.
• xdog-flow run <config> — Execute a workflow and print the structured success/message/output/context result envelope.
• --dry-run — Replace SDK streaming with DRYRUN:<model>; does not stub scripts/CLI backends and may not satisfy structured-result contracts.
• --input K=V — Seed or override a $in value (repeatable; split on the first =). Values parse as JSON when possible, otherwise remain strings.
• --provider X — Override the AI provider.
• --timeout N — Per-node wall-clock timeout in seconds (default 120).
• --workspace DIR, --confined, --allow-path DIR — Work directory and cooperative confinement/grants, not an OS sandbox.
• -v / --verbose — Show flow's DEBUG logs — node execution and loop firing.
• xdog-flow generate <config> — Compile the workflow to Python with inlined helpers; runtime imports still apply.
• -o / --output FILE — Write to a file instead of stdout.
• --portable -o DIR — Package selected sources: SDK nodes/tool manifests select xdog.ai/xdog.agent, and subflow parents additionally vendor xdog.flow. Inspect child/custom dependencies; this is not a hermetic closure. --offline downloads selected wheels at build time.
• xdog-flow graph <config> — Render the workflow graph.
• --mermaid — Emit a Mermaid flowchart.
• --svg — Emit an SVG document with the workflow JSON embedded.
• xdog-flow build <config> — Open the interactive TUI builder (created if the file is missing).
• xdog-flow scheduling install <config> — Build a portable bundle and install a timer/hook scheduler; supports --name and --dry-run.
• xdog-flow scheduling list — List local registry entries, not verified live next-fire times.
• xdog-flow scheduling stop <name> / start <name> — Disarm/rearm an installed schedule; stop also ends a timer service run. Both support --dry-run.
• xdog-flow scheduling uninstall <name> — Remove units, bundle, and registry entry; supports --dry-run.
• xdog-flow test <target> — Run a workflow's companion *.test.json suite. Accepts a workflow (finds the sibling suite), a suite file, or a directory to sweep. Exits 1 on failure.
• --case NAME — Run a single case.
• --allow-script-stub — Permit scripts stubs (script nodes run for real by default).
• -v / --verbose — Show the node trace for passing cases too.

Path-subflow caveat: current validate --json parses without the file base directory, so a valid "subflow": "./child.json" can report invalid-subflow. Use ordinary validate FILE; inline children do not need that workaround. SVG loading also omits the base directory during child parsing: prefer the JSON source or inline children. These are parser-path limitations, not child failures.

Installed Flow tool

The installed flow capability contributes a skill and tool at application scope. Discovery/registration does not activate the skill body, grant permission or start a workflow/process. A node's skills list explicitly activates its body. Flow has no daemon.

Tool parameters are CLI argv, excluding the executable, plus optional absolute process cwd:

{"arguments": ["validate", "/project/workflow.json", "--json"], "cwd": "/project"}

The fixed same-environment invocation is Python -m xdog.flow, without a shell. Non-interactive validate, run, generate, graph, test, scheduling and help are supported; interactive build is manual-only. cwd is not a workflow --workspace or a permission grant. Results are {exit_code, stdout, stderr}; CLI JSON stays a string inside stdout. Inspect the actual code/diagnostics. Cancellation/close settles owned CLI processes, not rollback or uninstall of an accepted schedule. Output is bounded; interrupted effects are not automatically retried. Normal host permissions apply, including for imports during validation.

Structured SDK result and tool registry

The SDK runner and generated SDK code inject submit_result through Agent's existing tool loop, with generic result_schema and caller-owned result_sink. Successful validation writes result_sink["result"]; failure leaves it unchanged for correction. A single structured port receives the submitted array/object/scalar directly; multiple ports require an object keyed by port name. Old flow_output_schema / flow_result_sink context keys are rejected. Authors use canonical typed outputs, not a separate JSON output_schema field.

The executor owns a fresh registry with demo echo, SDK defaults bash, filesystem, current_time, and opt-in submit_result. Nodes select ordinary tools explicitly; structured submission is injected when needed. Trusted custom tool manifests can add module:attribute objects/factories. Imports do not mutate a global runtime inventory. CLI nodes use external tool/MCP configuration instead.

Workflow tests — xdog-flow test

A workflow is a program, so it needs tests. Flow uses a companion suite rather than embedding tests in the production artifact:

release_readiness.json
release_readiness.test.json

uv run xdog-flow test packages/flow/examples/release_readiness.json --allow-script-stub
uv run xdog-flow test packages/flow/examples/ --allow-script-stub
uv run xdog-flow test packages/flow/examples/release_readiness.json \
  --allow-script-stub --case "critical finding blocks the release"

Only the boundaries a test cannot reason about are stubbed. Agent turns (SDK and CLI backends alike), human signals, and whole subflow nodes; script nodes are opt-in behind --allow-script-stub, since stubbing deterministic logic hides the thing under test. Edges, conditions, loops, fan-out, fan-in aggregation, mappings, type coercion, retry and $output collection all run for real — a case cannot degrade into "I mocked the chain and asserted my own mocks".

Stubs are injected at the provider call, not at the node output. Prompt interpolation has already run, and the stubbed value still passes through the node's required-field check and to_state coercion. So a stub is validated by the same code that validates a real model response, and a broken {{$.path}} is still broken. Because the stub runner answers every agent node, no provider or CLI is ever constructed; missing agent stubs fail instead of reaching a live backend. Unstubbed scripts/imports still have real filesystem/process/network effects. The following is an excerpt, not a complete Release Radar suite; use the checked-in companion file for the collector stub, all required finding fields and assertions.

{
  "cases": [
    {
      "name": "critical finding blocks the release",
      "inputs": {"repo": "/fixture/repo", "base_ref": "main"},
      "agents": {
        "plan_checks": {"checks": [{"name": "security", "focus": "auth"}], "rationale": "..."},
        "audit": [
          {"when": {"check": {"name": "security"}}, "then": {"finding": {"severity": "critical"}}},
          {"then": {"finding": {"severity": "low"}}}
        ]
      },
      "subflows": {"report": {"final_report": "# Blocked", "quality_score": 9, "report_feedback": "ok"}},
      "expect": {
        "output": {"risk": {"status": "blocked", "release_allowed": false}},
        "calls": {"audit": 3, "report": 1}
      }
    }
  ]
}

A stub is authored as the node's output ports — either a constant, or an ordered rule list where the first match wins. Three selectors, each stable under concurrency:

Use when for fan-out and round for loops — that is how a case pins down loop termination: score below the gate on round 1, above it on round 2.

expect takes exactly one outcome — success (the default), error: "<substring>", or paused: "<human node id>" — plus two partial assertions. output is a deep subset of $output; calls maps node id to invocation count and collapses four questions into one number:

Objects match as subsets, arrays must be the same length, and bool only matches bool. On failure only the deepest differing path is printed, with a trace marking each node stub or ran. Two further failures are about the suite rather than the workflow: no rule matched a call (the activation's inputs are printed), and a selector that never fired (a stale round: 3 against a two-iteration loop).

Authoring mistakes are caught at load time — a stub aimed at a missing node, at the wrong node type, or setting an undeclared output port never reaches execution.

Nodes inside a subflow are deliberately not stubbable: a child workflow carries its own .test.json, so the parent asserts the composition and the child asserts its own internals. xdog-flow test runs the interpreter only — interpret == compile is flow's own invariant, guarded by flow's own suite, and binding your cases to codegen output would couple them to something they should not know about.

CLI agent nodes

An agent node may set "backend": "claude-cli" or "codex-cli" to run its turn by shelling out to a coding-agent CLI instead of the in-process SDK:

• No provider — the CLI owns auth; a workflow whose agent nodes are all CLI-backed omits provider (it is required only for an SDK agent node).
• allowed_tools — forwarded to Claude's --allowedTools when nonempty. Codex has no corresponding per-tool allowlist in this adapter. An empty list does not prove deny-all tooling or an enforced sandbox.
• mcp_servers — an opaque per-server spec flow converts into the CLI's MCP config, with ${ENV_VAR} secret interpolation (the JSON carries the reference, never the token).
• The CLI binary is found on PATH; FLOW_CLI_BIN (or FLOW_CLI_BIN_CLAUDE_CLI) overrides it. Both engines shell the same command, so interpret == compile holds.

Scheduling

A top-level schedule block declares deployment configuration, activated only by xdog-flow scheduling install; the one-shot engine ignores it:

• {"mode": "timer", "every": "15m"} or {"mode": "timer", "cron": "0 9 * * 1-5"} — a systemd user timer runs the bundle on schedule; there is no automatic CLI crontab/nohup fallback.
• {"mode": "hook", "signal": "s", "listen": {"type": "http", "path": "/hooks/x", "port": 8787}} — an external event delivers signal to a fresh run (routed by one shared, systemd-supervised listener). Pair it with a human node on the same signal.

Every firing is an independent python <bundle> run — the engine is unchanged. Timer installation provisions a uv environment by default; --no-venv --python selects an existing interpreter. --no-start skips immediate timer arming but still enables later login/boot startup; it does not disable hook setup.

Hook deployment currently needs operator review: the rendered listener unit names flow.scheduler.listener instead of xdog.flow.scheduler.listener, and its interpreter/spawn path uses /usr/bin/python3, not the timer bundle's uv interpreter. The live listener serves HTTP on loopback (default 8787), returning 202 after spawning, not a durable execution receipt or workflow result. File router helpers and accepted file/socket metadata do not start file watchers or socket activation. No built-in HTTP authentication option is enforced. Schema acceptance is not verified transport deployment; keep the listener private.

--dry-run previews units/actions without installation or provisioning, but still loads trusted workflow code. Stop/uninstall cannot undo prior effects. Do not store secrets in schedule.inputs: they are serialized into configuration; CLI MCP ${ENV_VAR} handling is a separate runtime feature.

Generated-module run-time overrides

A generated module reads a few environment variables at run time, so a compiled workflow (or a --portable bundle run with python .) stays overridable without regenerating. Some mirror run flags; others are generated/API-only controls:

• FLOW_INPUTS='{"days": 2}' — a JSON object merged per-key into $in (mirrors --input).
• FLOW_PROVIDER=copilot — override the provider (mirrors --provider).
• FLOW_MAX_TOKENS=100000 — abort once cumulative agent tokens pass the ceiling.
• FLOW_RUN_ID + FLOW_CHECKPOINT_DIR — enable checkpoint/resume.
• FLOW_SIGNALS=go,ready — deliver human-node signals (how a hook run passes its gate).
• FLOW_CLI_BIN (or FLOW_CLI_BIN_CLAUDE_CLI) — override the CLI binary a CLI agent node shells out to.

Generated modules do not implement run --dry-run; passing --dry-run to python workflow.py does not make it model-free. SDK imports, subflow imports of xdog.flow, third-party libraries and custom dependencies must be provisioned.

Validated before it runs

Loading a workflow runs every check below; any failure raises before a single node executes. This is what lets diagrams and codegen trust the graph.

Current topology restrictions also reject nested fan-out, fan workers inside loops, nested subflows, subflows inside loops and subflows as fan workers. A fan group is one checkpoint unit: incomplete groups can rerun all instances on explicit resume. A child has a namespaced checkpoint where configured, not parent-owned partial child scheduling. None of this promises exactly-once effects. context.lastNode is descriptive under concurrency; context.stoppedBy, when present, records the authoritative bounded-stop reason.