Ask the copilot

One copilot turn, streamed. Two protocols answer on this route for one release, chosen by `Accept`. THE UI MESSAGE STREAM. List `application/vnd.phonebase.ui-message-stream` in `Accept` and send the AI SDK transport's body: `{id, messages, trigger, messageId}`, where `id` is the thread id (a new one opens the thread) and `messages` is the client's transcript. ONLY THE LAST MESSAGE IS READ: a user message (its text parts) starts a turn, and an assistant message carrying a tool part in state `approval-responded` answers the question the previous turn ended on. The history the model is shown is the STORED thread, within a budget of 48000 characters of transcript, never the client's copy. What the budget cuts away is NOT forgotten: it is folded into a short summary the copilot writes once and keeps with the thread, shown in front of the recent messages on every turn after that, so a long conversation still knows what it was started for and which phone it was about. Nothing rebuildable from the server goes into that summary. The response is `text/event-stream` with the header `x-vercel-ai-ui-message-stream: v1`, one `data: <chunk>` frame per chunk, ended by `data: [DONE]`. It opens with `start` (naming the assistant message being written, which is the message a resumed approval continues), carries text and reasoning as deltas, every tool call as `tool-input-available` before it runs and `tool-output-available` (`{summary, text, frameId?}`), `tool-output-error` (`errorText`, which the protocol requires, and when the tool itself failed also `{message, code, retryable, retryAfterMs?}` beside it, on the stream only and never on a stored part) or `tool-output-denied` after, a `file` chunk with a `data:` URL for a screenshot of at most 204800 bytes, `data-allowance` ({percent, metered}; TRANSIENT, delivered to the client's data callback and never stored as a part) after `start` and before `finish`, `data-device-choice` ({reason, devices:[{id, label}]}) when a call needed a phone and none was named, `data-suggestions` ({items:[{text, deviceId}]}, at most three, each naming a device) before `finish` on a turn that completed -- both of those ARE parts and survive a replay of the thread, and ends with `finish` (`finishReason`, and `messageMetadata.stopReason` from the copilot's own closed set) or with `error`, after which nothing follows. WHEN IT FAILS (API-232). `copilot_unfunded` means the copilot has no credit ON OUR SIDE: the message is the sentence to show, nothing the caller did caused it, and their phone and direct commands are unaffected. `rate_limited` is the provider throttling and is worth retrying. `model_unavailable` is the model being unreachable. Those three were ONE code until now, so a client could only ever say the vaguest of them; `model_refused`, `tool_failed` and `internal` complete the set. The older event stream still reports the first three as `model_unavailable`, because its console branches on the set as it stood. APPROVALS RIDE THE STREAM. Anything that changes the phone, takes or hands back the device, or starts an agent run asks first: `tool-approval-request` carries an `approvalId` and a descriptor with the tool, its arguments and one sentence to show, and the stream ENDS with `finish{finishReason: "tool-calls"}`. The descriptor says which card to draw and why: `kind` is `light` (one line and one row) or `plan` (a goal with an editable `budget` of `maxSteps` and `deadlineMs`), and `reason.code` is `start_run`, `install_app`, `dangerous_operation` or `boundary`. When one question covers the same tool on SEVERAL phones the descriptor carries `calls: [{toolCallId, tool, input}]` and one yes runs all of them, each as its own call with its own receipt; a dangerous operation is never folded into that list and always gets its own card. Answer by sending the same thread again with the assistant message's tool part in state `approval-responded` (`approval: {id, approved, reason?, input?, descriptor?}`); the next stream continues the same assistant message: the tool runs, or `tool-output-denied` ends the turn. `approval.input` is the person's EDIT of the arguments on a plan card: it is MERGED over the arguments they were shown, so sending only the field they changed does not delete the rest, and it is re-checked against the tool's published input schema. An edit the schema refuses is 400 naming the field, and nothing runs. If you echo `approval.descriptor.reason`, it must be the code the question was asked with, or the answer is 400: consent shown for one reason is not consent for another. Echoing nothing is accepted. The question does NOT expire on a clock: it waits until you answer it (Confirm or Decline) or a new message on the thread supersedes it, which closes it with `tool-output-error`. A turn takes at most 12 model steps, across the requests an approval splits it into. Closing the request aborts the turn: the copilot stops before its next step or tool call, what was written is kept, and the stored message ends with `finishReason: "stop"`. A tool already running completes and its receipt stands. THE EVENT STREAM (older). Any other `Accept`, or none, selects it. Send `{prompt}`; the response is a `text/event-stream` whose frames are named SSE events: `session.start` once, first; `message.delta` prose; `tool.call` a tool is ABOUT TO RUN; `tool.result` it finished, `isError` being the tool's own verdict; `approval.request` a question, the turn PAUSED; `tool.denied` you said no or nobody answered; `ping` keep-alive; `done` with a `stopReason`; `error` with a `code`. Exactly one `done` or one `error` ends every stream. Approvals are answered on `POST /v1/copilot/approvals`, a SEPARATE request, while the stream stays open; a client that closes the stream to answer loses the turn. This protocol goes in the release after the console has switched. WHICH PHONE (API-228). Both shapes take an optional `context` and `mentions`. When they name a device, the turn is about it: the model is told so, a call that needs a device and names none is given that one, and it does not ask which phone. When nothing names one and you have several, a `data-device-choice` chunk carries the candidates, the call is answered `tool-output-error`, and no phone is touched. A device id in `context` or `mentions` that your session cannot address is 400 naming the field; every wrong field is named in the one answer. Needs a signed in person. A copilot acts as somebody, and an API key has nobody behind it; drive the tools directly through the MCP endpoint instead. The turn can reach exactly the tools your session already has, no more, because it drives the same tool surface this service publishes. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404.