Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
10 changes: 5 additions & 5 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2214,12 +2214,12 @@ Sorting and the rest:
- The phone door allows `threads/:id/read` and `threads/:id/unread` (`inbox-devices.ts` ALLOWLIST); the list row's `read_at` and the question's `set_aside_at` are additive. The surface draws no list or thread, so it is unchanged.
- Tests: `packages/shared/inbox/store-mark-read.test.ts` (the rules, the note, a replay, a store older than Mark read), `packages/shared/inbox/store-words-only-reply.test.ts` and `packages/core/inbox-reply-sentence.test.ts` (a reply with no answers: the exact agent text, words, annotations, one question, an earlier answer; partial replies unchanged), `packages/core/question-answer-by-reply.test.ts`, `packages/server/inbox-mark-read.test.ts` (the routes and guards, the note through `wait_for_reply`, no decision on a skip, a words-only reply through `wait_for_reply`), the DOM test `packages/inbox/markRead.test.tsx` (the whole window over a real Inbox run by `tests/helpers/inbox-dom-server.ts`; the chip's default with and without a pick; it includes the one-session thread whose words-only Send switched to skip is one reply), and `tests/e2e/inbox-mark-read.spec.ts` on the compiled binary.

**πŸ‘ Looks good** (approval "inbox-acknowledge", 2026-10-15; not in this repo). A silent acknowledgment: "cool, looks good" without waking the agent for a turn.
**πŸ‘ Looks good** (approval "inbox-acknowledge", 2026-10-15, amended 2026-10-16; not in this repo). "Cool, looks good": the thread goes to Quiet, and after the Undo window the πŸ‘ is sent to the agent that wrote the message as one short turn. The amendment, the owner verbatim: "I replied with looks good, but I realized that doesn't send through. I think we just need to send looks good through, honestly." Before it the πŸ‘ was silent (agents saw it only on their next read).
- The thread's foot is `[↩ Reply] [πŸ‘ Looks good]` side by side (44 px each on a phone); πŸ‘ is hidden while any question in the thread is open or picked (and while picks or annotations wait to be sent), once the person wrote back (the last message, the Inbox's notes read past, is theirs), on an archived thread, and with no agent message. No new key; the toast's `Z` undoes.
- `POST /api/inbox/messages/:id/ack` (`{ serverSession?, ack? }`, `ack: false` takes it back; the window's same-origin and `serverSession` guards) β†’ `InboxStore.ackMessage`: an additive `ack: { label: "Looks good", at, read_seq, made_read, settled_seq, settled_at, seen_at }` snapshot line on the agent's message, plus Mark read (`read_seq` = the Mark read it stands on, `made_read` = the πŸ‘ made it). Undo removes the ack and undoes the Mark read only when the πŸ‘ made it. Move back (`/unread`, `E`) on that Mark read withdraws the ack too, so the agent never sees a πŸ‘ on a thread the person moved back. Refused: `422 ack_not_allowed` (a person's message), `409 ack_stale` (not the thread's latest agent message), `409 ack_after_reply` (a person message, not an Inbox note, follows it: the reply is the answer and keeps its Sent / Delivered state), `409 question_open`, `409 thread_resolved`. A second πŸ‘ writes nothing. In a one-message thread the root is the agent message, so `markRead` re-reads the root after withdrawing.
- Nothing is sent and nothing wakes: no person message, no bridge command (`pendingReplies` is person-only), no push. After the Undo window (`setAsideDelayMs`, the set-aside note's 10 s), the server writes `settled_seq`/`settled_at` (`settleAcks`; swept at start too). Only then do agents see it: `read_thread` carries `ack: { label, at }` (`store.agentThread`), and `wait_for_reply` returns `{ status: "acknowledged", acks: [{ message_id, label, at }], cursor }` for an ack on the caller's latest message in a thread it waits on (replies first; not a person reply). Either one writes `seen_at` (`markAcksSeen`). A wait across every thread the caller asked (no thread id, no cursor) skips an ack already seen, so an old πŸ‘ on a finished thread never answers a later wait; a wait on one named thread keeps answering it.
- The window: the button pressed (`aria-pressed`, success tint; a click takes it back), a pill under the message "πŸ‘ Looks good Β· You, <time> Β· not sent; <agent> sees it when it next reads this thread", then "<agent> saw it, <time>" from `seen_at` (never "Delivered"); the row's `ack` (additive, while the Mark read it made holds) reads "πŸ‘ Looks good" in place of "Read"; the one toast "πŸ‘ Looks good Β· Moves to Quiet Β· not sent to <agent>" with Undo. Held order as for Mark read.
- The thread-state model has an `ack` op (property runs only; the trace fixtures are unchanged). Phone door: `POST messages/:id/ack` (contract 7.56). Tests: `packages/server/inbox-ack.test.ts`, the DOM test `packages/inbox/ack.test.tsx`, `tests/e2e/inbox-ack.spec.ts`.
- Inside the Undo window (`setAsideDelayMs`, the set-aside note's 10 s) nothing is sent: the toast's Undo (or `Z`) takes it back with nothing written for the agent. After it, `settleAcks` (swept at start too) writes two lines: the ack with `settled_seq`/`settled_at` and `note_id`, then the note it names, a person's message with `ack_of: <message id>`, `reply_to` that message and body `inboxAckLine(<message id>)` ("The person marked your message πŸ‘ Looks good (<message id>). No reply needed unless you have a question."; `packages/shared/inbox/connection.ts`, the mod's copy too). The note rides the reply machinery unchanged, so delivery is exactly once by the existing claim, lease and `delivered` event: `pendingReplies` hands it to the session that wrote the message (`isFor`), and the bridge command is a `reply` with `ack_of`, whose wake (`inboxWakeText`) is `Plannotator Inbox: <subject> (<note id>)` and the ack line alone (an older connection words it as a reply with the line as the person's words). The note is an Inbox note (`isInboxNote` includes `ack_of`): the list's `sent`, `unseen`, the look and "came back" read past it, `readAt` keeps the thread read, and `thread()` (so the window, `read_thread`, search's thread reads and `threadSummary`'s count and `last_at`) leaves it out; the ack on the message says it. Delivered only while the ack still names it (`ackNoteLive`): a πŸ‘ taken back after it settled (the pressed button, Move back) and before delivery is never delivered, and a later πŸ‘ is a new note. At settle `ackMessage`'s conditions are checked again (`ackNotSentReason`): when the agent wrote again after the message inside the window (the πŸ‘ would read as the answer to the newer one) or the person sent a reply after it (their reply is the answer; the πŸ‘ button is hidden by then, so they could not take it back), the ack settles with `not_sent: "replied" | "wrote_again"` and no note, no agent ever sees it (`agentThread`, `markAcksSeen`, `wait_for_reply`), and the line reads "πŸ‘ Looks good Β· not sent: you replied" / "… not sent: <agent> wrote again". Agents also see it in `read_thread` (`ack: { label, at }`, `store.agentThread`) and `wait_for_reply` returns `{ status: "acknowledged", acks: [{ message_id, label, at }], cursor }` for an ack on the caller's latest message (replies first; the note line itself never answers as a reply), which records the note's delivery, so the wake never hands it again; a delivery through the wake marks the ack seen, so neither hands it twice. A wait across every thread the caller asked (no thread id, no cursor) skips an ack already seen; a wait on one named thread keeps answering it. A store from before the amendment replays unchanged: its settled acks have no `note_id`, were never sent, and are not sent now.
- The window: the button pressed (`aria-pressed`, success tint; a click takes it back), a line under the message (`AckPill`, `ackPillLine` in `packages/inbox/components/Thread.tsx`, `data-ack-pill`): "πŸ‘ Looks good Β· You, <time> Β· goes to <agent> in a few seconds" inside the Undo window (`pending`), then "… Queued for <agent>; it gets this as its next turn." for a message from a waking connection (`queued`, `message.wakes`) or "… Saved for <agent>. It sees it when it next reads this thread." otherwise and for an older settled ack (`saved`), then "πŸ‘ Looks good Β· Delivered to <agent>, <time>" (`delivered`) from the window thread's additive `ack.delivered_at` (the note's delivery, else `seen_at`); the wording follows the reply's delivery line (#1968). The row's `ack` (additive, while the Mark read it made holds) reads "πŸ‘ Looks good" in place of "Read"; the one toast "πŸ‘ Looks good Β· Moves to Quiet Β· goes to <agent> unless you undo" with Undo. Held order as for Mark read.
- The thread-state model has an `ack` op (property runs only; the trace fixtures are unchanged). Phone door: `POST messages/:id/ack` (contract 7.56). Tests: `packages/shared/inbox/store-ack-delivery.test.ts` (the two lines, once, taken back before delivery, Move back, replay, a store from before the amendment), `packages/server/inbox-ack.test.ts` (the routes, the bridge command and wake text, a held poll, Undo inside the window, `acknowledged` as the delivery, a restart, and the Pi and OpenCode `InboxWake` with stand-in targets), the mod against a real Inbox (`apps/hook/hooks/mod/inbox.test.ts` 12: one turn after the window, the exact text, Delivered), the DOM test `packages/inbox/ack.test.tsx` (every line state; the DOM server takes `INBOX_DOM_SET_ASIDE_MS` and a `deliver` stdin command), `tests/e2e/inbox-ack.spec.ts`.

**The project menu** (design record "inbox-project-menu", approved 2026-10-14; not in this repo). Each sidebar project has a menu: **Mark all as read** and **Archive all**, with one Undo per batch.
- Opening it: the row's **β‹―** (`components/ProjectRow.tsx`), a real button beside the row (`.ib-projrow` > `.ib-proj` + `.ib-pmore`, the Settings row's pattern, never one inside the other; named "<project> options", `aria-haspopup="menu"`), shown on hover, on keyboard focus (`:has(:focus-visible)`) and while its menu is open, in place of the count (hidden for the eye only, so the row button's accessible name keeps it: "pando 1"); or a right-click on the row (at the pointer). Both are Base UI (`Menu`, `ContextMenu`): arrows, Home/End, type-ahead, Escape and Tab close, focus back to β‹―. The menu is the Inbox's dropdown look (`.ib-pm`, the search chips' `.ib-sp-menu` values), portaled into `.pn-inbox`; the row whose menu is open keeps a muted background (`data-menu`). No new shortcut (the platform's context-menu key reaches the row by itself; the toast's `Z` undoes). On a phone (`PHONE_QUERY`) β‹― is always shown (44 px, after the count), there is no right-click or long-press, and the menu is a sheet from the bottom edge titled by the project (`aria-hidden`: the popup's `aria-label` names it; `.ib-pm-pos[data-phone]`, `Menu.Backdrop` scrim), 48 px items; an action closes the navigation sheet.
Expand Down Expand Up @@ -2771,7 +2771,7 @@ Not covered, by design: the Inbox's tailnet listener ("Over your tailnet": it an
| `/api/inbox/threads/:id/seen` | POST | `{ serverSession?, through_seq? }`: the person looked at the thread; its agent messages so far leave "New since you looked". `through_seq` (optional, a whole number: the seq of the newest message the window showed) caps the look at the agent messages at or below it; at or behind the recorded look it writes nothing (a look never goes back), past the newest message it is the newest; anything else is `422 validation_error` (`field: "through_seq"`). Writes nothing when nothing is new. Returns `{ thread: row }` |
| `/api/inbox/threads/:id/read` | POST | `{ serverSession? }`: Mark read. The thread goes to Quiet without archiving; its questions still waiting on the person close unanswered (skips, no decision); counts as a look. After the Undo window the asking agents get one set-aside note. Same-origin and `serverSession` guards; `409 thread_resolved` on an archived thread. Returns `{ thread: row }` (`read_at` set) |
| `/api/inbox/threads/:id/unread` | POST | `{ serverSession? }`: Undo Mark read: reopens the questions that Mark read closed as they were (a saved pick included); an earlier Mark read's stay closed. Same guards. Returns `{ thread: row }` |
| `/api/inbox/messages/:id/ack` | POST | `{ serverSession?, ack? }`: πŸ‘ Looks good on the thread's latest agent message (silent: nothing sent, no wake) plus Mark read; `ack: false` takes both back. Same guards. Returns `{ message, thread: row }`; `422 ack_not_allowed`, `409 ack_stale` / `ack_after_reply` / `question_open` / `thread_resolved` (see "πŸ‘ Looks good") |
| `/api/inbox/messages/:id/ack` | POST | `{ serverSession?, ack? }`: πŸ‘ Looks good on the thread's latest agent message plus Mark read, sent to the agent after the Undo window (a note delivered like a reply); `ack: false` takes both back. Same guards. Returns `{ message, thread: row }`; `422 ack_not_allowed`, `409 ack_stale` / `ack_after_reply` / `question_open` / `thread_resolved` (see "πŸ‘ Looks good") |
| `/api/inbox/threads/:id/sessions` | GET | New message: the live agent sessions of the thread's project, `{ home, project, sessions: [{ session, host, started_at, last_seen_at, busy, idle_since, wrote_thread }] }`, the thread's writers first (latest writer first), then by start. `?asker=<session>` adds `asker: { session, live }`: whether the session that asked is still there, with a 60 s grace (see "Replying when the asking session has ended") |
| `/api/inbox/threads/:id/message` | POST | New message: `{ serverSession?, session, body, idempotency_key }` writes the person's words to that live session (`to` on the message); same-origin and `serverSession` guards; `409 session_not_live` when the session is not live (nothing written); a replayed key answers the message it wrote |
| `/api/inbox/sessions` | GET | Compose: every live session, `{ serverSession, home, projects: [{ project: { id \| null, name, root }, sessions: [{ session, host, started_at, last_seen_at, busy, idle_since, last_thread: { id, subject, at } \| null }] }] }`, the most recently active project first. `?session=<id>` adds `session: { session, live }` with the asker grace. Also on the phone door (contract 7.39) |
Expand Down
2 changes: 1 addition & 1 deletion adr/implementation/inbox-mobile.md
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,7 @@ The allowlist. Each row is the window's handler as it is today, with the request
| `POST messages/:id/picks` | same | `{ idempotency_key, questions: [{ key, revision, answer or null }] }` | `{ message_id, questions, reply: null }` | 7.10 |
| `POST messages/:id/reply` | same | `{ idempotency_key, words?, questions?, feedback?, annotation_ids?, skip_unanswered?, uploads? }` (`skip_unanswered: true` skips the message's questions left without a pick; a phone sends it only as the window does, see 7.11; `uploads`: `upl_` ids from 7.48, which become attachments on the reply, see 7.57) | `{ message_id, questions, reply, replayed, decisions, decisions_refused }` | 7.11 |
| `POST messages/:id/resolve` | same | `{ idempotency_key, resolved? }` | `{ thread: summary }` | 7.12 |
| `POST messages/:id/ack` | same | `{ idempotency_key, ack? }` (`ack: false` takes it back) | `{ message, thread: row }`: πŸ‘ Looks good (design record "inbox-acknowledge", 2026-10-15). Silent: nothing is sent, no session is woken, no push. The message gains `ack: { label, at, read_seq, made_read, settled_seq, settled_at, seen_at }` and the thread is marked read (Quiet until an agent writes again); the row gains the additive `ack: { label, at }` while that read holds (draw "πŸ‘ Looks good" in place of "Read"). `ack: false` removes it and undoes the Mark read when the πŸ‘ made it (`made_read`); `threads/:id/unread` on that read withdraws the ack too. Only the thread's latest agent message, only while no question in the thread is open or picked and the person has not replied after it: `422 ack_not_allowed` (a person's message), `409 ack_stale` (a newer agent message), `409 ack_after_reply`, `409 question_open`, `409 thread_resolved`. An Inbox before it answers `404 device_route_not_found`. Added 2026-10-15 | 7.56 |
| `POST messages/:id/ack` | same | `{ idempotency_key, ack? }` (`ack: false` takes it back) | `{ message, thread: row }`: πŸ‘ Looks good (design record "inbox-acknowledge", 2026-10-15). Silent: nothing is sent, no session is woken, no push. The message gains `ack: { label, at, read_seq, made_read, settled_seq, settled_at, seen_at }` and the thread is marked read (Quiet until an agent writes again); the row gains the additive `ack: { label, at }` while that read holds (draw "πŸ‘ Looks good" in place of "Read"). `ack: false` removes it and undoes the Mark read when the πŸ‘ made it (`made_read`); `threads/:id/unread` on that read withdraws the ack too. Only the thread's latest agent message, only while no question in the thread is open or picked and the person has not replied after it: `422 ack_not_allowed` (a person's message), `409 ack_stale` (a newer agent message), `409 ack_after_reply`, `409 question_open`, `409 thread_resolved`. An Inbox before it answers `404 device_route_not_found`. Added 2026-10-15. Amended 2026-10-16 (the owner: "send looks good through"): once the Undo window passes with the πŸ‘ standing, the Inbox delivers it to the agent through a note, a person's message carrying `ack_of: <message id>` (body "The person marked your message πŸ‘ Looks good (<message id>). No reply needed unless you have a question."), and the ack gains `note_id`; when the person replied or the agent wrote again inside the window, the ack settles with `not_sent: "replied" \| "wrote_again"` and no note. **A phone never displays a message with `ack_of`**: the thread route leaves it out, but the relay and the event stream send every store line, so a phone that builds threads from lines must drop it (it is one of the Inbox's own notes, like `set_aside` and `reopened`: not the person's reply, not a look). The window's thread adds `ack.delivered_at` (when it reached the agent) | 7.56 |
| `POST messages/:id/to` | same | `{ idempotency_key, to: { host?, session } }` | `{ message, row }`: Send to another session, for a person message no session took yet. `409 already_delivered`, `409 thread_resolved`, `422 not_addressed`, `409 session_not_live` pass through. Added 2026-10-15 | 7.41 |
| `POST threads/:id/delete` | same | `{ idempotency_key }` | `{ ok, store }` | 7.13 |
| `GET threads/:id/attachments` | same | | `{ serverSession, attachments: [state], inline_images: [state], annotations }` (`inline_images` additive, 2026-10-15) | 7.14 |
Expand Down
Loading
Loading