Skip to content
Draft
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
8 changes: 8 additions & 0 deletions docs/agent-guides/inbox-compose.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,14 @@
- **Words in one place.** The person-facing strings (tooltips "Remove quote" and "Go to the message", the screen-reader label, "Quote removed.") are `REPLY_QUOTE_WORDS` in `replyQuote.ts`. They are not yet approved word for word.
- Tests: `packages/inbox/replyQuote.test.tsx` (DOM), `tests/e2e/inbox-reply-quote.spec.ts`.

**Mention a thread in a reply** (approval `.product/approved/inbox-drag-threads/`, piece 1, treatment A "in the words"; `threadDrag.ts`, `replyMentions.tsx`, `threadMentions.ts`, `data/threadMentionRefs.ts`, `components/MentionMenuItem.tsx`, `components/useThreadRowDrag.ts`, `@plannotator/core/inbox-thread-mention`). The Inbox is Bun-only: no Pi server change, and no server or `api.ts` change at all.
- **Four ways in.** (1) Drag a list row (or the ⌘/Shift-picked rows, carried together) onto the open reply box. (2) "Mention in reply" in the row menu (right-click, the row's ⋮, a picked row's menu and the pick bar's ⋯ through `BulkItems`; "Mention 3 in reply" with several). (3) Paste this Inbox's `#thread=msg_…` link, or a bare thread id, into the box. (4) On a phone the row's sheet has the same item, named with the reply it goes to (the reply last written in); it opens that thread with the mention at the end of the words. No keyboard shortcut: the menu is reachable with Shift+F10 or the menu key on a row.
- **The drag** (`threadDrag.ts`) is a pointer drag, not native HTML drag and drop, so a file drop or a text drag in the box is untouched. A mouse or pen press moves 5 px before it lifts; touch never drags (the phone/iPad swipe and long press stay). A ghost pill follows the pointer (a stack with a count for several); the rows it came from keep a fill with their words faded. `:root[data-thread-drag]` is set while carrying. The box (`.ib-rbox`, or full screen's `.ib-fcomp`) gets `data-thread-drop="target"` only while a thread is carried, `"over"` under the pointer (a stronger tint and the "Drop to mention this thread" label; fills only, the box's edge never changes; a caret shows where it lands, snapped to the end of the word), `"refuse"` when the only thread carried is the one the box answers (quietly refused). Escape, a window blur or a drop elsewhere cancels; the click after a drag is swallowed. Held within 48 px of the list's top or bottom edge (`AUTO_SCROLL_BAND`), the list scrolls, faster nearer the edge; a drop target under the pointer always wins, so the next piece's edge places (Priority, Quiet, Archive) register as targets over those bands and stop the scroll while hovered. The ghost's classes are `ib-tdrag*` (`ib-tghost` is the toast's button). A polite live region (`[data-thread-drag-live]`) says what was picked up, cancelled or mentioned. Reduced motion: no lift, no fly-back, no flash, no blinking caret. A closed box and a box that is sending (read-only) are no target.
- **The token.** A mention is its label in the words: the thread's title (`mentionTitleOf`, one line, capped at 120), plus ` · project` when that differs from the reply's project. It is painted through the field's skill-token channel (`data-skill-ref-token="thread:<id>"`, `"thread-archived:<id>"` in grey), paint only. Several go in comma separated. Backspace right after one takes it whole. Which labels are mentions is kept per reply in this browser (`localStorage` `plannotator-inbox-reply-mentions`); an edit inside a label turns it back into words. A thread on another machine works and is marked as not readable from here.
- **Send.** `replyWordsWithMentions` turns the standing labels into the agent's words (`inboxThreadMentionWords`): each mention as `"Title" (thread msg_…)` at its spot, then a list after the words with each thread once, its project, archived or elsewhere, and how to read it. All of that wording is one constant, `INBOX_THREAD_MENTION_WORDS` in `packages/core/inbox-thread-mention.ts`, **pending the owner's approval word for word** (and a clean-room test). The agent reads a mentioned thread with `read_thread` and its `thread_id` (any thread on this machine). The mentioned thread is not changed.
- **The sent message** draws each mention as a link to its thread (`linkInboxThreadMentions` in `useBodyText.ts`: `[Title](#thread=msg_…)`, painted like the token with a thread mark), and leaves the list out; previews (`replyWords`) show the title alone.
- Tests: `packages/inbox/replyMentionsField.test.tsx` (DOM), `packages/inbox/threadMentions.test.ts`, `packages/core/inbox-thread-mention.test.ts`.

