Chat with the copilot

​

Threads live on the server

• The copilot remembers. Each turn is shown the thread so far, within a budget (see Limits), so you can say “now open the second one” without repeating yourself.
• Your client’s history is not trusted. A request carries the client’s copy of the transcript, and only its last message is read. What the copilot is shown is the stored thread. Two browsers open on one thread see the same past, and nobody can put words in the copilot’s mouth by editing a payload.
• A thread is private. Another person in your organisation cannot list it, open it, rename it or delete it. To them it answers 404, the same as a thread that never existed. There is no sharing yet.

​

Reopening a thread

• limit is how many messages, DEFAULT_THREAD_MESSAGE_ROWS when omitted and at most MAX_THREAD_MESSAGE_ROWS.
• nextBefore in the response is the oldest message on the page, when older ones exist. Send it back as before to get the page before it.
• Inline screenshots are carried within MAX_INLINE_PAGE_BYTES of decoded image data per response (about a third more on the wire, as base64 inside JSON). The fit is greedy, newest first: each screenshot is kept if it fits what is left, so a large one that does not fit is left out while a smaller older one may still be carried. files=none leaves every one out. Either way omittedFiles says how many were left out, and the frameId on the tool output beside each one still names the picture for the frames API.

​

The protocol

{
  "id": "thread_8f2c",
  "trigger": "submit-message",
  "messages": [
    { "id": "u_1", "role": "user", "parts": [{ "type": "text", "text": "Open the camera on pixel-1" }] }
  ]
}

​

Which phone the turn is about

{
  "id": "thread_8f2c",
  "messages": [{ "id": "u_1", "role": "user", "parts": [{ "type": "text", "text": "Open the camera" }] }],
  "context": {
    "route": "/devices/pixel-1",
    "device": { "id": "pixel-1" },
    "pinned": { "deviceId": "pixel-1" }
  },
  "mentions": ["pixel-2"]
}

1. context.pinned.deviceId, a phone the person pinned to this chat.
2. mentions, when it names exactly one.
3. context.device.id, the page they are on.
4. The device this thread last acted on, read from its own tool calls.
5. The only device you have, if you have one.
6. Otherwise a data-device-choice card.

• The copilot is told, and it acts. A tool call that needs a device and names none is given the one the context decided, so a sentence with no phone in it still reaches the right phone, and the call you see carries the id.
• context is never replayed. It describes where somebody is now, so only this request’s copy is read. The stored thread keeps none of it. What survives between turns is which device the thread actually touched, which is a fact rather than a claim about a page.
• An id you cannot address is a 400, naming the field. Every field that is wrong is named in the one answer, so you never fix them one round trip at a time. context.device is {"id": ...}, an object; a bare string is refused rather than ignored.

​

Approvals

1. The copilot sends tool-input-available for the call, then tool-approval-request with an approvalId and a descriptor: the tool, its arguments, one sentence to show, and expiresAt. The sentence is built from the tool and its arguments, never from anything the model wrote, so a card cannot describe a tap as a screenshot.
2. The stream ends with finish{finishReason: "tool-calls"}. The stored assistant message holds the pending question, so the answer may arrive on any machine, minutes later.
3. You answer by sending the same thread again, with that assistant message last and its tool part in state approval-responded, carrying approval: {id, approved, reason?, input?, descriptor?}. This is what the AI SDK’s addToolApprovalResponse produces, plus the two fields below.
4. The next stream continues the same assistant message: its start names the same messageId. On a yes the copilot looks at the screen first, then runs the call, then the calls the model had queued behind it, then decides again. On a no it sends tool-output-denied and the turn ends: a copilot that carried on after a refusal, working around it, would make its approvals meaningless.

​

What the card says

​

One card, several phones

​

Editing before you agree

{ "id": "ap_1", "approved": true, "input": { "maxSteps": 4, "goal": "log in and stop" } }

​

How much it does on its own

​

What is never turned off

• A tool that declares requiresUserInteraction in its own MCP metadata. This is enforced at every call. Historical install_app approval cards remain readable, but approving one cannot restore retired installation.
• A text message to somebody this chat has not written to before.
• Doing something to several phones in one go.
• Creating a schedule.
• Money, API keys and team membership, which are never done on your behalf at all. Those are not cards; they are refusals with a link.

​

Picking a cut stream back up

• since is the messageId from the start chunk you were reading.
• afterPart is how many of its parts you already hold. 0, the default, replays the whole message; a number past its end sends the frame and nothing inside it, which is how you learn you are caught up.
• Omit since and the newest assistant message is replayed from the beginning, which is what a client that lost its place entirely needs.
• A since naming no message of this thread replays nothing rather than restarting from the top. Restarting would repeat what you already have and hide that your cursor is stale.

​

Commands: one tool, no model

{ "tool": "press_key", "input": { "key": "home" }, "context": { "device": { "id": "pixel-1" } }, "threadId": "thread_8f2c" }

• It works with no copilot configured. A deployment with no model answers 503 on POST /v1/copilot and still runs commands. Pressing Home should not need a language model.
• The receipt is not marked via copilot. You did this.

​

When it fails

​

Limits

• A turn takes at most MAX_TURN_STEPS model steps, across the requests an approval splits it into. Reaching the budget is not an error: the work done is done, and its receipts exist. A job that genuinely needs more is an agent run.
• One message carries at most MAX_COPILOT_PROMPT_CHARS characters of text.
• The history the model is shown is the most recent messages that fit within HISTORY_BUDGET_CHARS characters of transcript, cut at a message of yours so the transcript never opens with the copilot’s reply. Your newest message is always included. What the cut removes 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. A long conversation therefore still knows what it was started for and which phone it was about. The summary is regenerated only when the cut reaches past what it already covers, so it costs one extra model call when a thread first crosses the budget and nothing on the turns after. Nothing that can be rebuilt from the server goes into it: the mode, what has been remembered and which phone the chat is about are regenerated fresh every turn, so a summary of them would be a second and stale copy.
• Screenshots travel inline up to MAX_INLINE_FILE_BYTES; above that you get the frame id.
• The listing returns at most MAX_THREAD_ROWS threads per page, a thread read at most MAX_THREAD_MESSAGE_ROWS messages, and both refuse a larger limit rather than quietly reducing it.
• The copilot gives up on a model that stays silent for MODEL_TIMEOUT_MS within one step, and says so as an error of its own; a model that keeps answering slowly is never cut off.

​

The older event stream