Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
0ee55cc
Inbox: say a sent reply is queued, and Send now delivers it into the …
backnotprop Oct 16, 2026
534f254
Inbox: keep the plannotator_inbox description under Claude Code's 2,0…
backnotprop Oct 16, 2026
7ff155d
Inbox: the sessions route's asker answer now carries connection
backnotprop Oct 16, 2026
e6d54da
Inbox: the phone list test reads the Sent row's new wording
backnotprop Oct 16, 2026
ef0a4d9
Merge remote-tracking branch 'origin/main' into inbox-queued-send-now
backnotprop Oct 16, 2026
b36ead6
Inbox Send now: decide at the append, never into an Ask turn, confirm…
backnotprop Oct 17, 2026
d90a116
Merge remote-tracking branch 'origin/main' into inbox-queued-send-now
backnotprop Oct 17, 2026
541d99b
Inbox Send now: OpenCode 2 never shows the model a reply twice; Queue…
backnotprop Oct 17, 2026
8f8c10d
Merge remote-tracking branch 'origin/main' into inbox-queued-send-now
backnotprop Oct 17, 2026
f211dba
Merge remote-tracking branch 'origin/main' into inbox-queued-send-now
backnotprop Oct 17, 2026
763042e
Merge remote-tracking branch 'origin/main' into inbox-queued-send-now
backnotprop Oct 17, 2026
3e5679b
Inbox Send now: OpenCode 2 never gives up a steer mid-run, and a repe…
backnotprop Oct 17, 2026
73d25bb
Merge remote-tracking branch 'origin/main' into inbox-queued-send-now
backnotprop Oct 17, 2026
d1c20bf
Inbox e2e: the 👍 line reads the session's connection (when its sessio…
backnotprop Oct 17, 2026
c4da7ed
Merge remote-tracking branch 'origin/main' into fix-1968-tmp
backnotprop Oct 17, 2026
38f44c1
Inbox: a claim the mod cannot use at once is given back, so the perso…
backnotprop Oct 17, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -156,6 +156,7 @@ jobs:
packages/inbox/endedSession.test.tsx
packages/inbox/compose.test.tsx
packages/inbox/composeThread.test.tsx
packages/inbox/sendNow.test.tsx
packages/inbox/pasteFiles.test.tsx
packages/inbox/markRead.test.tsx
packages/inbox/ack.test.tsx
Expand Down
26 changes: 14 additions & 12 deletions AGENTS.md

Large diffs are not rendered by default.