**The phone composer and its picker sheet** (approval `.product/approved/inbox-phone-composer-picker/`, 2026-11-09: the owner tried a prototype on an iPhone and said "the mobile changes are fine. I don't necessarily want the desktop changes"; `packages/inbox/phoneComposer.css`, `components/BottomSheet.tsx`, `components/SheetRow.tsx`, `components/AgentPill.tsx`, `components/PhoneReplyRecipient.tsx`, `compose/PhoneToSheet.tsx`). A phone only (`usePhone`, `PHONE_QUERY`): a computer's reply box, New message and pickers are unchanged, pixel for pixel.
- **Where the split is.** Two places choose the phone's parts: `rcptPill` in `Thread.tsx` (`PhoneReplyRecipient` or `ReplyRecipient`) and To's list in `ComposeDialog.tsx` (`PhoneToSheet` kept mounted, or `ToPicker`); `ComposeDialog` also draws `phoneTo`, `phoneStartIn` and the card's wrapper only on a phone. The look is `phoneComposer.css`, imported by `apps/inbox/index.css` after `inbox.css`: its components' own rules, then one block inside `PHONE_QUERY` for everything a computer also draws (`phoneComposer.test.tsx` fails on such a rule outside that block). `inbox.css` is untouched, since it also ships to another app as `@plannotator/ui/inbox-thread.css`; the phone's older rules for the pill on the line over the row and for To's fold stay there, unused by this window.
- **One card.** The reply box (`.ib-rbox`) and New message's words with their row (`.ib-cp-pcard`, `[data-compose-pcard]`) are one rounded card: radius 28, 8 px from the left and right edges and 8 px above the keyboard (or the home bar). The flat strip under the thread is gone: the foot that holds the box keeps the pane's colour and has no hairline or shadow of its own. The scale: gap 8, card padding 10, controls 36 px round with a 44 px hit area (`::after`), text 16 px (iOS zooms the page into a smaller field).
Expand Down
2 changes: 2 additions & 0 deletions docs/agent-guides/inbox-messages.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,8 @@
- **The person's words.** `replyWords` (`inbox-folding.ts`) and `withoutInboxReplyQuoteLead` strip the lead, so snippets, the list's preview and the excerpt of a quoted reply show the person's words. The window strips it from a drawn reply only when that message has `quote`. Copy message copies the body as stored, lead included.
- Tests: `packages/core/inbox-reply-quote.test.ts`, `packages/shared/inbox/store-reply-quote.test.ts`, the wake case in `packages/server/inbox-wake-context.test.ts`.

**A thread mentioned in a reply** (approval `.product/approved/inbox-drag-threads/`, piece 1; the window side is "Mention a thread in a reply" in `inbox-compose.md`). The window writes the agent's words before Send, so the store and a linked machine's older Inbox get ordinary words: each mention as `"Title" (thread msg_…)` where it stood, then a list after the words (a heading line, `- msg_… "Title"`, and indented lines for the project, archived or another machine, and how to read it). The wording is `INBOX_THREAD_MENTION_WORDS` in `@plannotator/core/inbox-thread-mention`, pending the owner's approval. The window recovers the threads from that list (`splitInboxThreadMentions`, exact lines only) to draw links, and `replyWords` leaves it out of previews.

