Intent Preview

The agent restates what it understood and the guesses it made, before any work starts — one click when it's right, one correction when it isn't.

Installation

bash

npx shadcn@latest add @pixeldosa/intent-preview

Requires `cn` at `@/lib/utils`. Use it only where misreading the request would be costly — long runs, side effects, ambiguous scope. On cheap, reversible actions it is friction.

Usage

"use client";

import { IntentPreview } from "@/components/ui/intent-preview";

<IntentPreview
  interpretation="Reconcile this quarter's flagged invoices and draft a summary of the root cause."
  assumptions={[
    { id: "dataset", label: "Dataset", value: "Q3 Revenue Final.xlsx", options: ["Q3 Revenue.xlsx"] },
    { id: "audience", label: "Summary for", value: "Finance team", options: ["Leadership"] },
  ]}
  boundaries={["Change any invoice", "Send the summary without asking first"]}
  onStart={(values) => run(values)}
  onRephrase={() => focusPrompt()}
/>

Why it exists

An agent interprets a request before it plans anything. If it misreads you there, every later step builds on the mistake. The cheapest correction in an agentic run is the first one — this puts it where it costs one click.

Features

Guesses arrive filled in. When they're right, confirming is one click. When one's wrong, you correct that one in place — no rewriting the prompt.
Changes are visible. The button becomes "Start with changes" once anything was corrected, so the confirmation carries information rather than ceremony.
Boundaries are part of intent. "I won't send the summary without asking first" is often the thing people most want to know before a run.
Holds still — it's your turn.

Intent Preview vs Agent Ask

Question	Agent Ask	Intent Preview
Can the agent proceed without you?	No — it's missing something	Yes — on its best guess
What you do	Supply the answer	Confirm or correct the guesses
Cost when things are fine	Always an answer	One click

Examples

Only where misreading is expensive. A cheap, reversible action doesn't need it:

const needsPreview = task.estimatedSteps > 3 || task.hasSideEffects;

Followed by a plan, for runs where both the reading and the steps matter:

{phase === "intent" ? <IntentPreview {...intent} onStart={() => setPhase("plan")} /> : null}
{phase === "plan" ? <AgentPlan steps={plan} onRun={execute} /> : null}

Props

Prop	Type	Description
`interpretation`	`string`	Required. The request restated in one plain sentence.
`assumptions`	`{ id, label, value, options? }[]`	The guesses that filled gaps. `options` makes one correctable.
`boundaries`	`string[]`	What the agent will deliberately not do.
`onStart`	`(values) => void`	Required. Receives the confirmed values.
`onRephrase`	`() => void`	Back to the prompt.
`onCancel`	`() => void`
`startLabel`	`string`	Defaults to `"Start"`.
`headingLevel`	`2 \| 3 \| 4 \| 5 \| 6`	Heading level, so the component fits your page's outline. Defaults to `3`.

Accessibility

A labelled <section> whose name is the interpretation itself.
Assumptions are a <dl>; corrections use Select, a combobox named after the assumption ("Dataset") that announces its current value, with keyboard, typeahead and touch-sized options.
Actions are a keyboard toolbar.

When not to use

A question the agent can't guess the answer to is Agent Ask. The steps it will take are Agent Plan. And don't put this in front of cheap, reversible actions — confirmations nobody needs train people to click through without reading.

why it's built this way

Engineering Notes

Built from the model-side view of how agentic runs fail: interpretation happens before planning, and an early misreading compounds through every step that follows. Surfacing the interpretation in one sentence, together with the specific guesses that filled gaps in the request, moves correction to the single point where it is nearly free. Two decisions keep that from becoming friction. First, assumptions arrive pre-filled with the agent's best guess, so the common case — the guess is right — costs one click, and the start label changes to 'Start with changes' only when something was corrected, so the confirmation carries information rather than ceremony. Second, correction happens in place through a Select of alternative readings rather than by rephrasing the whole request, which is both faster and more precise. Boundaries ('I won't…') are included because what an agent will not do is part of its intent and is the thing users most want to know before a run with side effects. It is deliberately distinct from Agent Ask: Ask blocks on missing information the agent cannot guess, whereas Intent Preview is for requests the agent could act on immediately, where acting on a wrong guess would be expensive.

how it moves, and when it doesn't

Motion Notes

Still, by design. This is a user-turn surface under the system's turn-taking grammar, so nothing moves or shimmers while it waits — the absence of motion is the signal that nothing proceeds until the user confirms. Motion is limited to the shared colour transition on hover and focus at `--pd-duration-instant`, inherited from the composed AI Action Toolbar and Select, and the brief fade of a correction list as it opens; both drop away under prefers-reduced-motion. Entrance motion belongs to whatever surface reveals the preview, not to the component.

Reconcile this quarter's flagged invoices and draft a summary of what caused the duplicate-payment warning.