Spend caps and budgets
Paid work can use a quote and a maximum credits ceiling.
Spend caps set the maximum Credits a fetched live run may consume. Use a cap after you have inspected the exact capability contract and its estimate, especially when a provider-backed operation can require a quoted price.
The cap belongs to the execution envelope, not the capability's params object. That keeps the whole-run limit visible while the fetched capability schema continues to define only its own inputs. Read Credits and billing for credit classes and Tool catalog for discovery and current-contract rules.
Execution controls for a priced run
A run request separates capability parameters from execution controls. Parameters describe the particular action, such as a worksheet, provider, recipient, or content artifact. Mode, the credit ceiling, quote binding, and tool-turn token describe how the gateway may execute the fetched capability. Moving a ceiling into params changes neither the run policy nor the capability schema.
The fetched contract is the authority for whether a live ceiling is required. A client should not attach a random maximum to a read-only capability or infer that a similarly named capability uses the same price. The descriptor exposes the action policy, cost policy, credit class, scopes, supported input, and asynchronous policy for the capability actually selected in this workspace.
Mode is required for every mutating call. smoke_test inspects schema and policy without a write or audit entry. dry_run validates against real workspace state without business writes, provider spend, or outward action. live executes the fetched contract. Some capabilities support only dry_run and live, so always use the returned supported-mode list.
The tool-turn token ties the run to the contract delivered in discovery. It is not a credential, a quote, or a spend authorization. It proves that the caller is running a capability the current turn already delivered. A run without a delivered contract is refused with capability_not_fetched and a repair.
| Field | Type | Required | Meaning |
|---|---|---|---|
mode | Execution enum | Mutating calls | The explicit smoke_test, dry_run, or live mode supported by the fetched contract. |
max_credits | Nonnegative number | When a live credit ceiling is required | The execution-wide credit ceiling beside params. |
quote_hash | Returned quote binding | Quoted priced live call | The quote minted for the same live request and bound by the server. |
tool_turn_token | Turn token | When supplied by discovery | The current contract-discovery binding, not a credential or cap. |
Reuse the quoted request
A live capability that needs a price returns quote_required with an estimate. The repair is to repeat the same live request with unchanged parameters and a max_credits ceiling. The server binds the quote to that tool turn, so a caller does not generate a quote hash or copy one from an unrelated request.
The ceiling limits that Dreamstate run. It is not the person's yes. When the server requires a yes, that is the paid-run consent rule. The ceiling does not change the third party's own billing relationship. A provider connection can still be required, and a provider-backed live action can still have an external effect according to its action policy. Check both before treating a quote as sufficient evidence that the call is ready.
Keep parameters unchanged when accepting a quote because a different worksheet, recipient, provider, or request body is a different execution decision. If the task needs a different target or amount, start from the fetched contract again and obtain a new estimate. A ceiling is not a way to turn a changed request into the earlier priced request.
Architect should first explain the estimate and the intended ceiling, then run the original request only when the user has already asked for that effect. Above the server's row or provider-spend limit, follow the paid-run consent rule. Owner actions have a separate security rule.
Run a dry run for this enrichment job. If it returns a quote, explain the estimate and rerun the unchanged request live with a maximum of 200 credits. Report the final result or machine-readable refusal.Credit classes and effects
The catalog has three credit classes, and only these values appear in the customer surface. A class tells a caller how the catalog categorizes cost, but it does not tell the caller whether the effect is a read, a reversible workspace change, an external send, a publish, an enrollment, or an activation. Read the action policy together with the cost policy.
A read-only capability can be free, but a free operation can still have a policy or state consequence that needs review. A dynamic or action-priced capability can be synchronous or asynchronous. The descriptor's asynchronous policy tells the client whether it should look for a run identifier and use run reads or events before judging the work terminal.
Use the returned output shape to record evidence. State-bearing results can include a web_url to the corresponding object in the app, but JSON ids remain the source of truth for later reads. A lost client connection does not prove that no credit-consuming run was admitted.
| Credit class | Meaning |
|---|---|
free | A catalog credit class for an operation with no credit charge. |
action | A catalog credit class for action-priced work. |
dynamic | A catalog credit class whose charge is determined by its contract and run. |
Caps are not owner approval
A spending ceiling is not a root-action approval. Root actions change who owns or can reach the workspace or its money, including billing, seats, API keys, integrations, credentials, webhooks, and ownership changes. They require a signed-in session, fresh approval at the applicable tier, and an Idempotency-Key, never an API key alone.
The owner-action security check is separate from ordinary capability cost. A run can have a credit ceiling and still need the owner path because it changes an external credential or workspace authority. Conversely, a quoted provider-backed action can need a maximum-credit ceiling without being a root action. Keep these two controls distinct in client code and operator explanations.
Before a live run, check the capability's effects, provider readiness, sender policy, recipient state, and mode. A ceiling only controls potential Dreamstate credit use. It cannot correct a suppressed recipient, a missing sender, a missing provider connection, a required idempotency key, or an invalid request schema.
When it goes wrong
If a mutation returns mode_required, choose a mode supported by the fetched contract. Do not rely on the server to select live. If a caller cannot decide between dry_run and live, run the static or workspace-state validation first and preserve the returned evidence for the later decision.
If live work returns quote_required, retain the same capability and parameters, then repeat the request with the estimate's bound quote and an intended maximum-credit ceiling. If the user wants different parameters, do not reuse the quote: rediscover the contract and get the estimate for the new work.
If the gateway returns capability_not_fetched, search or get the exact capability in the current tool turn. If the token is expired or the catalog changed, start fresh discovery. The ceiling does not make an unfetched or stale capability runnable.
If the action needs a connection, sender, or recipient field, repair that condition in its owning pack before retrying a paid live call. If the action is a root action, use the signed-in owner flow and idempotency key. Check the final run result or receipt before issuing another request after a network interruption.