Docs

Service requests

Service-defined reviews, browser approval and execution recovery.

A service request lets an assistant prepare an action for a person to review. The hosted flow records the review, waits for an account owner's browser approval, and executes the exact action that was reviewed. Local-host service requests are not implemented.

Use a request

Call a service's request builder through MCP or crab call. For example, on an accessible Outbox deployment:

crab call you/outbox review '{"input":{"from":"[email protected]","to":["[email protected]"],"subject":"Report","text":"The report is ready."}}'

The response contains a code and url. MCP also returns a resource_uri; read that authenticated resource for the request state and execution result. Share the link with the person. Creating a request does not complete its action. The page shows the originating service, the account it acts for, the service-authored review and any price per execution attempt.

An owner of the requesting account signs in through the browser to approve or decline. API keys can prepare and read their account's requests; they cannot approve them. Review content and results require account access even when someone knows the link.

Wait for the outcome:

crab request CODE --wait --json

A completed service request contains its action's result. A failed request retains the failure and the reviewed action. Reopen its page to resume the same request. A request awaiting an outcome can also be resumed after an interrupted host execution. Duplicate approvals do not start concurrent executions.

Requests permit new execution attempts for 30 minutes after creation. Declined and expired requests cannot start an action. Check an existing outcome before creating a replacement after an uncertain failure. A changed service image or action price requires a new review.

Define a request builder

Mark a Rust tool #[tool(request)] and return berm_lang::abi::requests::Review<T>:

Field Meaning
title One line, 1–160 bytes
body The review as Markdown, 1–8000 bytes
tool An account-callable action in the same service
input The immutable action input, at most 16384 serialized bytes

The builder prepares the review and must not perform the requested action. It is read-only for database writes, logs and wakes. Its content must accurately describe its action input. The host sanitizes Markdown and supplies the service and account attribution.

The action receives {"request":"CODE","input":T}. berm_lang::abi::requests::Execution<T> describes that object. The action must enforce its own caller policy and use the request ID to deduplicate retries. An argument object is not proof of authorization. Hosted execution uses the requesting account's owner identity after browser approval; no session token is handed to the service.

The Outbox source is a complete example using the existing Resend library, owner-only execution and a stable provider idempotency key.

HTTP and SDK

POST /services/OWNER/NAME/request/TOOL creates a request from a declared builder. The body is the builder's normal argument object. The SDK exposes this as Client::ask_service. Calling that builder through the normal hosted tool endpoint or MCP also returns a request link.

Read its state at GET /requests/CODE. The requesting account's owner approves with POST /requests/CODE/approve or declines with POST /requests/CODE/decline, using a browser session. A repeated approval of a completed request returns its recorded outcome.

The host stores the review and decision. The service owns its business policy, effects and retry safety. Approval does not authorize unrelated actions or later changes to the reviewed input.