State Diff
Structured before/after view of state mutations.
Answers: Execution Amnesia, Unpredictable Outcomes, L2 Collaborative.
Install
npx ax-depute@latest add state-diffpnpm dlx ax-depute@latest add state-diffyarn dlx ax-depute@latest add state-diffbunx ax-depute@latest add state-diffOverview
State Diff provides mutation visibility, turning abstract JSON payloads into human-readable proof of what changed. In high-stakes environments, humans cannot simply trust an agent's summary — they need exact before-and-after deltas.
Basic Usage
<StateDiff
title="Configuration Changes"
entries={[
{ field: 'max_instances', type: 'modified', before: '2', after: '5' },
{ field: 'region', type: 'added', after: 'us-east-1' },
{ field: 'legacy_mode', type: 'removed', before: 'true' },
]}
/>Solution Patterns
Place StateDiff inside a ToolTrace or a PlanCard to show exact intended or completed mutations. Pair it with BindingApproval so the person can see the mutation they are confirming. The signature, if any, comes from your backend.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | — | Title of the diff (e.g. "Database Mutation") |
description | string | — | Optional context |
entries | DiffEntry[] | — | Flat list of diff entries |
groups | DiffGroup[] | — | Grouped entries (takes precedence over entries) |
hideUnchanged | boolean | false | Hide unchanged fields |
defaultCollapsed | boolean | false | Start collapsed |
timestamp | string | — | Mutation timestamp |
sourceId | string | — | Tool call/step ID |
Design rationale
Why hideUnchanged? Massive JSON payloads distract from the actual mutation. Highlighting only the delta reduces cognitive load and focuses human attention exactly where the risk is.
Why structure over syntax highlighting? A human cannot easily parse a raw git-style diff of a minified JSON object. Transforming the delta into a structured, dot-notated table makes the blast radius legible to non-engineers.