fabro/docs/public/agents/outputs.mdx

---
title: "Outputs & Artifacts"
description: "How Fabro captures agent responses, tracks file changes, and collects test assets"
---

When an agent or prompt node finishes, Fabro captures its response text and produces an **outcome** that feeds into context, transition logic, and downstream nodes. Fabro also tracks every file change per stage, offloads large outputs into content-addressed blob storage, and automatically collects test artifacts like screenshots and reports.

## Response capture

After an agent or prompt node completes, Fabro captures the full response text and persists it to `stages/{node_id}@{visit}/response.md` in metadata snapshots and `fabro dump` output. It also writes the final outcome (status, context updates, routing directives) to `stages/{node_id}@{visit}/status.json`.

## Context updates

Every agent and prompt node sets three context keys from its response:

| Key | Value |
|---|---|
| `last_stage` | The node ID of the stage that just completed |
| `last_response` | The response text, truncated to the first 200 characters |
| `response.{node_id}` | The full response text |

These keys are available to downstream nodes via the [context](/execution/context). The `last_response` key provides a quick preview, while `response.{node_id}` preserves the complete output for nodes that need it.

```dot
plan -> implement -> review -> exit

// In the review node's prompt, you can reference prior outputs:
// The context key response.plan contains the full plan text
// The context key response.implement contains the full implementation
```

## Routing directives

Agent and prompt nodes can influence which edge is taken after they complete by including a JSON object with routing fields in their response. Fabro scans the LLM output for the **last** JSON object containing any recognized routing field:

```json
{
  "outcome": "fail",
  "failure_reason": "tests failed",
  "preferred_next_label": "fix",
  "suggested_next_ids": ["implement", "review"],
  "context_updates": { "tests_passed": true, "coverage": 85 }
}
```

| Field | Effect |
|---|---|
| `outcome` | Sets the node status: `success`, `fail`, `partial_success`, `retry`, or `skipped` |
| `failure_reason` | When `outcome` is `fail`, provides a structured failure message |
| `preferred_next_label` | Matched against edge labels to select the next node |
| `suggested_next_ids` | Ordered list of preferred target node IDs |
| `context_updates` | Key-value pairs merged into the run context |

### How extraction works

Fabro finds all balanced `{...}` JSON objects in the response text, parses each one, and uses the **last** object that contains at least one recognized field (`preferred_next_label`, `outcome`, `failure_reason`, `suggested_next_ids`, `context_updates`). The JSON can appear anywhere in the response -- inside a fenced code block, inline with natural language, or at the end.

```markdown
I've reviewed the code and found several issues that need fixing.
The test coverage is below the threshold.

{"preferred_next_label": "fix", "context_updates": {"coverage": 72}}
```

JSON objects without recognized fields are ignored.

### Fallback: status.json file

If no routing directives are found in the response text, Fabro checks whether the agent wrote a `status.json` file into the sandbox working directory. If the file exists, Fabro extracts routing directives from it using the same logic. This is useful for agents that write structured output to files rather than including JSON in their response text.

Response text directives always take priority -- `status.json` is only read as a fallback when the response contains no recognized routing fields.

If neither source provides routing directives, the transition falls through to condition matching, unconditional edges, or weight-based tiebreaking as described in [Transitions](/workflows/transitions).

### Instructing the agent

Fabro does not automatically instruct agents to emit routing JSON. You must include instructions in your prompt:

```dot
review [
    label="Review",
    shape=tab,
    prompt="Review the implementation. If changes are needed, \
        respond with: {\"preferred_next_label\": \"fix\"}. \
        If everything looks good, respond with: \
        {\"preferred_next_label\": \"approve\"}."
]

review -> fix     [label="Fix"]
review -> approve [label="Approve"]
```

## Output logging

Fabro writes several files per stage to `stages/{node_id}@{visit}/` in metadata snapshots and `fabro dump` output:

| File | Contents |
|---|---|
| `prompt.md` | The assembled prompt (preamble + expanded prompt text) |
| `response.md` | The full LLM response text |
| `status.json` | The outcome: status, context updates, routing directives, usage stats |

These files are written for every agent and prompt node execution, including retries. Use them for debugging unexpected agent behavior or verifying that routing directives were extracted correctly.

## File tracking

Fabro records which files each stage touches. When an agent calls `write_file` or `edit_file`, Fabro tracks the file path. When using a CLI-based agent backend, Fabro snapshots the Git working tree before and after execution and diffs the results.

The tracked paths are stored as `files_touched` on the stage outcome:

```json
{
  "status": "success",
  "files_touched": ["src/main.rs", "tests/api_test.rs", "README.md"]
}
```

### Where files_touched appears

| Location | How it's used |
|---|---|
| `StageCompleted` event | Emitted with `files_touched` in the event stream and surfaced by `fabro logs` / exported event streams |
| Preambles | Listed under each completed stage so downstream agents know what changed |
| Retros | Included per-stage and aggregated across the full run |
| `status.json` | Written to the stage's logs directory after each node completes |

