Workflow steps and control flow

Control flow determines which action is eligible to run next and what happens when it cannot. The current runtime directly verifies ordered actions, declared state transitions, approval gates, and failure paths; it does not verify a universal branching language or compensation engine.

Generic branching, loop, concurrency, compensation, and timing semantics remain unverified.

Control flow should be documented only where the runtime supplies a concrete mechanism. Ordered action numbers and run-state transitions are verified. Waiting for a user, pausing for approval, recovering, rejecting, canceling, expiring, and failing are represented by declared states. General branches, loops, parallelism, compensation, and workflow-level timeout policies are not established. Keeping that boundary explicit prevents provider retry behavior or individual fixture logic from being promoted into universal workflow semantics.

Step types

The verified execution unit is an action. It records an ordered step, tool ID, risk, status, input, output, proposal ID, and timestamps. Functional-agent definitions can declare workflow steps and proposed actions, while tool contracts determine whether a step is available, contract-only, planned, approval-gated, or blocked.

No universal workflow-node catalog is present in the supplied contracts. Avoid describing conditions, delays, loops, joins, or parallel blocks as current features unless a later implementation source verifies them.

Runtime actions are identified by an ordered step number and a tool contract.

A step can be read-only, writing, externally side-effecting, destructive, or privileged through its risk classification.

Execution state and approval requirement determine whether the step can run.

Verified step behavior is an ordered action with a step number, tool, risk, status, input, output, optional proposal, and timestamps. The documentation should not invent a richer universal step taxonomy.

Failure handling should preserve the failing action, evidence, transition logs, and persistence mode. Actions can be blocked, require approval, or begin running according to policy. Timeout behavior remains local to the verified implementation unless a workflow-wide policy is explicitly defined.

An action includes an ordered step number and a tool identifier. The run state machine controls progression through planning, running, waiting, approval, recovery, and terminal states. Ordered action numbers and declared state transitions are verified; a universal branching language, loops, concurrency, and compensation are not.

A workflow description should remain traceable to its run, actions, proposals, decisions, evidence, and output. Policy can block an action, require approval, or permit it to begin; invalid state transitions return explicit errors.

Sequencing

If an action number is missing or duplicated, the history should be treated as incomplete until the underlying records are checked. Display order alone must not be used to invent an execution sequence that the action store does not support.

Step order provides a deterministic way to read the action history. A later action should not be assumed to have executed merely because it appears in the definition; check its status and the run transition log. Waiting for user input or approval can pause the sequence.

Parent and child runs can represent related execution, but they do not automatically establish concurrent branches. Treat each run as an independent state machine linked by identifiers.

Action order provides the verified basis for sequence.

The run state machine constrains when execution can move between planning, running, approval, recovery, and terminal outcomes.

Do not infer parallel scheduling from a list of ordered actions.

Sequencing is visible through step order and run-state transitions. An action may be blocked, await approval, start running, or fail, and those outcomes influence the containing run.

Invalid transitions return explicit errors instead of silently changing state. A workflow description should remain traceable to the containing run, its actions, proposals, decisions, evidence, and output.

Provider-level retries and timeouts must not be generalized into workflow-step policy. The agent runtime verifies action decisions and run transitions, not a universal workflow retry engine.

A visual builder or generally available trigger service should not be implied when the source only verifies runtime contracts.

Step order is data carried by the action record. It supports a deterministic reading of what was intended to happen first, but it does not prove that arbitrary graph execution is available. When one action waits for input or approval, later work should be interpreted through the run’s declared transitions rather than assumed to have continued in parallel.

Branching

The current state machine expresses guarded movement between declared run states; it is not a general-purpose branch-expression language. A blocked tool decision, approval requirement, rejection, failure, cancellation, or recovery path can change what happens next. The sources do not establish arbitrary user-authored conditions, merge nodes, loop counters, or parallel branches, so those constructs must remain outside this guide.

A state transition caused by approval or failure is not proof of a reusable branch node. Document the transition that occurred, not a visual control-flow feature that the sources do not establish.

Generic branching is not verified. Declared run transitions and helper-selected action paths cover blocked, approval-required, and running outcomes; they do not form an arbitrary condition builder.

Where a functional contract describes a specific decision, document only that contract and its evidence. Do not infer else branches, merge behavior, branch-local variables, or parallel scheduling.

A decision can block, ask for approval, or allow a proposed action.

State transitions create conditional paths such as awaiting approval, rejection, recovery, failure, or completion.

A general user-authored branch-expression syntax is not implemented.

General branching syntax is not verified. Conditional product logic may exist in individual functional contracts or helpers, but it should not be documented as a platform-wide visual branching feature.

