Modes
Mutating calls name a mode and the server does not default to live work.
A Mode tells Dreamstate whether you want to inspect a capability, preview it against your workspace, or execute it. Use a mode whenever a capability can change workspace data, call a provider, spend Credits, or reach someone outside the workspace. Architect, the CLI, MCP, and REST send the same mode value to the same execution contract.
Modes sit after discovery, not before it. First search the tool catalog, fetch the exact capability schema, and then choose a supported mode. After live work starts, use Runs to read the durable result rather than submitting the same operation again.
Choose the execution mode
The server does not infer live execution for a mutating call. The fetched capability contract decides whether a particular mode is available, so a read can have different mode behavior from a create, send, or publish action. Use the smallest mode that answers the question you have now.
| Mode | What it does | What it does not do |
|---|---|---|
smoke_test | Static schema and policy inspection | Writes nothing and creates no audit entry. |
dry_run | Validation and preview against workspace state | Makes no business write, provider spend, or outward action. |
live | Capability execution | Performs the operation described by the fetched contract. |
Use smoke_test when you need to inspect the static schema and policy before touching workspace state. Use dry_run when a preview needs the real selected workbook, Worksheet, sender, or other workspace context. Use live only when the returned contract and preview describe the result you intend to create or deliver.
A dry run is not a generic simulation of every downstream provider. It validates and previews from the available workspace state, while avoiding business writes, provider spend, and outward actions. Read the preview as a decision record, then correct its inputs before changing to live mode.
Discover the contract, then preview
Ask Architect for an outcome, not an assumed capability id. Architect uses the catalog search control, fetches the returned contract, and chooses the capabilities that match the request. The same pattern applies in every surface: search identifies candidates, get supplies the current input schema, and run receives the selected mode.
For example, creating a Workbook is data work. The example below asks for a preview of a Workbook called October prospects. In the app, compare the returned preview with the intended name and destination before changing the call to live mode.
Keep the parameters from a successful preview when you move forward. If the task is paid, the execution response can return an estimate instead of starting live work. That response is information about this request, not proof that a later request with changed inputs has the same price or effect.
Review cost and outward effect
Credits are the spend control for live work. When a paid live call needs a price, Dreamstate returns quote_required with its estimate. Rerun the same call with unchanged parameters, the returned quote binding, and a max_credits ceiling that covers the estimate.
Check the capability description and cost policy that discovery returned before you do this. A capability can be free, can use an action cost, or can have dynamic cost behavior. Do not substitute a ceiling copied from another capability, because the request and its estimate are part of the live execution contract.
Architect can ask about a sensitive effect as part of its judgment, but the operating control is still the requested mode and credit ceiling. In the CLI, retain the output with the run identifier. In the app, follow the returned web_url when it is present, while keeping JSON identifiers as the source of truth.
Use live mode intentionally
Live mode executes the selected capability, but it does not turn a draft into every later state automatically. For example, a Sequence can be drafted, validated, published, enrolled, started, delivered, and replied to as separate stages. Review Sequences and enrollment before treating a completed create as delivery.
Live work can return immediately or create durable work for later inspection. When the result names a run, open the run rather than guessing from the original request whether all steps have completed. A state-bearing result can also include a direct app URL, which helps you inspect the object without replacing its JSON id in follow-up calls.
Connections affect execution, not preparation. You can build a draft when the required LinkedIn account, mailbox, or provider is not connected, but a contract that needs that connection can refuse the later live step. Keep the draft, resolve the connection in the relevant app settings, and then fetch the current contract again before retrying.
When it goes wrong
A mutating request without a mode returns mode_required. Retry with smoke_test, dry_run, or live, after checking that the fetched schema supports the choice. The server explicitly says that it does not default to live mode.
If the service returns quote_required, do not alter fields and assume the old quote still applies. Preserve the parameters, use the returned quote information, and provide the matching max_credits value for the rerun. Search and get again when the capability contract was delivered on another turn.
A root capability attempted through an API key can return destructive_approval_required. Root actions change workspace ownership, reach, money, keys, credentials, or similar protected settings, so they run only from the current signed-in owner session with their required idempotency handling. This is a security rule for owner actions, not a mode or credit rule for ordinary execution.