17 changes: 15 additions & 2 deletions adr/implementation/inbox-mobile.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,8 @@ The allowlist. Each row is the window's handler as it is today, with the request
| `POST messages/:id/guide/annotations` | same | `{ idempotency_key, annotation }` (the review app's line comment: `id`, `filePath` in the guide's patch, `side` `old`/`new`, `lineStart`/`lineEnd`, `text`); an edit is the same annotation id under a new key | `{ annotation: record }`. Removed through `annotations/:id/remove` (7.18). The window's refusals pass through: `422 validation_error` (a file not in the patch, a bad side, lines not in one hunk), `404 guide_not_found` / `message_not_found`, `409 annotation_closed`, `409 thread_resolved`. Added 2026-10-15 | 7.53 |
| `POST messages/:id/decision` | same | `{ idempotency_key, key, recording?, draft? }` | `{ question }` | 7.21 |
| `GET decisions?project=prj_...` | same | | `{ serverSession, cursor, project_id, waiting, decisions, project_counts }` (`project_counts`, added later, is every project's `{ project_id, waiting, settled }`; a phone may ignore it) | 7.22 |
| `GET threads/:id/sessions` | same | | `{ serverSession, home, project, sessions }` | 7.23 |
| `GET threads/:id/sessions` | same | | `{ serverSession, home, project, sessions }` (`?asker=<session>` adds `asker: { session, live, connection }`, `connection` = `{ busy, idle_since, send_now }` while that session's connection polls, else null; each session carries `send_now`) | 7.23 |
| `POST messages/:id/send-now` | same | `{ idempotency_key }` | `{ message }` with `deliver_now_at`: Send now (2026-10-16). The session the person's reply or message goes to gets it at once, into its running turn when one runs. Offer it only while `asker.connection.send_now` and `busy` are true (draw "Queued · <agent> is working; it gets this when its turn ends"); `409 send_now_unavailable` when that session's connection does not poll now or cannot take it mid-turn, `409 already_delivered`, `422 not_addressed`. A second press writes nothing. An Inbox before it answers `404 device_route_not_found` | 7.58 |
| `POST threads/:id/message` | same | `{ idempotency_key, session, body }` | `{ message, replayed }` | 7.24 |
| `GET sessions[?session=ses_...]` | `GET /api/inbox/sessions` | | `{ serverSession, home, projects: [{ project: { id or null, name, root }, sessions: [{ session, host, started_at, last_seen_at, busy, idle_since, last_thread }] }], session? }`: every live session, any project (compose's To). A snapshot: a session may have ended by the time a relayed answer is read. Added 2026-10-15 | 7.39 |
| `POST messages` | `POST /api/inbox/messages` | `{ idempotency_key, to: { host?, session }, body, uploads?: [upl_...], thread_name? }` | `{ thread_id, message, project, replayed }`: a thread the person starts, addressed to one live session. `draft_id` (which deletes a shared draft) is refused by the door, `422 { "field": "draft_id" }`: drafts stay on the computer. The body key is also the store's own. `409 session_not_live` (nothing written), `503 project_unresolved` (not recorded, so the same call runs again), `422 validation_error`, `409 idempotency_key_reused` pass through. `thread_name` (optional, added 2026-10-16) is the thread's name, its chip, checked by the thread-name rules (`422 validation_error`) and refused with `409 thread_name_taken` (nothing written) while another open thread of the project has the name; an agent never replaces it. `thread_name_auto: true` (optional, added 2026-10-16) marks `thread_name` as compose's own suggestion: dropped instead of refused when not valid or taken, and replaced by the agent's first name. A name refused here (`409 thread_name_taken`, `422`) is stored by the door under the idempotency key like any 4xx, so a retry with another name, or none, must use a NEW idempotency key; the same key answers the stored refusal again. Added 2026-10-15 | 7.40 |
Expand Down Expand Up @@ -1157,7 +1158,7 @@ curl -sS -X POST "$INBOX/api/inbox/device/markups?idempotency_key=00000000-0000-

### 7.53 A comment on a guided review's diff

7.50 to 7.52 (shared drafts) and 7.54, 7.55 (decision retire and replace) are held and not built. 7.56 is 👍 Looks good, 7.57 a reply carrying files (below).
7.50 to 7.52 (shared drafts) and 7.54, 7.55 (decision retire and replace) are held and not built. 7.56 is 👍 Looks good, 7.57 a reply carrying files, 7.58 Send now (below).

```sh
curl -sS -X POST "$INBOX/api/inbox/device/messages/msg_01K70000000000000000000020/guide/annotations" \
Expand Down Expand Up @@ -1189,6 +1190,18 @@ curl -sS -X POST "$INBOX/api/inbox/device/messages/msg_01K7000000000000000000002

7.11's answer, with `reply.attachments` holding each file as an ordinary attachment record (the same as 7.40's thread). The agent reads them as `Attached: <name> (<path>)` lines under the words, on its wake and from `wait_for_reply`. A Send of files alone (no words, no answers) is a reply, read as a words-only one. Replaying the key answers the reply it wrote and copies nothing; an id that is gone: `404 upload_not_found`, nothing written. On a Send that answers several messages, name the files on the reply that carries the words (the last), as the window does.

### 7.58 Send now

The line under the person's last reply says where it is (the window's `deliveryLine`, `packages/inbox/deliveryLine.ts`): for a reply to a message with `wakes`, or a message with `to`, read `GET threads/:id/sessions?asker=<that session>`; `asker.connection.busy` true reads "Queued · <agent> is working; it gets this when its turn ends", false reads "Sending to <agent>…", null (the connection does not say) or no `connection` reads "Queued for <agent>; it gets this as its next turn", `connection: null` reads "Queued for <agent>; it gets this when its session is back"; `deliver_now_at` on the message reads "Sending to <agent> now…"; a reply to a message without `wakes` reads "Saved for <agent>. It sees it when it next reads this thread". Offer Send now only while `connection.busy` and `connection.send_now` are true:

```sh
curl -sS -X POST "$INBOX/api/inbox/device/messages/msg_01K70000000000000000000058/send-now" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"idempotency_key":"00000000-0000-4000-8000-000000000058"}'
```

`{ "message": { "id": "msg_01K70000000000000000000058", "deliver_now_at": "2026-10-16T17:06:00.000Z", "...": "" } }`. The session's connection then puts it into the running turn (Claude Code: a user row; Pi and OpenCode 2: a steer) and records the delivery as usual ("Delivered to <agent>, <time>").

## 8. What this contract leaves out

The Workspaces app's side (it has its own contract, and decides how to draw a message's images), the iPad, pairing through the relay, deleting a mailbox, a retention sweep at the relay, rates beyond the reused creation brake, raw attachment bytes on the door, device attestation, request signing, re-authentication, and any Settings, restart or storage route on the phone.
Expand Down
11 changes: 11 additions & 0 deletions apps/hook/hooks/mod/controller.ts
Original file line number Diff line number Diff line change
Expand Up @@ -348,6 +348,11 @@ export class PlannotatorMod {
sessionId: session.sessionId,
tools: session.inboxTools,
isBusy: () => this.turns.busy,
// Send now goes into a running main turn, never into this session's own Ask question.
steerableTurn: () => {
const turn = this.turns.runningTurn
return turn !== null && !this.turns.ownsTurn(turn) ? turn : null
},
...(session.cwd ? { cwd: session.cwd } : {}),
instanceId: this.instanceId,
})
Expand Down Expand Up @@ -1555,6 +1560,11 @@ export class PlannotatorMod {
this.turns.onPromptDropped(prompt)
}

/** A main-loop model request is about to go out (every turn.step without an agent id), from register.ts. */
onMainStep(turnId: string): void {
this.inbox?.onMainStep(turnId)
}

/** A model request of a turn is about to go out (turn.step), from register.ts. */
onTurnStep(turnId: string): void {
this.turns.onStep(turnId)
Expand All @@ -1581,6 +1591,7 @@ export class PlannotatorMod {
onTurnComplete(turnId: string, answer: string, aborted: boolean): void {
this.host.debug(`turn.complete ${turnId}${aborted ? ' (aborted)' : ''}: ${answer.length} chars`)
this.turns.onTurnComplete(turnId, answer, aborted)
this.inbox?.onMainTurnComplete(turnId)
this.pushBridgeStatus()
}

Expand Down
18 changes: 18 additions & 0 deletions apps/hook/hooks/mod/host.ts
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,24 @@ export interface Host {
storeSet(key: string, value: unknown): Promise<void>
/** `$.prompt.submit`: runs once the session is idle, read under the plugin's name. */
submit(text: string): Promise<void>
/**
* `$.session.append` of a user-role row (the model reads it; the person
* does not see it as typed): in a running turn it is in the turn's next
* model request, the one way a plugin puts words into a running turn
* (`$.prompt.submit` never folds into one). Rejects when the row was
* refused, or the engine has no `$.session.append`. Optional for hosts
* (tests) that model an engine without it.
*/
appendUserRow?(text: string): Promise<void>
/**
* Whether this engine has `$.session.append` (a build that documents it;
* `claude plugin validate` refuses reading `$.session.append` as a value,
* so it is decided from the engine's version). Absent or false: Send now
* is never advertised.
*/
sessionAppendAvailable?(): Promise<boolean>
/** `$.session.append` of a notice the transcript shows and the model never reads. */
appendNotice?(text: string): Promise<void>
suggest(text: string): Promise<void>
status(text: string | undefined): void
log(text: string): void
Expand Down
26 changes: 26 additions & 0 deletions apps/hook/hooks/mod/inbox-contract.ts
Original file line number Diff line number Diff line change
Expand Up @@ -448,6 +448,14 @@ export interface InboxReplyCommand {
* command; an older connection ignores it.
*/
name_thread?: boolean
/**
* The person pressed Send now in the Inbox: deliver it at once, into the
* running turn when one runs (Claude Code: `$.session.append`; Pi: a
* steer; OpenCode 2: `delivery: "steer"`), instead of waiting for the
* session to go idle. Only handed to a connection whose poll said it can
* (`INBOX_SEND_NOW_POLL_FIELD`). Absent on every other command.
*/
now?: boolean
/**
* On the person's 👍 Looks good, delivered once its Undo window passed
* (amended 2026-10-16: it reaches the agent): the agent message they
Expand All @@ -459,6 +467,24 @@ export interface InboxReplyCommand {
ack_of?: string
}

/**
* The poll field (`true`) by which a connection says it can deliver a reply
* into a running turn: the window offers Send now only for such a session.
* An older Inbox ignores it; an older connection never sends it, so it is
* never offered there.
*/
export const INBOX_SEND_NOW_POLL_FIELD = 'send_now'

/**
* The turn a connection submits when a reply it put into a running turn
* arrived as that turn ended, so the model never read it: the reply is in
* the conversation already, so this only points at it.
*/
export function inboxSentNowFollowUpText(command: Pick<InboxReplyCommand, 'id' | 'subject' | 'type'>): string {
const subject = (command.subject ?? '').replace(/\s+/g, ' ').trim() || (command.type === 'message' ? 'a message' : 'a reply')
return `Plannotator Inbox: ${subject} (${command.id})\nThe person's ${command.type === 'message' ? 'message' : 'reply'} above (${command.id}) arrived as your last turn was ending. If you have not answered it yet, answer it now.`
}

export function parseInboxBridgeCommands(text: string): InboxReplyCommand[] {
try {
const body = JSON.parse(text) as { commands?: unknown }
Expand Down
Loading
Loading