**Saving an answer** (`packages/inbox/pickQueue.ts`; the owner's debug log, 2026-11-02: a dictated "Other" answer queued 81 saves on a phone over a tailnet, and a Send waited 7.2 s behind them). A question card calls `commit` on every change (`QuestionBlock`: each key, each step of a dictation). The window saves a click at once, and typed words after a pause:
- **Typed words wait for a pause** (`packages/inbox/typedAnswers.ts`, 2026-11-10: every key used to save a full copy of the question, 212 MB of `questions.jsonl` for one person, and each save redrew the thread and read the list and drafts). A change that only edits the words of "Other…", a free-text answer or a note (`isTypedChange`) waits `TYPED_ANSWER_SAVE_MS` (the reply box's 500 ms) after the last key. The field draws every key at once from `pending`. The words waiting go at once on: a click or pick anywhere on the cards (a choice, Skip, Accept recommended, the suggested answer's row), the field losing focus, every wait of the line (`settled()`, each Send round and the line closing, Re-ask, Mod+Enter, the stale page's Reload), the pane moving to another thread or closing, and the page hiding or going (`pagehide`, `visibilitychange`: sent with `keepalive`, through the line when no save of that question is out, else on its own at the next revision). The first words on an unanswered question, a choice, Skip and a cleared answer change the question's state, so they save at once. A save that fails with words waiting puts them in the line at once, and they decide.
- **One save at a time, the newest answer next.** A thread's saves run one by one: a save answers its message's questions whole, and each save's revision comes from the one before. While one runs, each question keeps only its newest answer waiting, in the place in the line it first took, so answers to other questions all save, each once.
Expand Down
4 changes: 3 additions & 1 deletion packages/core/inbox-folding.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ import { INBOX_STILL_OPEN_LINE, sliceText } from './inbox-questions';
import { withoutInboxSkillsBlock } from './skill-reference-block';
import { INLINE_DESTINATION, stripInlineMarkup } from './inline-markdown';
import { withoutInboxReplyQuoteLead } from './inbox-reply-quote';
import { withoutInboxThreadMentions } from './inbox-thread-mention';

/**
* Where "new since you looked" starts: the seq of the person's last look at
Expand Down Expand Up @@ -213,7 +214,8 @@ const ANSWERS_HEADING_LINE = new RegExp(`^#{1,6}\\s+${QUESTION_ANSWERS_HEADING}\
* lead a quoting reply opens with (`withoutInboxReplyQuoteLead`).
*/
export function replyWords(body: string): string {
const lines = withoutInboxSkillsBlock(body).split(/\r?\n/);
// A mentioned thread (inbox-thread-mention.ts) reads as its title; the list after the words is the agent's.
const lines = withoutInboxThreadMentions(withoutInboxSkillsBlock(body)).split(/\r?\n/);
const at = lines.findIndex((line) => ANSWERS_HEADING_LINE.test(line.trim()) || INBOX_STILL_OPEN_LINE.test(line.trim()));
const kept = (at >= 0 ? lines.slice(0, at) : lines).join('\n');
// A quoting reply's lead ("Replying to your message from …", inbox-reply-quote.ts) is the agent's, not the person's words.
Expand Down
91 changes: 91 additions & 0 deletions packages/core/inbox-thread-mention.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
/**
* A thread mentioned in a reply (approval "inbox-drag-threads", piece 1). What regresses: the agent's words losing
* the thread's id at the mention's spot, wording spelled outside the one constant (the owner approves it word for
* word), the window drawing the agent's list or the inline form instead of a link, and previews showing them.
*/
import { describe, expect, test } from 'bun:test';
import { replyWords } from './inbox-folding';
import {
INBOX_THREAD_MENTION_WORDS as W,
inboxThreadMentionList,
inboxThreadMentionTitle,
inboxThreadMentionWords,
linkInboxThreadMentions,
splitInboxThreadMentions,
withoutInboxThreadMentions,
} from './inbox-thread-mention';

const FLAKY = { id: 'msg_01JD5FLAKYLOGINTESTCI000', title: 'Flaky login test on CI', project: 'harbor' };
const RATE = { id: 'msg_01JD5RATELIMITPUBLICAPI0', title: 'Rate limit for the public API', project: 'ledger-api', archived: true };

function spanOf(words: string, label: string, ref: typeof FLAKY | typeof RATE) {
const start = words.indexOf(label);
return { ref, start, end: start + label.length };
}

describe('the words the agent reads', () => {
test('each mention keeps its spot with its id, and the list after the words names every thread once, all from the one constant', () => {
const words = 'Same root cause as Flaky login test on CI; see Rate limit for the public API · ledger-api and Flaky login test on CI.';
const second = words.lastIndexOf(FLAKY.title);
const out = inboxThreadMentionWords(words, [
spanOf(words, FLAKY.title, FLAKY),
spanOf(words, 'Rate limit for the public API · ledger-api', RATE),
{ ref: FLAKY, start: second, end: second + FLAKY.title.length },
]);
const expected =
`Same root cause as ${W.inline(FLAKY.title, FLAKY.id)}; see ${W.inline(RATE.title, RATE.id)} and ${W.inline(FLAKY.title, FLAKY.id)}.` +
`\n\n${W.heading}\n${W.item(FLAKY.id, FLAKY.title)}\n ${W.details(FLAKY)}.\n ${W.read(FLAKY.id)}` +
`\n${W.item(RATE.id, RATE.title)}\n ${W.details(RATE)}.\n ${W.read(RATE.id)}`;
expect(out).toBe(expected);
// The id is in the words at the mention, not only in the list.
expect(out.indexOf(FLAKY.id)).toBeLessThan(out.indexOf(W.heading));
expect(W.details(RATE)).toContain('archived');
});

test('a thread on another machine says it cannot be read from here, and gets no read line', () => {
const list = inboxThreadMentionList([{ id: FLAKY.id, title: FLAKY.title, elsewhere: true }]);
expect(list).toContain(W.details({ elsewhere: true }));
expect(list).not.toContain(W.read(FLAKY.id));
});

test('no mention: the words as they are; an overlapping or stale span is left as plain words', () => {
expect(inboxThreadMentionWords('plain words', [])).toBe('plain words');
expect(inboxThreadMentionWords('short', [{ ref: FLAKY, start: 2, end: 99 }])).toBe('short');
});

test('a title is one line and capped', () => {
expect(inboxThreadMentionTitle('two\nlines​ here')).toBe('two lines here');
expect([...inboxThreadMentionTitle('x'.repeat(500))].length).toBe(121);
expect(inboxThreadMentionTitle(' ')).toBe('Untitled thread');
});
});

describe('what the window draws', () => {
const body = inboxThreadMentionWords('Fix it like Flaky login test on CI did.', [spanOf('Fix it like Flaky login test on CI did.', FLAKY.title, FLAKY)]);

test('a sent mention is a link to its thread, and the list is not drawn', () => {
expect(linkInboxThreadMentions(body)).toBe(`Fix it like [Flaky login test on CI](#thread=${FLAKY.id}) did.`);
});

test('a title with markdown in it stays the link text', () => {
const odd = { id: FLAKY.id, title: 'Fix [x] *now*' };
const sent = inboxThreadMentionWords('See Fix [x] *now*', [{ ref: odd, start: 4, end: 17 }]);
expect(linkInboxThreadMentions(sent)).toBe(`See [Fix \\[x\\] \\*now\\*](#thread=${FLAKY.id})`);
});

test('a preview reads the title alone (replyWords)', () => {
expect(withoutInboxThreadMentions(body)).toBe('Fix it like Flaky login test on CI did.');
expect(replyWords(body)).toBe('Fix it like Flaky login test on CI did.');
});

test('words that only look like a list are left alone', () => {
const typed = `${W.heading}\nnothing listed`;
expect(splitInboxThreadMentions(typed)).toBeNull();
expect(linkInboxThreadMentions(typed)).toBe(typed);
});

test('what the store adds after the words (answers) stays', () => {
const withAnswers = `${body}\n\nAnswers:\n1. Yes`;
expect(linkInboxThreadMentions(withAnswers)).toBe(`Fix it like [Flaky login test on CI](#thread=${FLAKY.id}) did.\n\nAnswers:\n1. Yes`);
});
});
Loading
Loading