The runtime contracts do not prove a generally available visual builder or trigger service. Failure handling should preserve the failed action, evidence, transition log, and persistence mode.

Model a supported path as ordered actions with explicit transitions for waits, approvals, failure, rejection, cancellation, and recovery.

Control flow documentation should name the exact state or action boundary that allows, pauses, rejects, or stops progress.

The available records can show that one action followed another or that a run waited for input or approval. They do not define a general branch expression, merge rule, loop condition, or parallel scheduler. Document a branch only when a specific agent contract declares it and the corresponding state transitions and actions are visible.

A child run is likewise a relationship, not proof of automatic fan-out. Operators should inspect parent and child identifiers, action order, and timestamps before drawing conclusions about execution order.

Retries

Action-level retry behavior is not defined as one reusable workflow primitive. Preserve the failed action and transition context, then apply only retry behavior implemented by that action or its underlying service. Gateway provider retries belong to the model-routing layer.

The supplied agent sources do not define one workflow-wide retry policy. Tool and action failure behavior can vary with side effects, approval, provider, and implementation. Repeating an external or destructive action may be unsafe if the first attempt partially succeeded.

Use run idempotency only for the behavior verified by createAgentRun: a matching key can return an existing run. It does not guarantee idempotent tools or action-level retries.

The agent source pack exposes recovery helpers and a recovering state but does not define one universal step retry count.

Retry behavior can depend on the agent or tool implementation.

Do not reuse Gateway retry semantics as an agent-workflow guarantee.

Workflow retries are not established as one global mechanism. Provider retries inside the Gateway and a new action or recovery transition inside an agent run are different behaviors and should remain separate.

Provider-level Gateway retries and timeouts must not be generalized into workflow-step behavior.

Retries should remain attached to a verified helper or tool behavior. The sources do not establish one default count, backoff schedule, or automatic compensation rule for all actions. Record each repeated attempt as part of the owning action or recovery path so operators can distinguish a deliberate retry from a newly created run.

Timeouts

No universal workflow timeout, step timeout, or scheduling deadline is verified. The expired run state exists, but the source bundle does not define one duration or automatic transition rule for all agents.

If a specific tool or provider has a timeout in its own contract, document it there. Do not transfer Gateway provider-timeout behavior into agent workflows without evidence.

The supplied workflow and agent types do not establish a global timeout value for every step or run.

An expired run is a defined state, but the trigger and timing policy that cause expiry require implementation context.

Surface timeout configuration only when a specific contract provides it.

No fixed workflow timeout model is supplied. Provider-specific Gateway timeouts, run expiry, and an action failure may all involve time, but they do not justify one universal timeout rule.

Provider retry behavior should not be promoted into a general workflow retry policy.

Failure paths

A parent run and child run can fail independently. The parent-child link supports navigation and summary counts, but the supplied sources do not define automatic propagation, cancellation, rollback, or completion rules between them. Review both state machines before claiming that one run determined the other’s result.

A step can be blocked before execution, wait for approval, fail after starting, or contribute to a run transition such as failed or rejected. Invalid run transitions return explicit errors, and terminal runs cannot continue. Persistence mode affects how much history remains available for diagnosis.

Record the current run state, transition log, action status, tool execution state, proposal and decision, evidence, output, and persistence. Those fields identify the failed boundary without inventing a generic compensation mechanism.

Blocked tools, denied approvals, invalid transitions, missing registry entries, unavailable persistence, and execution failures produce different paths.

Rejected, failed, canceled, and expired are distinct terminal states.

Record the failing step, evidence, proposal, decision, transition, and persistence outcome for diagnosis.

Failure paths should retain the failing action, exact state or transition error, proposal and decision context, evidence, audit events, child runs, and persistence mode before recovery is attempted.

The supplied contracts do not establish general branching syntax, loop semantics, concurrency control, compensation behavior, or fixed workflow retry and timeout rules.

Control flow is observable through action order and declared state transitions. An action that requires user input can move the run into a waiting state; an approval-gated proposal can move it toward awaiting_approval or partially_approved; a rejection can produce the distinct terminal rejected result; and execution errors can lead to failed or a supported recovery path. Invalid transitions return errors instead of silently forcing progress.

The type and helper sources do not define a general expression language for branches, loops, parallel joins, compensation, or workflow-wide timeout rules. A parent-child relationship should not be documented as automatic parallel execution, and a retry helper should not be described as universal action compensation. When a step fails, inspect the action status, tool execution state, proposal and decision, transition log, evidence, output, and persistence mode. Resume or replay only through a verified helper path and account for any side effect already produced.