Act best practices

​

Pin the selected capability

Start from the exact capabilityId and capabilityRevision the user reviewed. Do not silently rerun Search or swap providers when execution begins.

​

Preserve durable identifiers

• Store actionId as soon as Start action returns.
• Create one requestId per logical mutation.
• Reuse that requestId only when retrying the identical mutation.
• Use a new requestId for a different update, approval decision, or stop request.

​

Render the server state

Treat status, actionRequired, availableActions, interaction, and webLink as the current source of truth. Never replace a nonterminal status with optimistic completed copy.

​

Keep authority explicit

An update supplies information; it does not approve work. A connection authenticates access; it does not grant standing spending authority. An approval applies only to the exact revision and digest the user reviewed.

​

Keep sensitive work in the browser

Open only Darwin’s first-party webLink for connection or payment interactions. Provider authorization URLs, payment credentials, API keys, and raw private scopes do not belong in prompts, client logs, or Action request bodies.

​

Poll responsibly

Use bounded exponential backoff, pause when the page is not active when appropriate, and stop polling on completed or stopped. Resume from the stored actionId after a client restart.