### How tracking works

For the **API backend**, Fabro subscribes to agent session events. When a `ToolCallStarted` event fires for `write_file` or `edit_file`, Fabro records the `file_path` argument as pending. When the corresponding `ToolCallCompleted` arrives without an error, the path is confirmed as touched. Failed tool calls are discarded.

For the **CLI backend**, Fabro takes a different approach: it runs `git diff --name-only` and `git ls-files --others --exclude-standard` before and after the agent session, then computes the difference. Any files that appear in the "after" snapshot but not "before" are recorded as touched.

## Artifact offloading

When a stage produces a large context value -- an LLM response, command output, or any context update -- Fabro automatically offloads it into a global content-addressed blob store instead of leaving the full value inline in durable context.

### How offloading works

After each node completes, Fabro checks every context update. If the serialized JSON of a value exceeds **100KB**, it is stored once by SHA-256 hash and replaced with a durable blob ref:

```
response.plan  -->  blob://sha256/2cf24dba5fb0...
command.output -->  blob://sha256/a4f3c1d9c2e1...
```

Values under 100KB remain inline.

Checkpoints, checkpoint-completed events, forks, and resumes persist these `blob://` refs, not host-specific file paths.

### Preamble rendering

When Fabro builds a [preamble](/execution/context#preamble-construction) for a downstream stage, it first materializes any blob refs into execution-local files and then renders a reference instead of inlining the full content:

```markdown
## Completed stages
- **plan**: success
  - Model: claude-sonnet-4-5, 12.4k tokens in / 3.2k out
  - Files: src/main.rs, tests/api_test.rs
  - Response: See: /path/to/runtime/blobs/<blob_id>.json
- **test**: success
  - Script: `cargo test 2>&1 || true`
  - Stdout: See: /path/to/runtime/blobs/<blob_id>.json
```

This keeps preambles concise while still giving agents a path to read the full output if needed.

## Git storage

Large offloaded context values are not stored on the Git [metadata branch](/execution/checkpoints#metadata-branch). The metadata branch keeps checkpoint JSON and stage metadata; blob payloads live in the durable blob store and are referenced by `blob://sha256/...`.

Captured stage artifacts such as screenshots, videos, reports, and traces still use the artifact store and metadata export paths described below.

## Remote sandbox syncing

For remote sandboxes (Docker, Daytona), execution-time file access happens inside the sandbox filesystem.

- Blob refs are materialized into `{working_directory}/.fabro/blobs/{blob_id}.json`
- Explicit non-blob `file://` refs keep the existing copy-on-demand behavior and are copied into `{working_directory}/.fabro/artifacts/{filename}` when needed

In both cases, downstream handlers and agents continue to consume ordinary `file://` pointers during execution.

<Note>
For local sandboxes, syncing is a no-op since the agent can already access the host filesystem directly.
</Note>

## Automatic asset capture

After each node executes a command, Fabro automatically scans the sandbox for test artifacts — screenshots, videos, reports, and traces — and copies any new or changed files to the run's directory. This happens without any agent or workflow configuration.

### How asset capture works

1. **Before** the command runs, Fabro takes a baseline snapshot of known artifact paths in the sandbox
2. **After** the command completes, Fabro re-scans and diffs against the baseline
3. Files that are new or modified since the command started are downloaded to the stage's artifact directory

Only files modified after the command started are collected. Files that match the baseline fingerprint (same size and mtime) are skipped. Individual files over 10 MB and total collections over 50 MB are also skipped.

### What gets captured

Fabro looks for files inside these directories:

| Directory | Typical contents |
|---|---|
| `playwright-report/` | Playwright HTML reports |
| `test-results/` | Playwright screenshots, videos, and traces |
| `cypress/videos/` | Cypress test recordings |
| `cypress/screenshots/` | Cypress failure screenshots |

And files matching these filename patterns anywhere in the tree:

| Pattern | Typical contents |
|---|---|
| `junit*.xml` | JUnit XML test reports |
| `*.trace.zip` | Playwright trace archives |

Tool caches and dependency directories (`node_modules`, `.cache/ms-playwright`, `.yarn/cache`, etc.) are excluded from scanning.

### Asset storage layout

Collected assets are written to the run's directory, organized by node and retry attempt:

```
~/.fabro/scratch/{run_id}/
  cache/
    artifacts/
      files/
        {node_slug}/
          retry_1/
            test-results/
              screenshot.png
              video.webm
```

## Observability

Outputs and artifacts appear in several observability surfaces:

| Surface | What's reported |
|---|---|
| `StageCompleted` event | `files_touched` list for the stage |
| `WorkflowRunCompleted` event | `artifact_count` -- total number of offloaded artifacts across the run |
| [Retros](/execution/retros) | Per-stage `files_touched` and aggregate `files_touched` across all stages |
| [Preambles](/execution/context#preamble-construction) | File list and artifact pointer references for completed stages |
| Stage logs | `status.json` in each stage's run directory contains the full outcome including `files_touched` |