From 0ee55cce3db4cfeaae02a9eb7c5740e2b70b57f2 Mon Sep 17 00:00:00 2001 From: Michael Ramos Date: Fri, 16 Oct 2026 17:41:37 -0400 Subject: [PATCH 1/9] Inbox: say a sent reply is queued, and Send now delivers it into the running turn MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The line under the person's reply said "Saved for Claude Code. It sees it when it checks." while the reply waited for the session to go idle, which read as dropped. It now says where the reply is, from the session's connection: "Queued · Claude Code is working; it gets this when its turn ends." with Send now, "Sending to Claude Code…" while idle, and the truthful "Saved for … It sees it when it next reads this thread." for an agent that only reads the thread. Send now (POST /api/inbox/messages/:id/send-now, door 7.58) marks the reply deliver_now_at; the bridge command carries now: true. The Claude Code mod puts it into the running turn as a user row with $.session.append (a plugin's $.prompt.submit never folds into a running turn), with one short follow-up turn if the turn ended before any request carried it; Pi steers (deliverAs: "steer"); OpenCode 2 prompts with delivery: "steer". Connections advertise it with the poll field send_now. Also fixes the mod counting a subagent's turn.start as the session's turn: its end was never counted, so a background subagent left the session busy for good and Inbox replies never went in. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/test.yml | 1 + AGENTS.md | 28 +- adr/implementation/inbox-mobile.md | 17 +- apps/hook/hooks/mod/controller.test.ts | 20 ++ apps/hook/hooks/mod/controller.ts | 13 +- apps/hook/hooks/mod/host.ts | 11 + apps/hook/hooks/mod/inbox-contract.ts | 28 +- apps/hook/hooks/mod/inbox.test.ts | 87 ++++- apps/hook/hooks/mod/inbox.ts | 90 +++++- apps/hook/hooks/mod/register.ts | 14 +- apps/hook/hooks/mod/testing/claude-session.ts | 17 + apps/hook/server/inbox-help.ts | 2 +- apps/hook/tests/register.test.ts | 47 ++- .../src/content/docs/reference/inbox.md | 10 +- apps/opencode-plugin/inbox.ts | 17 +- apps/pi-extension/inbox.ts | 48 +-- packages/core/inbox-types.ts | 20 +- packages/inbox/api.ts | 16 +- packages/inbox/components/InboxList.tsx | 5 +- packages/inbox/components/NewMessage.tsx | 6 +- packages/inbox/components/Thread.tsx | 83 ++++- packages/inbox/composeThread.test.tsx | 2 +- packages/inbox/deliveryLine.test.ts | 59 ++++ packages/inbox/deliveryLine.ts | 84 +++++ packages/inbox/inbox.css | 13 + packages/inbox/sendNow.test.tsx | 196 +++++++++++ packages/server/inbox-devices.ts | 2 +- packages/server/inbox-send-now.test.ts | 305 ++++++++++++++++++ packages/server/inbox-sessions.ts | 73 ++++- packages/server/inbox.ts | 4 + packages/shared/inbox/agent-link.ts | 33 +- packages/shared/inbox/connection.ts | 28 +- packages/shared/inbox/store.ts | 51 ++- tests/e2e/inbox-compose.spec.ts | 3 +- tests/e2e/inbox-ended-session.spec.ts | 3 +- tests/e2e/inbox-new-message.spec.ts | 3 +- tests/e2e/inbox-send-now.spec.ts | 292 +++++++++++++++++ tests/e2e/playwright.config.ts | 4 +- 38 files changed, 1636 insertions(+), 99 deletions(-) create mode 100644 packages/inbox/deliveryLine.test.ts create mode 100644 packages/inbox/deliveryLine.ts create mode 100644 packages/inbox/sendNow.test.tsx create mode 100644 packages/server/inbox-send-now.test.ts create mode 100644 tests/e2e/inbox-send-now.spec.ts diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index b35fc9612c..7ba4acdbc0 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -154,6 +154,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 diff --git a/AGENTS.md b/AGENTS.md index 6faa5a431f..e56a4b4755 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -991,8 +991,8 @@ an `ask` is submitted as a real turn (`$.prompt.submit`), identified at `turn.start` by its header and last line (Claude Code frames a plugin prompt as "The plannotator plugin sent a message: …", seen live), streamed back from `turn.step` text/tool chunks, and finished from `turn.complete`'s `answer`. -`busy` = a turn is running (pushed on `turn.start` / `turn.complete`, not only -at the next poll); `interrupt` aborts the running turn (`$.turn.abort`); +`busy` = a MAIN-LOOP turn is running (pushed on `turn.start` / `turn.complete`, not only +at the next poll; a subagent's `turn.start`, which every hook hears, is ignored by `onTurnStart`: its end is never counted, so counting it left the session busy for good after a background subagent started, and the Inbox wake never delivered); `interrupt` aborts the running turn (`$.turn.abort`); cancel aborts our own turn, or, while it is still queued, confirms at once and aborts its turn the moment it starts. Claude Code never raises a plugin's own hooks for a prompt its code submitted (the debug log says "skipped: re-entry"), so the @@ -1039,7 +1039,7 @@ A poll answered `superseded: true` (another client polled the server after us) waits 10-15 s before polling again, instead of taking the server back at once and starting a busy loop with the other client. -**The Plannotator Inbox (`plannotator_inbox` and the reply wake, `inbox.ts`).** Where `PLANNOTATOR_INBOX_TOOL` / `inboxTool` allows it at the first `session.start` (on by default here), `register.ts` reads the Inbox's tool list once (`discoverInboxTools`: `tools/list` on its `/mcp`; a stopped Inbox is described by the list it last answered with, kept in `$.store` as `inboxTools`; with neither, the list bundled with the mod, `INBOX_DEFAULT_TOOLS` in `inbox-default-tools.ts`, generated from a real Inbox by `bun run scripts/sync-mod-inbox-tools.ts` and pinned to one by `inbox-default-tools.test.ts`) and registers `plannotator_inbox` (`inboxAgentTool`), a SEPARATE tool, never actions on `plannotator`. So Claude Code has the tool before this computer ever ran the Inbox: the first call starts it. With no `inbox/inbox.json` the link stays silent: no HTTP request and no file (no lease, no claims folder) until a call starts the Inbox, and the wake polls from the next tick after. With the tool, `inbox/inbox.json` present at the first `session.start` (an Inbox has run here) and `inboxReminder` on (default), a `prompt.context` hook adds the `plannotatorInbox` block (`withInboxReminder`, the line naming the tool's registered full name) to the conversation's first message, once per conversation (see `inboxReminder` under Config-only settings). The session's `PlannotatorMod` owns an `InboxLink` (one per session id, so `/clear` and an in-process resume follow the new id: the old link is disposed at `session.end` and the next hook makes one for the new id). A call (`tool.call`, answered by the mod) re-reads the registry, checks health against its `serverSession`, starts a stopped Inbox with `plannotator inbox --background` (a one-shot that detaches the Inbox into its own session and waits for it; never a browser tab), and proxies to `/mcp` with `project_path` = `$.session.cwd()` (or the agent's optional `project_path`, resolved against it by `INBOX_PROJECT_DIR_SCRIPT` and refused before the Inbox is reached when it is not an existing folder) and `agent_session` = the host's real session id; `wait_for_reply` is held to 25 s through the tool (`$.http.fetch` gives up at 30 s). The wake: a 1 s `$.clock.every` tick long-polls `/api/inbox/bridge/poll` (20 s) with a 5 to 60 s backoff that never gives up; a reply waits in the mod until the session has been idle for two ticks (a pending `$.prompt.submit` cannot be withdrawn, so a prompt the person typed, or a `/clear`, queued during a turn goes first), is checked once more with the Inbox (an agent may have read it meanwhile), claimed once across processes (`INBOX_CLAIM_SCRIPT`: mkdir of `claude-code-mod//inbox/claims/`), submitted (`inboxWakeText`), and acknowledged (`delivered`, retried until the Inbox answers). A prompt typed into the reply's own turn takes it over as Claude Code folds it in; the mod never aborts it and never delivers the reply again. Two processes on one session: the session's inbox lease (`claude-code-mod//inbox/watcher.json`, the rules of the review watcher lease: the person's last process wins, 20 s stale) picks the one that polls and delivers, and the claim makes a lease race harmless; a claimant writes `alive` while its turn waits, and a reply whose claimant stopped for 60 s without `delivered` is reported once with a toast (the only toast the connection raises); one marked `delivered` whose acknowledgement was lost is acknowledged by the other process. Nothing touches the system prompt; the tool list is fixed per process. Version skew: an Inbox without the bridge route (404) just leaves the poll backing off; an action the running Inbox lost answers "update Plannotator"; a `plannotator` without the `inbox` subcommand answers that the binary has no Inbox. +**The Plannotator Inbox (`plannotator_inbox` and the reply wake, `inbox.ts`).** Where `PLANNOTATOR_INBOX_TOOL` / `inboxTool` allows it at the first `session.start` (on by default here), `register.ts` reads the Inbox's tool list once (`discoverInboxTools`: `tools/list` on its `/mcp`; a stopped Inbox is described by the list it last answered with, kept in `$.store` as `inboxTools`; with neither, the list bundled with the mod, `INBOX_DEFAULT_TOOLS` in `inbox-default-tools.ts`, generated from a real Inbox by `bun run scripts/sync-mod-inbox-tools.ts` and pinned to one by `inbox-default-tools.test.ts`) and registers `plannotator_inbox` (`inboxAgentTool`), a SEPARATE tool, never actions on `plannotator`. So Claude Code has the tool before this computer ever ran the Inbox: the first call starts it. With no `inbox/inbox.json` the link stays silent: no HTTP request and no file (no lease, no claims folder) until a call starts the Inbox, and the wake polls from the next tick after. With the tool, `inbox/inbox.json` present at the first `session.start` (an Inbox has run here) and `inboxReminder` on (default), a `prompt.context` hook adds the `plannotatorInbox` block (`withInboxReminder`, the line naming the tool's registered full name) to the conversation's first message, once per conversation (see `inboxReminder` under Config-only settings). The session's `PlannotatorMod` owns an `InboxLink` (one per session id, so `/clear` and an in-process resume follow the new id: the old link is disposed at `session.end` and the next hook makes one for the new id). A call (`tool.call`, answered by the mod) re-reads the registry, checks health against its `serverSession`, starts a stopped Inbox with `plannotator inbox --background` (a one-shot that detaches the Inbox into its own session and waits for it; never a browser tab), and proxies to `/mcp` with `project_path` = `$.session.cwd()` (or the agent's optional `project_path`, resolved against it by `INBOX_PROJECT_DIR_SCRIPT` and refused before the Inbox is reached when it is not an existing folder) and `agent_session` = the host's real session id; `wait_for_reply` is held to 25 s through the tool (`$.http.fetch` gives up at 30 s). The wake: a 1 s `$.clock.every` tick long-polls `/api/inbox/bridge/poll` (20 s) with a 5 to 60 s backoff that never gives up; a reply waits in the mod (unless the person pressed Send now: see "Questions and Send"; the mod then puts it into the running turn with `$.session.append`) until the session has been idle for two ticks (a pending `$.prompt.submit` cannot be withdrawn, so a prompt the person typed, or a `/clear`, queued during a turn goes first), is checked once more with the Inbox (an agent may have read it meanwhile), claimed once across processes (`INBOX_CLAIM_SCRIPT`: mkdir of `claude-code-mod//inbox/claims/`), submitted (`inboxWakeText`), and acknowledged (`delivered`, retried until the Inbox answers). A prompt typed into the reply's own turn takes it over as Claude Code folds it in; the mod never aborts it and never delivers the reply again. Two processes on one session: the session's inbox lease (`claude-code-mod//inbox/watcher.json`, the rules of the review watcher lease: the person's last process wins, 20 s stale) picks the one that polls and delivers, and the claim makes a lease race harmless; a claimant writes `alive` while its turn waits, and a reply whose claimant stopped for 60 s without `delivered` is reported once with a toast (the only toast the connection raises); one marked `delivered` whose acknowledgement was lost is acknowledged by the other process. Nothing touches the system prompt; the tool list is fixed per process. Version skew: an Inbox without the bridge route (404) just leaves the poll backing off; an action the running Inbox lost answers "update Plannotator"; a `plannotator` without the `inbox` subcommand answers that the binary has no Inbox. **Tests.** Bun: `apps/hook/hooks/mod/*.test.ts` (controller flows over an in-memory `Host`, delivery, shell words, and `bridge.test.ts` against the REAL @@ -2132,7 +2132,7 @@ Sorting and the rest: - the "Guided review" mark when the thread carries one - the time - A Sent row reads "Saved for . It sees it when it checks." Quiet is folded. + A Sent row reads "Queued for ; it gets this as its next turn." when the reply goes to a session whose connection wakes it (the row's additive `sent.wakes`), else "Saved for . It sees it when it next reads this thread." (`sentRowLine`, `packages/inbox/deliveryLine.ts`). Quiet is folded. - The look of a row (design record "inbox-polish", approved 2026-10-15, not in this repo; `inbox.css`, `components/InboxList.tsx`): - Hover and the selected row are a pill 3 px inside the row (its `::before`, radius 8, no border; variant A): hover muted 45%, selected `--ib-sel` (primary 10% light, 15% dark; 14% / 19% hovered). The separators run unbroken under it. The Decisions page's rows (`.ib-drow`) use the same rule. - The thread chip is left out when the subject already starts with the thread's name (`chipName`: compared by `inboxThreadNameKey`, and only where the subject ends there or goes on with a space, or with `:`, `-`, `–` or `—` and a space, so `v2` stays beside "v2.1 release" and `auth` beside "auth-service down"), on the wide, two-line and phone rows. @@ -2193,7 +2193,8 @@ Sorting and the rest: - The reply box with its "N picks" and "N annotations" chips. Mod+Enter sends. Its chip row wraps inside the box (`.ib-rfoot`): a chip never shrinks or breaks its label, and the skip chip's sentence wraps inside itself only where the box is narrower than it (a phone). Before this, in the 440 px thread beside a file, "3 annotations" broke over lines and spilled out of the box. `tests/e2e/inbox-attachments.spec.ts` checks the chips stay inside the box at 440 px, 1440, 810, 900, 390 and 320. The no-wrap applies to the chips only, never to the "N annotations ride this reply" list (`.ib-annpop`), whose quotes and comments wrap; where that list would run past the window's right edge it lines up with the reply box's right edge (`--ib-annpop-shift`, set by `AnnotationsChip`); the same e2e checks both at every width. - A Send is `POST /api/inbox/messages/:id/reply` with an idempotency key per target message, kept for a retry. The store writes one person reply in this order: its first line (`Answered N questions.`, `Skipped N questions.` or `Answered N questions, skipped M.`, counted by the answers section's own rule, so it never disagrees with "x of y answered"), the person's words, `formatQuestionAnswersSection`, then the annotations' feedback. A reply that sends no answer and no skip (words, annotations, or both) has no first line and no answers section: the person's words, then the still-open line (`inboxStillOpenLine` in `packages/core/inbox-questions.ts`, called by `composeInboxReplyBody`; approval "inbox-words-only-reply", 2026-10-13), then the feedback. The line is "No questions answered yet; all N are still open. Don't re-ask them; the person will answer in the Inbox." (N: every question the replied-to message's session asked in this thread that is still open, or picked and not sent, so words that go to the session's later plain update still count the questions it asked before; another session's questions are never counted, and a message with no session counts only its own; for one: "No question answered yet; it is still open. Don't re-ask it; …"; when an earlier reply already answered some: "No new answers in this reply; N questions are still open. …"); there is none when nothing is left open. `INBOX_STILL_OPEN_LINE` matches it, and the folded line's `replyWords` cuts the reply there, so a snippet shows only the person's words. This holds for every caller, a body with no `skip_unanswered` (the phone door, an older window) included. The wake text is unchanged and carries this body. Plan review's export (`formatQuestionAnswersSection`, `packages/core/question-block.ts`) is untouched. - The sent questions are marked before the reply line lands. When the reply line never lands, they read as picked again, so a retry never reads "already sent" with nothing sent. -- After a Send, the reply shows "Saved for …" until an agent reads it or a connection delivers it, then "Delivered to , 10:52 AM". +- After a Send, the line under the person's last reply or message says where it is (`deliveryLine`, `packages/inbox/deliveryLine.ts`; the owner's request 2026-10-16, "it should say this message is queued up … and then maybe an option just to send it immediately"). For a session whose connection wakes it (a reply to a message with `wakes`, or a message with `to`), the window reads that session's connection every 3 s (`GET /api/inbox/threads/:id/sessions?asker=`, the additive `asker.connection` = `{ busy, idle_since, send_now }` while it polls, null when it does not): "Queued · Claude Code is working; it gets this when its turn ends." with **Send now** (`data-send-now`, only while `send_now`), "Sending to Claude Code…" while idle, "Queued for Claude Code; it gets this as its next turn." when the connection does not say (or an older Inbox), "… when its session is back." when it does not poll, "Sending to Claude Code now…" once Send now was pressed (`deliver_now_at`). A reply to an agent that only reads the thread (MCP, OpenCode 1) reads "Saved for . It sees it when it next reads this thread." Then "Delivered to , 10:52 AM", unchanged. The ended-session and Not delivered lines are unchanged. +- **Send now** (`POST /api/inbox/messages/:id/send-now`, window guards; door 7.58): the store writes `deliver_now_at` on the message (`requestDeliverNow`; a second press writes nothing; `already_delivered`, `not_addressed`), after the server checked the recipient's connection polls now and said it can deliver into a running turn (`send_now_unavailable` otherwise; `recipientOf` names the session). The bridge command then carries `now: true` and a held poll answers at once. The connection delivers it without waiting for idle: the Claude Code mod as a user row in the running turn (`$.session.append`, the one way a plugin puts words into a running turn: `$.prompt.submit` never folds into one; read at the turn's next model request; if the turn ended with no request after it, one short follow-up turn points at it, `inboxSentNowFollowUpText`), Pi as `sendUserMessage(..., { deliverAs: "steer" })`, OpenCode 2 as `session.prompt({ delivery: "steer" })`; idle, as a turn at once. A connection says it can with the poll field `send_now: true` (`INBOX_SEND_NOW_POLL_FIELD`): the mod always (it stops after an engine refuses the row), Pi and OpenCode 2 where the wake target has `steer`; OpenCode 1 and older connections never, so Send now is never offered there. Nothing is ever aborted. Claim-once holds: the same claim folder and lease as a normal delivery. Tests: `packages/server/inbox-send-now.test.ts` (routes, guards, the poll, agent-link's steer), `apps/hook/hooks/mod/inbox.test.ts` 12 and 13 (the mod against a real Inbox), `apps/hook/tests/register.test.ts` (the engine harness: the row through `$.session.append`), `packages/inbox/deliveryLine.test.ts`, the DOM test `packages/inbox/sendNow.test.tsx`, `tests/e2e/inbox-send-now.spec.ts` (compiled binary; light, dark and a phone). - No tool answers, approves or sends for the person. - **Paste to attach** (the owner, 2026-10-16: "When I'm writing a new message or even a reply, I need to be able to paste in images"). A paste in compose (anywhere in the dialog) or in the reply box (`.ib-rbox`'s `onPaste`) that carries files attaches them through compose's upload path, tiles and progress (`useComposeFiles().paste`, `packages/inbox/compose/ComposeFiles.tsx`; the rules in `packages/inbox/compose/paste.ts`). A clipboard image with a name nobody chose (`image.png`, `Pasted Graphic 2.png`, `blob`, none) is renamed `pasted-image-YYYY-MM-DD-HHMM.` in local time (`pasted-file-…` for anything else), `-2`, `-3` when the name is taken in this message; a real name (a file copied in the file manager) is kept. Text is never taken from the browser, because dictation apps (Hex) write the clipboard, post a synthetic paste and restore the old clipboard about 500 ms later: everything reads `event.clipboardData` synchronously inside the event, never `navigator.clipboard`; a paste of text alone is left wholly to the native path (no `preventDefault`); a paste of files beside text (an image copied from a page brings HTML, a file from Finder its name) attaches the files and still lets the browser insert the text (`clipboardHasText`); only files with no text is prevented. Text with an unnamed picture is text: a cell copied in Excel, Numbers or Pages carries a picture of itself, which Chromium hands over as `image.png`, so when the clipboard has non-empty `text/plain` only files with a real name attach (`isGenericPasteName`; a screenshot and Chrome's "Copy image" carry no plain text and attach, a Finder copy keeps its name). Each attach by paste is said politely ("Attached "): the thread's live region for the reply box, the dialog's own (`[data-compose-paste-live]`) for compose, since the window's region sits outside the modal dialog. Local previews' object URLs are freed on remove, reset and unmount. No paperclip, drop zone or shortcut in the reply box (the owner asked for paste only). - The reply box's files are tiles inside the box above its chips (`[data-reply-files]`, `.ib-rfiles`; each at least 200 px wide in a row, the whole box when that is narrower: they fit a 320 px phone, and a tile's × takes a 44 px hit area on a phone). They live with the box: Cancel, Escape, a Send and another thread forget them (uploads in flight are aborted; `useComposeFiles().reset`); there are no reply drafts. Send waits while one uploads ("Wait for the files to finish uploading."). The ids ride the reply that carries the words (the last target, with the words and annotations), as `uploads`. A Send clears only the files it carried (`useComposeFiles().forget`): one pasted while it was in flight keeps the box open for the next Send. A retry after a failed Send whose words, files or annotations changed takes a new idempotency key for the reply carrying them (`sendContents` in `Thread.tsx`), so a Send that went through but answered an error is never replayed in place of the changed one. The ended-asker note counts only finished uploads, as Send does. @@ -2275,7 +2276,7 @@ Sorting and the rest: - None: the button greys but stays pressable and opens " is not running in " with Reply instead (5.3). - One: the box opens addressed to it, "New message to in (live session, idle|working)" (5.1). - Several: one row each, with when it started and whether it wrote this thread, is idle or is working (5.2). - - The thread shows the message "to ", then " takes it as its next turn." until delivered, then "Delivered to ,