mirror of
https://github.com/fabro-sh/fabro.git
synced 2026-08-28 05:27:41 +00:00
133 lines
6.7 KiB
Text
133 lines
6.7 KiB
Text
---
|
|
title: "Node Outcomes"
|
|
description: "The four stage outcomes and the attributes that control them"
|
|
---
|
|
|
|
Every node execution produces an **outcome** that drives edge routing, retry logic, and goal gate checks. This page defines the four externally visible outcomes and the attributes that influence them.
|
|
|
|
## The four outcomes
|
|
|
|
| Outcome | Meaning |
|
|
|---|---|
|
|
| `succeeded` | The handler completed normally |
|
|
| `failed` | The handler encountered an unrecoverable error |
|
|
| `partially_succeeded` | The handler did not fully succeed but produced usable results — typically from retries exhausted with `allow_partial=true` |
|
|
| `skipped` | The node was not executed (e.g. a branch not taken in a parallel fan-out) |
|
|
|
|
<Note>
|
|
Retry intent is internal to the engine. It triggers re-execution inside the retry loop and is never visible in edge `condition` expressions. Retryable failures emit `stage.retrying` events while the node is still active, then finish as one of the four outcomes above.
|
|
</Note>
|
|
|
|
## How handlers produce outcomes
|
|
|
|
Each node type has its own rules for which outcomes it can return:
|
|
|
|
| Handler | Produces | Conditions |
|
|
|---|---|---|
|
|
| **Command** | `succeeded`, `failed` | `succeeded` when exit code is 0; `failed` otherwise |
|
|
| **Agent / Prompt** | `succeeded`, `failed`, `partially_succeeded`, `skipped` | Defaults to `succeeded`. The LLM can set any outcome via a [routing directive](/agents/outputs#routing-directives) JSON object in its response. Backend errors request retry when retryable or finish as `failed`. |
|
|
| **Parallel** | `succeeded`, `partially_succeeded`, `failed` | Waits for every branch. `succeeded` when all branches succeed, `failed` when all branches fail, and `partially_succeeded` for mixed or partial results. A static fan-out with no branches remains partial; a valid `for_each` source with zero items succeeds. |
|
|
| **Human** | `succeeded` | Always succeeds — the user's selection becomes a routing signal via `preferred_label` |
|
|
| **Conditional** | `succeeded` | Always succeeds — routing is handled by the engine's edge selection |
|
|
| **Start / Exit / Wait** | `succeeded` | Always succeed |
|
|
|
|
## Retry loop
|
|
|
|
When a handler returns a retryable failure, the engine enters the retry loop. If retry attempts remain (per the node's [retry policy](/execution/failures#retry-policies)), the handler re-executes after a backoff delay. If attempts are exhausted, the final outcome depends on `allow_partial`:
|
|
|
|
```
|
|
┌─────────────┐
|
|
│ Run handler │
|
|
└──────┬──────┘
|
|
│
|
|
▼
|
|
┌──────────┐ succeeded / failed /
|
|
│Outcome? │─── partially_succeeded / skipped ──▶ Done (use as-is)
|
|
└────┬─────┘
|
|
│ retryable failure
|
|
▼
|
|
┌──────────────┐ yes ┌──────────────┐
|
|
│ Attempts │─────────▶│ Backoff + │──┐
|
|
│ remain? │ │ re-execute │ │
|
|
└──────┬───────┘ └──────────────┘ │
|
|
│ no │
|
|
▼ ┌──────────┘
|
|
┌──────────────┐ │
|
|
│allow_partial?│ │ (loops back to
|
|
└──────┬───┬───┘ │ "Run handler")
|
|
yes │ │ no │
|
|
▼ ▼
|
|
partially_succeeded failed
|
|
```
|
|
|
|
Handler errors follow the same loop: retryable errors (transient infrastructure) re-execute if attempts remain; non-retryable errors (authentication, bad config) fail immediately without consuming retry attempts.
|
|
|
|
## `allow_partial`
|
|
|
|
When `allow_partial=true` and the retry loop exhausts all attempts on a retryable failure, the outcome is promoted to `partially_succeeded` instead of `failed`. This lets the workflow continue past nodes that could not fully succeed.
|
|
|
|
| Attribute | Type | Default |
|
|
|---|---|---|
|
|
| `allow_partial` | Boolean | `false` |
|
|
|
|
```dot
|
|
implement [
|
|
label="Implement",
|
|
retry_policy="standard",
|
|
allow_partial=true,
|
|
prompt="Implement the feature."
|
|
]
|
|
```
|
|
|
|
In this example, if the agent returns a retryable failure and all 5 standard-policy attempts are used, the node finishes with `partially_succeeded` rather than failing the run.
|
|
|
|
See [Retry policies](/execution/failures#retry-policies) for the available presets and backoff settings.
|
|
|
|
## `auto_status`
|
|
|
|
When `auto_status=true`, any non-`succeeded` and non-`skipped` outcome is silently overridden to `succeeded` after the handler completes. This is applied after the retry loop, so retries still happen normally — only the final outcome is overridden.
|
|
|
|
| Attribute | Type | Default |
|
|
|---|---|---|
|
|
| `auto_status` | Boolean | `false` |
|
|
|
|
```dot
|
|
scan [
|
|
label="Scan",
|
|
shape=parallelogram,
|
|
auto_status=true,
|
|
script="find . -name '*.log' | head -20"
|
|
]
|
|
```
|
|
|
|
Use `auto_status` for nodes whose failure should never block the workflow — optional scans, best-effort cleanup steps, or informational commands where the output matters more than the exit code.
|
|
|
|
## Goal gate interaction
|
|
|
|
Node outcomes and workflow status are separate. A node can finish with `failed`
|
|
and the workflow can still reach `exit` and complete successfully if routing
|
|
handles that outcome. Mark a node with `goal_gate=true` when its failure must
|
|
make the workflow fail.
|
|
|
|
Nodes marked with `goal_gate=true` are checked when the workflow reaches the exit node. A goal gate is satisfied if its last outcome was `succeeded` **or** `partially_succeeded`. Any other outcome (`failed`, `skipped`) causes the workflow to fail, even though execution reached the exit.
|
|
|
|
This means `allow_partial=true` on a goal gate node lets the gate pass even if the node exhausted its retries — the promoted `partially_succeeded` outcome counts as passing.
|
|
|
|
See [Goal gates](/execution/failures#goal-gates) for retry target resolution and failure behavior.
|
|
|
|
## Outcome in edge conditions
|
|
|
|
The four externally-visible statuses can be used in edge `condition` expressions via the `outcome` key:
|
|
|
|
```dot
|
|
gate -> deploy [label="Pass", condition="outcome=succeeded"]
|
|
gate -> fix [label="Fix", condition="outcome=failed"]
|
|
gate -> review [label="Partial", condition="outcome=partially_succeeded"]
|
|
gate -> skip [label="Skipped", condition="outcome=skipped"]
|
|
|
|
// Common pattern: treat partial as passing
|
|
gate -> deploy [condition="outcome=succeeded || outcome=partially_succeeded"]
|
|
gate -> fix [condition="outcome=failed"]
|
|
```
|
|
|
|
See [Transitions](/workflows/transitions) for the full edge selection logic and operator reference.
|