# AIDE interface 1.0.0

Owned by **softmax.com**. The authoritative contract is
[asyncapi.json](https://softmax.com/docs/static/aide/1.0.0/asyncapi.json).
It uses AsyncAPI 3.0, JSON Schema, and JSON-RPC 2.0. This document specifies behavioral rules beyond message shape.
The [explorer](index.html) presents the same contract; [examples](examples.json) illustrate exchanges.

## Version and discovery

The stable entry point is `https://softmax.com/docs/aide`.
Each version has its own directory. Released versions are immutable; connections select an exact version.
While 1.0.0 is pre-release, additive changes are made in place in 1.0.0: new methods, optional fields, and new enum members that earlier producers never emit.
Frontends and backends must ignore unknown notifications and tolerate absent optional fields.
Frontends and the canary send additive methods or parameters only after a runtime that accepts them is deployed. Incompatible behavior requires a new major version.
`jsonrpc: "2.0"` names the envelope standard, not the AIDE version.
There is no capability-discovery method. Every defined request may return `unsupported`.

`asyncapi.json` contains all schemas, including OpenAI message and chunk definitions pinned to openai-python 2.54.0.
Its embedded schemas use the common JSON Schema Draft 7/2020-12 keyword subset supported by the AsyncAPI Schema Object.
References resolve inside the document. [Source provenance](source.json) and the [OpenAI SDK third-party license](OPENAI-LICENSE.txt) accompany the release.
That license accompanies the bundled OpenAI schemas; it does not license the Softmax API.

## Envelopes and validation

Requests: `{jsonrpc:"2.0", id:UUID, method:string, params:object}`.
Success: `{jsonrpc:"2.0", id:UUID, result:<method-specific value>}`.
Error: `{jsonrpc:"2.0", id:UUID|null, error:{code:integer,message:string,data?:object}}`.
Notifications: `{jsonrpc:"2.0", method:string, params:<typed body>}`, without an ID or response.
Use one JSON object per delivery. Batches are outside this version.

The schema `Request` is a closed union over method names and their parameter schemas.
`Notification` is the corresponding notification union. Empty `{}` parameters are intentional for parameterless requests.
Application objects reject extra fields except OpenAI objects, explicitly defined maps, and peer-defined objects (`chat.send.context` and the `data` of `surface.event` and `surface.act`).

The relay validates both directions: envelopes, method, allowed sender, parameters, nested objects, sizes, and replies.
It correlates each response ID with a pending request and checks that method's result schema and target/resource identity.
Unsolicited replies are rejected. Invalid replies are withheld and reported as `unavailable` with `outcome:"unknown"`.
Invalid notifications are dropped and logged, never answered.
The relay uses its selected release; payload-supplied schema URLs never control validation.

AsyncAPI describes the **relay's viewpoint**: `receive` means the relay receives a message, and `send` means it sends one.
Both connections describe the same logical interface. Their operation tags also name Frontend → AIDE or AIDE → Frontend.
Each operation's `reply.messages` identifies its typed success and the shared error message.
Identical cancellation success shapes share one message definition. The request ID determines the corresponding method.
Validation proves shape and routing; recipients implement actions and own their state.

## Public surface

| Direction | Requests | Notifications |
| --- | --- | --- |
| Frontend → AIDE | `session.open`, `session.page`, `chat.send`, `state.list`, `state.get`, `chat.history`, `chat.events`, `task.cancel`, `chat.cancel`, `input.respond`, `surface.event`, `clarification.response` | `browser.changed` |
| AIDE → Frontend | `browser.snapshot`, `browser.act`, `surface.act`, `clarification.request`, `policy.create`, `policy.update`, `policy.list` | `state.changed`, `chat.message`, `chat.chunk`, `chat.event`, `chat.finished` |
| Relay → Frontend | — | `aide.presence` (relay-owned) |
| Relay → AIDE | — | `frontend.closed` (relay-owned) |

Workspace resources are exactly **sessions, tasks, goals, and requests**, discriminated by `resource`.
Their authoritative object schemas are `Session`, `Task`, `Goal`, and `ChatRequest` in AsyncAPI's `components.schemas`.
Messages are read through `chat.history`; a request's progress through `chat.events`. Work cards can render tasks; they are not another resource.
No intents, runs, submissions, beliefs, execution ledgers, or arbitrary internal tables are public.
Workspace provisioning and hosting remain separate platform operations.

## Reads are authoritative; notifications are hints

Every state a frontend shows is readable on demand from durable workspace state:
sessions, tasks, goals and requests through `state.get`/`state.list`, messages through `chat.history`, and progress through `chat.events`.
These reads give the same answer after a reload, a reconnect, a backend restart, or workspace sleep.
Notifications are a fast path on top: they show changes sooner and tell the frontend when to read.
No notification is the only source of anything. AIDE does not replay notifications, and recipients may miss them.
Frontends ignore notification methods they do not know.

Every notification carries the cursor of the read that returns the same information:

| Notification | Cursor | Read on a gap |
| --- | --- | --- |
| `chat.event` | `event.attempt`, `event.seq` | `chat.events` after the last applied cursor |
| `chat.chunk` | `cursor` `{attempt, seq}` | `chat.events` after the last applied cursor |
| `chat.message` | `sequence` | `chat.history` with `after_sequence` |
| `chat.finished` | `cursor`, `revision` | `state.get` resource `requests` |
| `state.changed` | item `revision` | `state.get`/`state.list` of that resource |

Every record (`Session`, `ChatRequest`, `Task`, `Goal`) carries `revision`, the workspace store sequence of its latest change.
It is durable: it survives backend restarts and never decreases. Install a pushed record only when its `revision` is newer than the installed one.
When an item carries `revision`, apply it by that item revision and ignore the collection `previous_revision` chain.
`epoch` is a stable workspace identity; a changed epoch means the workspace's state was reset, so refetch everything.
The collection-level `revision` and `previous_revision` of `state.changed` remain as specified below until the per-item form is required.

After a reload or reconnect, read the session (its `requests` show every open request and recent outcomes), then `chat.history`, then `chat.events` for each open request from the last applied cursor.
A request's outcome stays readable from its record; never infer success from silence or from absence in `active_request_ids`.
Notifications from producers that predate these cursors omit them; treat each such notification as a prompt to read.

`aide.presence {present}` is a relay-owned notification: the relay sends it when the workspace backend connects or goes away, and peers never send it.
On any `aide.presence`, read every open request's record and its events from the last applied cursor.
Until the relay delivers `aide.presence`, a frontend may make one `wake:false` progress read of its open requests after 30 seconds without notifications for them.
That fallback read is not a subscription keepalive; keepalive reads remain forbidden.

Reads wake a sleeping workspace. `state.get`, `state.list`, `chat.history`, and `chat.events` accept `wake:false`:
the relay then refuses a read of a sleeping workspace with the relay-owned code `asleep` and `outcome:"not_delivered"` instead of waking it. `asleep` is distinct from `paused`.
The relay consumes `wake` and strips it before forwarding, so AIDE never receives it.
A frontend must not read a `waiting` request before its `waiting.until`; after it, one read is the wake that lets AIDE resume the request.

A frontend is subscribed to a session's notifications from its first request naming that session until its connection ends.
There are no keepalive reads. When a frontend connection ends, the relay sends the backend the reserved notification `frontend.closed` in a frame naming that `frontend_id`.
Only the relay sends `frontend.closed`, and only to the backend.

## Chat requests

`ChatRequest` (resource `requests`) is the durable record of one unit of chat work: each accepted `chat.send` (`origin:"user"`), and work AIDE starts without one (`origin:"runtime"`, such as a continuation or wake run).
Its `request_id` is the `chat.send` request ID, or a UUID AIDE chooses for runtime work.
`status` is `queued` until work starts, then `running`, and ends `completed`, `cancelled`, `failed`, or `interrupted`.
`interrupted` means a workspace restart or crash stopped the work; some actions may have run.
`error` is non-null exactly for `failed` and `interrupted`: a stable `code`, a human-readable `message`, and the classified `class` when known.

`waiting` holds a request after a budget, rate-limit, or provider failure. AIDE resumes it without the frontend; do not resend it.
`waiting.reason` and `waiting.until` say why and when; `waiting` is non-null exactly for that status.
`ErrorClass` is an open string. Frontends word the documented values and treat others as a generic failure:

| Class | Request | Frontend wording |
| --- | --- | --- |
| `budget_exhausted` | `waiting` | Out of model budget until `until` |
| `rate_limited` | `waiting` | Provider busy, retrying after `until` |
| `provider_unavailable` | `waiting` | Provider down, retrying after `until` |
| `too_large` | `failed` | Conversation too long; start a new one |
| `misconfigured` | `failed` | Workspace model setup is broken |

Cancelling a waiting request ends it `cancelled` with `error:null`.
A held request blocks later requests of its session, which stay `queued` behind it.
A budget hold can outlast `until` until new budget arrives. A resumed request keeps its record and starts its next `attempt`.

`in_history` says whether `chat.history` holds the request's messages: false before work starts and after a request ends without starting.
For such a request, `state.get` returns the original `chat.send` `messages`, or `message_omitted:true` when they would not fit the message limit.
A frontend shows such requests as pending or failed bubbles; Retry resends those messages under a new request ID.
`state.list` and `Session.requests` never include messages. Runtime requests have neither `messages` nor `message_omitted`.
Request records persist for the session's lifetime.

`Session.requests` embeds up to 1000 non-terminal requests of that session plus its 10 most recently updated terminal requests, ordered by `created_at`, oldest first.
`active_request_ids` lists every non-terminal request; each embedded non-terminal request appears in it and no terminal one does.
`state.list` with resource `requests` requires `session_id` and `scope` and pages all of that session's requests by `created_at`, newest first.
`state.get` with resource `requests` reads one by `request_id`; its `scope` must match the session's.
A request change upserts its session through `state.changed`; there is no separate request notification.
`Session.requests`, revisions, and the other additions of this section are optional in 1.0.0 because earlier producers omit them.

## Chat events

`chat.events` reads one request's progress after the cursor `after`, in cursor order, as typed `ChatEvent`s.
A cursor is `{attempt, seq}`: `attempt` counts the request's durable resumes (0 for its first run), and `seq` numbers that attempt's events.
Cursors order by `attempt`, then `seq`. `seq` starts at 1 in each attempt and increases by exactly one per event, whether the event is read or pushed; `{attempt:n, seq:0}` is the start of attempt `n`.
The runtime folds gateway events it cannot place into the next event, or drops them, before assigning `seq`.

`chat.event` pushes every event with the same cursor `chat.events` returns. `chat.chunk` additionally mirrors each `text.delta` in OpenAI form; when it carries `cursor`, it also carries `request_id`.
A pushed cursor is in order when it is `{attempt, last.seq + 1}` after the last applied cursor `last`, or `{last.attempt + 1, 1}` after the request was seen held.
Any other cursor means missed events: read `chat.events` from the last applied cursor.
A request interrupted by a restart gets a synthesized `finished` event with status `interrupted` at `{attempt: record attempt, seq: highest retained seq + 1}`; it is recorded durably on the request, and `chat.finished.cursor` carries it.

Kinds: `text.delta` (streamed text of a completion), `text.interim` (interim text; `already_streamed:true` when deltas already carried it),
`reasoning` (with `text` when exposed), `tool.started` (`call_id`, `name`, and `arguments` as JSON text),
`tool.completed`, and `finished` (the terminal status and error; always the last event). Every event carries `at`, the time AIDE recorded it. `tool.started`, `reasoning`, and `text.interim` carry `truncated:true` when their text was cut to fit.
Tool events describe backend work; complete tool calls and results are read from `chat.history`.

The result echoes `session_id` and `request_id` and returns events after `after` in increasing cursor order.
`next` is the last returned cursor. An empty page has `next` equal to `after` and `done:true` exactly when the request is terminal. `done:true` means nothing follows `next`.
Pages hold at most `limit` events (default 200, at most 1000) and fit the message limit; continue from `next`.
There is no long-poll; follow live progress through `chat.event` and read again on a gap.
An attempt whose events are no longer retained returns `history_unavailable`: read the request record and `chat.history`, then continue from `{attempt:<record attempt>, seq:0}`.

## Requests and refusal

All commands request an action; none directly assigns recipient-owned state.
For example, `task.cancel` asks AIDE to cancel work. The frontend observes the subsequent authoritative task state.
Every recognized request, including reads, can return:

```json
{"jsonrpc":"2.0","id":"22222222-2222-4222-8222-222222222222","error":{"code":-32000,"message":"Task cancellation is not supported.","data":{"code":"unsupported"}}}
```

`unsupported` means the recipient did not accept or act on the request. The connection and unrelated requests remain usable.
Callers finish the pending UI action, retain authoritative state, and present the explanation when useful.
They must not automatically retry unchanged unsupported requests or fall back to another protocol.
Valid notifications may be ignored by recipients that do not consume them.

Use `-32601` only for methods absent from the selected contract, `-32602` for malformed parameters, and `-32600` for invalid envelopes.
Unimplemented methods, resources, or action variants defined by the contract are not invalid requests.
Authorization refusals use `forbidden`.
When model work cannot start, AIDE refuses `chat.send` with `inference_unavailable`, never `unavailable`, which means lost transport.
Its `reason` (an `ErrorClass`, or null while model access renews) and `until` (or null) say why and until when.
The request was not accepted; send it again after `until`, or shortly when `until` is null.
The relay reports `starting` with `retry_after_ms`, `paused`, `asleep`, `unavailable`, or `gone` for workspace lifecycle failures. `starting`, `paused`, `asleep`, and `gone` are relay-owned codes, as are the notifications `aide.presence` and `frontend.closed`.
Standard JSON-RPC parse and internal errors use `-32700` and `-32603`.
Application errors use `-32000` with the closed `error.data.code` enum in the `Error` schema.
The relay uses `outcome:"not_delivered"` only when it knows the request never reached AIDE.
After dispatch, transport failure or an invalid reply uses `outcome:"unknown"`; it never proves non-execution.
AIDE recipients must not claim `not_delivered`. Retry the identical state-changing request ID to recover an uncertain acceptance.
An unrecoverable request ID is represented by `id:null`.

## Identity, acceptance, and cancellation

The outer request UUID identifies the current request. State-changing backend requests use it as a workspace-scoped idempotency key.
An identical retry returns the original result. Different input under that ID returns `id_reused`.
A disconnect after dispatch means unknown outcome, not confirmed failure. The relay never retries requests automatically.
Browser actions are connection-local and must never be replayed after reconnect.

`chat.send` acknowledges `{accepted:true,session_id,request_id}`, with `request_id` equal to its outer ID.
Acceptance means AIDE recorded responsibility recoverable after an ordinary workspace restart; it does not mean completion.
Rejected input receives an error, not `accepted:false`. Retrying an accepted request never starts duplicate work.
A replayed accepted `chat.send` returns the original acknowledgement and emits no notifications; read `chat.events` from the last applied cursor.

`chat.cancel` targets one chat request in its session, including accepted work not yet started, held `waiting` work, and `runtime` requests.
Stop for any running work in a session is therefore `chat.cancel` of its non-terminal request; there is no separate session-level stop.
`task.cancel` targets the task's work without exposing its scheduler.
`requested:true` confirms cancellation registration; false means the target is already terminal. Unknown targets return `not_found`.
Completion may win the cancellation race. Task state or the request record reports the actual outcome.
A retried `chat.cancel` may answer `requested:false` because the first registered it; the request record shows the outcome.
Cancelled tasks become `abandoned` with outcome `abandoned`; the summary explains why.

Session pending inputs have fresh UUIDs, distinct from chat request IDs and response-command IDs.
`input.respond.params.request_id` identifies that pending input. Approval choices are only `once` and `deny`. The `clarification` kind of pending input and of `input.respond` is deprecated; see "Non-blocking clarifications".
AIDE checks session membership, current pending state, response kind, and allowed choice.
An identical retry of an applied response returns `applied:true`. `conflict` means the input was resolved differently or withdrawn.
Changed prompts get new IDs. Pending inputs remain discoverable in the session until resolved or withdrawn.
`Session.pending` lists the prompts of every request in the session, `runtime` ones included.
An approval's `prompt` is a one-line summary; optional `description` explains the action and `command` is the exact command, shown verbatim.

## Non-blocking clarifications

`clarification.request` lets AIDE ask the frontend a question without holding any work. Its `prompt` is the question, `scope` is where it applies, and optional `session_id` names the session it belongs to.
The frontend answers the request at once with `{accepted:true}`, which means only that it took the question. A frontend that cannot ask returns `unsupported`.
The answer comes later, in `clarification.response`: `request_id` is the outer ID of the `clarification.request`, `answer` is the text, and `scope` repeats the question's scope.
AIDE replies `{applied:true}` when it took the answer. An identical retry of an applied answer returns `applied:true`.
`conflict` means AIDE no longer wants the answer or took a different one; an unknown `request_id` returns `not_found`.

These questions never appear in `Session.pending`, never hold a chat request, and are not answered with `input.respond`.
AIDE continues without the answer and may never receive one.
They replace the `clarification` kind of pending input, which is deprecated. AIDE must not emit new clarification pending inputs.
Until that kind is removed, a frontend still answers one it receives through `input.respond`. Approvals remain pending inputs.
`clarification.request` targets one frontend connection and must never be replayed after reconnect; AIDE may ask again under a new ID.
A frontend that still holds an unanswered question after a reconnect may answer it, because AIDE owns the question's identity.

## Session scope

Every session has an immutable `scope`: `{scope:"workspace",coworld:null,league:null}` or
`{scope:"coworld",coworld:<id>,league:<id>}`. `session.open` requires this declaration and returns it in `Session.scope`.
Session and request reads, event reads, chat sends, cancellation, and pending-input responses carry the expected scope.
AIDE validates equality with the stored session scope before reading content or performing an action; mismatches return `forbidden`.
Changing frontend selection never rebinds an existing session. Children inherit their parent’s scope.

Every other method except `aide.presence` carries `scope` too. A message that names a session carries that session's scope.
`surface.event`, `surface.act`, `clarification.request`, `clarification.response`, `policy.create`, `policy.update`, and `policy.list` require it.
It is optional on `browser.snapshot`, `browser.act`, and every notification, because earlier producers omit it.
On `browser.*` it is the scope of the page the frontend shows. The stored `MessageRecord` and `BrowserSnapshot` accept it for `chat.message` and `browser.changed`.
The relay checks only the shape of these scopes. The recipient checks the value: a `clarification.response` or `policy.update` whose scope differs from the question's or the held policy's returns `forbidden`.
`aide.presence` has no scope: the relay sends it, and it describes the whole workspace.

For sessions, `state.list.scope` selects an exact scope and `state.list.scope_id` selects a Coworld across its leagues.

`session.page` compares the attached session's scope with the viewed Coworld and league. The frontend sends the
page's scope and any related uploads it resolved from the catalog. These uploads are advisory; each
session keeps its own scope and remains subject to the usual workspace and scope checks.

AIDE can respond with `{kind:"stay"}` or `{kind:"offer",target_session_id:...}`. If the user accepts,
repeat the page context with the offered `target_session_id`. A null target asks AIDE to create a
session. AIDE returns `{kind:"switched",session:...}` with the session and scope to attach. The
original session and its requests keep their scope. A frontend can suppress offers the user declined.
If both filters are set, sessions must match both. Omitting both lists sessions across the workspace.
Task and goal `scope_id` remains the domain Coworld identifier; it does not imply league ownership.

Optional `session.open.client` names the opening frontend: `id` (at most 80 characters), `kind` (at most 40), and optional `guide` (at most 64), the agent skill for that frontend.
AIDE stamps it into every turn of the session. Without it, AIDE uses its own default identity.

Optional `session.open.source` says who writes the session's messages to the agent: `user` for a person's chat, or `surface` for messages the frontend sends itself.
AIDE returns it as immutable `Session.source`; the relay checks only the value. Both are optional (earlier producers omit `Session.source`), and absent means `user`.

## Chat

`chat.send.messages` contains ordered **new** OpenAI Chat Completions messages, appended atomically to the session.
The frontend inserts attachments into those messages. There is no separate attachment format.
AIDE retains their structure when passing them to OpenRouter, alongside retained history and its own agent instructions.
Unsupported model/media combinations must be refused explicitly. Provider-specific additions require defined schemas.
Optional `context` is a runtime-defined object, such as the page the user is viewing; the workspace validates and renders it.
Optional `instructions` (at most 64000 characters) is per-request agent guidance kept out of the visible message.
The relay checks only their JSON types and size; AIDE passes both to the workspace unchanged.

`MessageRecord` preserves complete messages, tool-call IDs, arguments, and tool results. Optional `request_id` identifies the originating chat request.
Autonomous messages may omit it. Tool calls describe backend execution; they do not instruct the frontend to execute a tool.
The frontend chooses how to display them. Browser control uses explicit reverse requests.
Optional `kind` separates conversation content (`message`) from a `continuation` prompt written to continue an earlier request, such as AIDE's resume prompt after a hold, and from a runtime `failed_turn` notice that the request record already reports.
Frontends normally hide `continuation` and `failed_turn`. Optional `reasoning` keeps the model's retained reasoning, and `created_at` the message time.

`chat.history` pages backwards from the newest record; `next_cursor` is an opaque boundary that stays valid as new messages arrive.
Optional `after_sequence` reads forward instead: records with a greater `sequence`, oldest first. It excludes `cursor`.

`chat.chunk` carries the pinned OpenAI `ChatCompletionChunk`. Sequence starts at one and increases per completion.
Its optional `cursor` is the chat.events position of the same text; a gap from the last applied cursor means missed progress.
A chat request may produce several completions. On a gap, read `chat.events` or recover complete messages from history; never execute partial tool arguments.
`chat.message` publishes a complete retained record. `chat.finished` reports completed, cancelled, failed, or interrupted; failed and interrupted include an error.
Earlier producers report `interrupted` as `failed` with code `interrupted`.
Store complete messages and the request's terminal record before announcing completion, remove the request from `Session.active_request_ids`, and push that session update.
Completion does not imply that a task succeeded.
On reconnect, read session state, history, and the open requests' events, as in "Reads are authoritative; notifications are hints".

## Workspace snapshots and updates

IDs are opaque and unique per resource across the workspace. `scope_id` is a project/Coworld identifier, never a storage path.
Omit scope for a workspace-wide inventory; requests are listed per session only. Unavailable resources return `unsupported`, not an empty inventory.
List limits default to 50 and accept 1–100. Cursors bind the filter and snapshot revision; stale cursors return `snapshot_expired`.
Every page shares an epoch and revision; `next_cursor:null` completes the inventory.

`state.changed` replaces one complete record, deletes it, or invalidates the collection. There is no patch language.
Revisions increase per resource collection; epochs distinguish resets.
Ignore old/duplicate revisions. Apply an update only when its `previous_revision` matches the installed revision.
Refetch on a gap, changed epoch, invalidation, or reconnect. Buffer updates during snapshot reads and apply the subsequent matching chain.
Filtered/paginated views may refetch instead of repairing membership locally. Notifications do not promise durable replay; reads do.

## Frontend DOM and actions

`BrowserSnapshot` contains the frontend's exposed DOM, relevant form state, document ID, and revision.
`browser.changed` pushes the same complete snapshot and may be coalesced; `browser.snapshot` pulls it.
Do not expose scripts, event-handler source, cookies, credentials, or password values.
Unavailable iframe/shadow content remains opaque, without exposed children or actions.
Node IDs are unique within a document and never reused for different nodes. Navigation changes document ID; relevant changes increment revision.

`browser.act` requests click, fill, or highlight. Check document, revision, target, allowed action, and expiry before dispatch.
Reject stale state with `stale_snapshot`, expired requests with `expired`, and unsupported actions with `unsupported`.
The frontend's ordinary authorization and confirmation behavior still applies. No arbitrary JavaScript execution is exposed.
The result describes dispatch and includes the resulting snapshot; `performed:true` does not promise completion of asynchronous page/network work.
Backend lifecycle changes use backend operations and state updates, not simulated clicks on lifecycle controls.
An oversized snapshot returns `too_large`; it is never silently truncated.

## Surface events and actions

`surface.event` carries one JSON object from the frontend to AIDE: an observation of how the frontend's own state is changing.
`surface.act` carries one JSON object from AIDE to the frontend: an action for the frontend to apply to itself.
The object travels in `params.data`, beside the `scope` it concerns. The frontend and AIDE define the objects between them, and no key inside `data` is reserved.
The relay checks the sender, the scope's shape, that each `data` is a JSON object, and the message limit, and passes `data` unchanged.

Both are requests. The recipient answers with `{data}`, where `data` is an object it defines and `{}` when it has nothing to say, or with an error.
A result means the recipient received the object and chose to answer; what it did is whatever that result says.
A recipient that does not understand an object returns `unsupported`. The frontend's ordinary authorization and confirmation behavior still applies to a `surface.act`.

This contract defines no read for either object; whether the frontend or AIDE keeps them is its own choice. `surface.act` is connection-local like `browser.act` and must never be replayed after reconnect.
A `surface.event` with an unknown outcome may be retried under the same request ID, as for any state-changing request.
Both count toward the 128 pending requests per frontend, so a frontend coalesces frequent observations instead of sending one per change.

## Policies

`policy.create` and `policy.update` let AIDE send policy code it wrote to the frontend, which deploys it. The frontend keys policies by `name`.
Both carry `name` (1–64 characters, no `:`), `scope`, and `blob`, the complete policy content. `scope` is where the policy plays; a name stays unique across scopes. The only blob is `{kind:"text", text}`: one source file of at most 1000000 characters.
Larger or binary content needs a new blob `kind`; it is never split across requests.

`policy.create` deploys a new policy and returns `conflict` when the frontend already holds that `name`. `policy.update` replaces the content of a held policy and returns `not_found` for an unknown `name`.
The result `{name, version}` echoes the name and gives the version the frontend deployed. It confirms the frontend accepted and deployed that content; it does not report how the policy performs.
A frontend that cannot deploy returns `unsupported`. Its ordinary authorization still applies.

The frontend deploys the text as a policy and never runs it in the page. The relay checks the shape and the message limit, and does not read the text.
Both requests target one frontend connection and must never be replayed after reconnect. After an unknown outcome, AIDE may send a new request: a `policy.create` that had applied then returns `conflict`, and AIDE continues with `policy.update`.

`policy.list` asks the frontend which policies it holds. It carries only `scope` and returns `{items}`: the `{name, version}` of every policy the frontend holds that plays in that scope, in no set order and in one reply, without pages.
A frontend that holds none returns an empty `items`; one that cannot hold policies returns `unsupported`.
AIDE keeps no memory of what it sent, so it lists before choosing between `policy.create` and `policy.update`, and after an unknown outcome to learn whether the request applied.
`policy.list` changes nothing, so AIDE may send it again after a reconnect, under a new ID. The text of a held policy is not returned: this contract defines no read for it.

## WebSocket binding

The platform supplies its authenticated API base URL. Append:

- `/v2/workspaces/{workspace_id}/aide/1.0.0/frontend` for the workspace owner's frontend.
- `/v2/workspaces/{workspace_id}/aide/1.0.0/backend` for that exact workspace's authenticated bridge.

Use `wss` outside local development and subprotocol `aide.1.0.0`.
The hosting platform supplies authentication; application parameters never grant workspace access.
The first server frame binds connection identity and message limit:

```json
{"binding":{"frontend_id":"11111111-1111-4111-8111-111111111111","version":"1.0.0","max_message_bytes":1048576}}
```

The backend receives `backend_id` instead of `frontend_id`.
Frontend application frames are bare JSON-RPC. Backend frames add routing:

```json
{"frontend_id":"11111111-1111-4111-8111-111111111111","message":{"jsonrpc":"2.0","id":"22222222-2222-4222-8222-222222222222","method":"session.open","params":{"scope":{"scope":"workspace","coworld":null,"league":null}}}}
```

The backend learns frontend IDs from incoming frames. Reverse requests target one authorized live connection; IDs expire on disconnect.
Notifications target individual frontends; there is no broadcast address. Replies return to their originating connection.
One UTF-8 JSON object occupies each text frame. Binary frames and batches are unsupported.
The inner application message limit is 1 MiB, including attachment data. Use provider-valid media references for larger attachments.
A frontend frame over `max_message_bytes`, or a backend frame over `max_message_bytes + 256` bytes, closes the connection with WebSocket code 1009 and no reply.
The backend's extra 256 bytes allow the routing wrapper; the serialized inner application message must still fit within `max_message_bytes`.
Senders check both the serialized application message and frame sizes before sending and report an oversized message to the user instead of sending it.
At most 128 requests may be pending per frontend. Requests expire after 30 seconds; dispatched work may already have committed.

## Minimum usable implementations

A usable AIDE supports session creation/discovery, text chat acceptance, retained history, readable request records with their outcomes, and request events.
A usable frontend supports those flows and handles unsupported reverse requests gracefully.
The wire permits `unsupported` uniformly; returning it for these core flows means the implementation does not meet this minimum.
The relay validates the contract, not implementation completeness. Publishing the contract does not activate a relay or change protocol selection.
