> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Sessions, Runs, approvals, and streaming

> **Availability:** The AutoMCP production service is not yet deployed. This page and its examples describe the committed v1 contract for integration planning; requests to the API URL will not succeed until the runtime is released.

A session belongs to one application and customer user. Each session permits one active Run at a time. Text turns and tool execution are durable Runs with states including queued, running, awaiting approval, awaiting cost evidence, awaiting settlement, succeeded, failed, canceled, and `outcomeUnknown`.

`WatchRun` provides Connect server-streaming status snapshots and `StreamRunText` provides text events. If a connection drops, the Run continues. Save the latest emitted event `sequence` and reconnect with it as `afterSequence` to receive newer events; a complete replay of every earlier delta is not promised. Duplicate mutation IDs with identical payloads return the original result; changed payloads conflict.

Cancellation is best effort. Reads and calls with an explicitly mapped upstream idempotency key may receive bounded retries. An ambiguous non-idempotent customer call stops as `outcomeUnknown`; AutoMCP does not claim the effect was undone, force a replay, or compensate it. Verify the customer API’s state and start a new Run with a new mutation ID and, when required, a new approval.

Every non-read-only customer API call requires a fresh hosted approval by the bound user. The approval shows the immutable app/version, tool and version, exact destination, and actual arguments, and binds the decision to the user, Run, argument digest, expiry, and resource version. Rejection, expiry, cancellation, changed arguments/version, stale state, or lost authority prevents execution. Voice statements, model output, MCP tokens, backend keys, administrators, and operators cannot substitute for browser approval.

### Open an approval screen

A browser token with `approvals:read` calls `HostedService.CreateHostedApprovalLink`
with its Run ID and opens the returned one-use URL. The hosted page creates a
customer session and a short-lived approval credential bound to that Run and
user. MCP users reach the same page from their authenticated customer login.
Neither path requires administrator access. Review the arguments, trusted user headers, and destination,
then explicitly approve or reject. A regular browser token cannot directly make
the decision, even if its grant includes `approvals:write`. Trusted headers show
the customer values injected by the server; Secret credential values are hidden.

### Jobs, artifacts, and expiration

Each Run has an AutoMCP-owned `jobId`. `PlatformService` lists Jobs and completed
Artifacts for the same user; `DownloadArtifact` requires authenticated payload
access and returns bytes directly. It never issues a public storage URL. Final
text and artifacts are available after verified cost settlement. A failed or
canceled Run can still have incurred costs and completed tool effects.

Reconnect status streams with the last sequence; the initial snapshot reflects
the latest Run state. Text deltas are provisional, and a final text event may
have an empty delta because the complete response is read with `GetRunPayload`.
Sequences belong to the Run, so retain separate cursors for state and text.
Session and payload retention are finite; an expired payload cannot be recovered
by reopening a stream. Metadata and pending accounting can outlive its contents.