Skip to content
Closed
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
49 changes: 47 additions & 2 deletions convex/phone.ts
Original file line number Diff line number Diff line change
Expand Up @@ -460,7 +460,7 @@ export const command = query({
const c = await ctx.db.get(commandId);
if (!c) throw new ConvexError({ kind: 'notFound', message: 'no such command' });
let result: unknown;
if (c.kind === 'slashCommands' && c.result) {
if ((c.kind === 'slashCommands' || c.kind === 'designReviews') && c.result) {
try {
result = JSON.parse(c.result);
} catch {
Expand Down Expand Up @@ -781,6 +781,51 @@ export const slashCommands = mutation({
},
});

// Reviews use the owning runner's durable revision checks and response queue.
export const reviewImages = query({
args: { token: v.string(), threadId: v.string(), sources: v.array(v.string()) },
returns: v.array(phoneImage),
handler: async (ctx, { token, threadId, sources }) => {
await checkPhoneToken(ctx, token);
await findThread(ctx, threadId);
if (sources.length > 40 || sources.some(src => !/^review:[a-zA-Z0-9-]{1,200}:[a-f0-9]{64}$/.test(src))) throw new ConvexError('Invalid review pictures.');
const out = [];
for (const src of new Set(sources)) {
const img = await ctx.db.query('replyImages').withIndex('by_thread_src', q => q.eq('threadId', threadId).eq('src', src)).order('desc').first();
if (!img) continue;
const url = await ctx.storage.getUrl(img.storageId);
if (url) out.push({ seq: img.seq, src, url, ...(img.width ? { width: img.width } : {}), ...(img.height ? { height: img.height } : {}) });
}
return out;
},
});

export const designReviews = mutation({
args: { token: v.string(), threadId: v.string(), reviewId: v.optional(v.string()) },
returns: v.id('commands'),
handler: async (ctx, { token, threadId, reviewId }) => {
await checkPhoneToken(ctx, token);
if (reviewId !== undefined && !/^[a-zA-Z0-9-]{1,200}$/.test(reviewId)) throw new ConvexError('Invalid review id.');
const t = await findThread(ctx, threadId);
return queue(ctx, t.runnerId, 'designReviews', threadId, reviewId ? { reviewId } : {});
},
});

export const respondReview = mutation({
args: { token: v.string(), threadId: v.string(), reviewId: v.string(), revision: v.number(),
draft: v.object({ pickedId: v.optional(v.string()), pickedIds: v.optional(v.array(v.string())),
notes: v.record(v.string(), v.string()), reply: v.optional(v.string()), none: v.optional(v.boolean()) }) },
returns: v.id('commands'),
handler: async (ctx, { token, threadId, reviewId, revision, draft }) => {
await checkPhoneToken(ctx, token);
if (!/^[a-zA-Z0-9-]{1,200}$/.test(reviewId) || !Number.isSafeInteger(revision) || revision < 0) throw new ConvexError('Invalid review or revision.');
if ((draft.pickedIds?.length ?? 0) > 12 || Object.keys(draft.notes).length > 12 ||
(draft.reply?.length ?? 0) > 8000 || Object.values(draft.notes).some(n => n.length > 4000)) throw new ConvexError('The review answer is too long.');
const t = await findThread(ctx, threadId);
return queue(ctx, t.runnerId, 'respondReview', threadId, { reviewId, revision, draft });
},
});

// Stop (API 69): ends the thread's running turn, as Stop on the Mac does.
// The `interrupt` command the main Mac sends another runner (relay.ts),
// which every runner from API 44 on applies.
Expand Down Expand Up @@ -1190,7 +1235,7 @@ async function knownRunner(ctx: QueryCtx, runnerId: string): Promise<string> {
// what the runner's own pendingCommands reads. One that waits too long goes
// (sync:pruneFiles, COMMAND_KEEP_MS). Its photos are recorded in commandFiles
// so a delete elsewhere sees they're still on their way (sync.ts storageInUse).
async function queue(ctx: MutationCtx, runnerId: string, kind: 'send' | 'respond' | 'update' | 'create' | 'page' | 'share' | 'quickAsk' | 'schedule' | 'picture' | 'press' | 'slashCommands' | 'interrupt', threadId: string | undefined, args: Record<string, unknown>) {
async function queue(ctx: MutationCtx, runnerId: string, kind: 'send' | 'respond' | 'update' | 'create' | 'page' | 'share' | 'quickAsk' | 'schedule' | 'picture' | 'press' | 'slashCommands' | 'interrupt' | 'designReviews' | 'respondReview', threadId: string | undefined, args: Record<string, unknown>) {
let n = 0;
let bytes = docBytes(args);
for await (const c of ctx.db.query('commands').withIndex('by_runner_state', (q) => q.eq('runnerId', runnerId).eq('state', 'pending'))) {
Expand Down
3 changes: 2 additions & 1 deletion convex/schema.ts
Original file line number Diff line number Diff line change
Expand Up @@ -549,7 +549,7 @@ export default defineSchema({
runnerId: v.string(), // or "any"
threadId: v.optional(v.string()),
// interrupt and call (API 44) come only from the main Mac's runner (relay.ts queueCommand).
kind: v.union(v.literal('send'), v.literal('respond'), v.literal('update'), v.literal('create'), v.literal('page'), v.literal('share'), v.literal('quickAsk'), v.literal('interrupt'), v.literal('call'), v.literal('schedule'), v.literal('picture'), v.literal('press'), v.literal('slashCommands')),
kind: v.union(v.literal('send'), v.literal('respond'), v.literal('update'), v.literal('create'), v.literal('page'), v.literal('share'), v.literal('quickAsk'), v.literal('interrupt'), v.literal('call'), v.literal('schedule'), v.literal('picture'), v.literal('press'), v.literal('slashCommands'), v.literal('designReviews'), v.literal('respondReview')),
args: v.any(),
state: v.union(v.literal('pending'), v.literal('taken'), v.literal('done'), v.literal('failed')),
note: v.optional(v.string()),
Expand Down Expand Up @@ -1065,6 +1065,7 @@ export default defineSchema({
height: v.optional(v.number()),
})
.index('by_thread_seq', ['threadId', 'seq'])
.index('by_thread_src', ['threadId', 'src'])
.index('by_storageId', ['storageId']),

// This backend's registration with the push relay (docs/push-relay.md),
Expand Down
2 changes: 1 addition & 1 deletion convex/sync.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2770,7 +2770,7 @@ export const finishCommand = mutation({
// And (API 77) a login or model change's: the login and model that
// runner applied, which may not be the model asked for.
const settings = c.kind === 'update' && (c.args?.accountId !== undefined || c.args?.model !== undefined);
const kept = ok && (c.kind === 'call' || c.kind === 'slashCommands' || settings) && result !== undefined && utf8Bytes(result) <= RESULT_MAX_BYTES ? cleanResult(result) : undefined;
const kept = ok && (c.kind === 'call' || c.kind === 'slashCommands' || c.kind === 'designReviews' || settings) && result !== undefined && utf8Bytes(result) <= RESULT_MAX_BYTES ? cleanResult(result) : undefined;
// The thread a create made is the command's runner's (it writes the row
// before finishing): never another runner's id, which the main Mac would
// then open as this runner's new thread.
Expand Down
3 changes: 2 additions & 1 deletion convex/version.ts
Original file line number Diff line number Diff line change
Expand Up @@ -389,4 +389,5 @@
// already, so nothing changes for them.
// phone:thread and the lists hold rows written before to the same rule
// as they read them.
export const API_VERSION = 82;
// 83: phone design review reads and responses through the owning runner.
export const API_VERSION = 83;
2 changes: 1 addition & 1 deletion docs/forking.md
Original file line number Diff line number Diff line change
Expand Up @@ -160,7 +160,7 @@ runner, app and phone; it's usually better to hide its entry point.
| Pools and Usage | `runner/src/pools.ts`, `usage*.ts`, `token-tally.ts`, `accounts.ts`; app `PoolsModel.swift`, `Usage.swift`, `Views/UsagePanel.swift` |
| Claude refusal recovery | App `RefusalRecovery.swift`, `Views/RefusalOffer.swift`, called from `Views/ComposerView.swift`. Offers a user-initiated switch to Codex Sol using the existing provider handoff. Remove the offer from the composer to leave switching to the model picker. |
| Patches (project buttons and panels), and trusting a folder's Claude Code hooks | `runner/src/patches.ts`, `patch-trust.ts`, `script-trust.ts`, `claude-trust.ts`, `panel-requests.ts`; app `Views/PanelsView.swift`, `ThreadPanels.swift`, `ActionChips.swift` |
| Design reviews (`show_options`) | `runner/src/reviews.ts`, `runner/src/review-media.ts` (videos and pages); app `ReviewSession.swift`, `Views/ReviewWindow.swift` |
| Design reviews (`show_options`) | `runner/src/reviews.ts`, `runner/src/review-media.ts` (videos and pages), `runner/src/phone-reviews.ts`, `ios/Threadbear/DesignReviewsView.swift`, phone review commands in `convex/phone.ts`; app `ReviewSession.swift`, `Views/ReviewWindow.swift` |
| Secrets (`ask_secret` and its card) | `runner/src/secrets.ts`, `runner/src/runner/approvals.ts` (`requestSecret`, `answerSecret`), the tool in `threadbear-mcp.ts`; app `Transcript/Cells.swift` (the card); phone `Threadbear/SecretCard.swift`, `ThreadbearKit/Secrets.swift`; `convex/phone.ts` (`secret`). Leave the tool out of `buildThreadbearTools` to switch it off. |
| Plan first (the plan card) | `runner/src/runner/approvals.ts` (`approvePlan`, `leavePlan`), `planProposed` in `runner.ts`, `ExitPlanMode` in `adapters/claude/adapter.ts`, the `plan` item and `collaborationMode` in `adapters/codex/`; app `PlanCardCell` in `Transcript/Cells.swift`, the plan card in `TranscriptReducer.swift`; on the phone, the `plan` message row (`toMessageDoc` in `runner/src/sync.ts`, API 72) and `ios/Threadbear/PlanViews.swift`, `Plans.swift` in ThreadbearKit and the plan case in `PendingCard.swift`. To hide it, take `.plan` out of the composer's permission menu (`ComposerControls.swift`) |
| Highlights and `pin` | `runner/src/highlights.ts`; app `Views/HighlightsView.swift`, `HighlightsBoard.swift` |
Expand Down
10 changes: 10 additions & 0 deletions docs/guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -244,6 +244,16 @@ message, so a go ahead in your reply doesn't set the same job off twice. It work
without Full access can't make a button that does more than it could
itself, and that's checked again when you press it.

On the iPhone, tap Reviews in the thread's top bar, or a review link in a
reply. The sheet shows the options, notes and still previews. Pick any
options, None of these, or write a reply, then Send answer. Reference
options are there to compare and cannot be picked. The runner must be
online to load the review and receive the answer. Pages and videos show
still previews; open their originals on the Mac. This needs the phone app
with Reviews and backend API 83 or newer. If the review changes on the Mac,
your answer stays in the sheet while it reloads, ready for you to check
and send again.

The comparison window starts on the first option's first picture. An option
can have several (its overview, how it looks mid-drag, a detail), shown in a
strip under the picture. Next and back (or the left and right arrow keys)
Expand Down
2 changes: 1 addition & 1 deletion docs/on-your-mac.md
Original file line number Diff line number Diff line change
Expand Up @@ -599,7 +599,7 @@ File references are where to look.
| Service | Whose | What goes there |
|---|---|---|
| A browser picture's URL | the site you drag from | When a picture dropped on the GPUI composer offers only an HTTP or HTTPS URL, the app downloads it directly without browser cookies, credentials or a proxy (30-second timeout, at most 25 MB). Only public internet addresses outside this Mac and its directly connected networks are used, including after DNS lookups and redirects. It is staged privately until the runner imports it. |
| Your Convex deployment | yours | Thread titles and status, all message text (each message cut at 8,000 characters), one line per tool call, the line a thread writes when its login runs out and it moves to another or waits (your other machines, your phone and your signed-in website are given those, never a shared page), projects, schedules, your logins' emails and usage, whether you're at the Mac, whether this machine is low on memory or disk, and the pictures you paste into a message, up to 10 MB each, so your own website can show them. Those go up as they are, in your deployment's file storage: unlike text, nothing can scrub a secret out of a picture, so a screenshot of something sensitive goes too. `"sync": { "pastedPictures": false }` in `runner.json` keeps them on this Mac. While someone has the website's Runners view open, this machine's CPU, memory and disk use, its processor model, operating system and time since it started, every 10 seconds; with nobody looking, none of that is sent. Photos you send from the phone, and pictures you send from the Mac app to a thread on another of your Macs, deleted once that Mac has fetched them. Pictures and videos agents put in their replies or pin, at most 10 MB each, for the phone to show. Other images only for threads you share by link. Other tool output and files stay on the Mac, unless you move a thread to another of your machines: then the whole thread, sealed so only that machine can open it, goes through for as long as the move takes. Text has known secrets taken out first: see below. |
| Your Convex deployment | yours | Thread titles and status, all message text (each message cut at 8,000 characters), one line per tool call, the line a thread writes when its login runs out and it moves to another or waits (your other machines, your phone and your signed-in website are given those, never a shared page), projects, schedules, your logins' emails and usage, whether you're at the Mac, whether this machine is low on memory or disk, and the pictures you paste into a message, up to 10 MB each, so your own website can show them. Those go up as they are, in your deployment's file storage: unlike text, nothing can scrub a secret out of a picture, so a screenshot of something sensitive goes too. `"sync": { "pastedPictures": false }` in `runner.json` keeps them on this Mac. While someone has the website's Runners view open, this machine's CPU, memory and disk use, its processor model, operating system and time since it started, every 10 seconds; with nobody looking, none of that is sent. Photos you send from the phone, and pictures you send from the Mac app to a thread on another of your Macs, deleted once that Mac has fetched them. Pictures and videos agents put in their replies or pin, and still previews of design review options, at most 10 MB each, for the phone to show. Opening a review on the phone also sends its current choices, notes and draft through the authenticated command queue. Other images only for threads you share by link. Other tool output and files stay on the Mac, unless you move a thread to another of your machines: then the whole thread, sealed so only that machine can open it, goes through for as long as the move takes. Text has known secrets taken out first: see below. |
| Convex (the Convex panel) | yours | Only for a thread in a Convex project, when its Convex panel opens: the runner's Convex CLI asks api.convex.dev for the project's deployments and a deploy key, the runner asks the deployment whether a kept key still works (`/api/check_admin_key`), and the panel loads Convex's embedded dashboard (dashboard-embedded.convex.dev) with that key. Sign in to Convex goes to auth.convex.dev. (`runner/src/convex-keys.ts`) |
| Your other Macs, over ssh | yours | Only when you run `tb runner add <name> --ssh <host>` or `tb runner check --ssh <host>` on your first Mac: it reads that Mac's Threadbear `runner.json`, writes its id and the deployment's address there if it hasn't them, writes its new key into that Mac's `secrets/convex-key`, and looks whether that Mac has a deploy key, Convex panel keys or a Convex login (names only, never a key), through your own ssh setup with agent and port forwarding off (`runner/src/runner-keys.ts`). `tb runner audit` asks this Mac's runner for its threads' last seqs and your deployment for what the main key made. `tb runner rotate-owner` sets env vars on your deployment with your deploy key, and, if you give it a Convex team access token for that run (`CONVEX_TEAM_TOKEN`, never kept), asks api.convex.dev for the deployment's deploy keys (their names and dates) before it rotates. |
| Your update build hosts, over ssh | yours | Only from the installed GPUI app, when `runner.json` has `updateBuildHosts` and main's `desktop/` has changed: a copy of your main's files to build it from, rsynced to `~/.cache/threadbear-check/gpui` on the first one that's a Mac and answers, and the two built binaries copied back (`desktop/scripts/stage-update.sh`) |
Expand Down
6 changes: 3 additions & 3 deletions docs/parity.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,9 @@ and web" is the iPhone app and the website, which read every thread through Conv
| A message's reply buttons | `buttons.list` | Yes | Yes |
| The slash command list | `threads.commands` | Yes | Yes |
| Hibernate until something happens | `threads.hibernateWhen` | Yes | No: The phone hibernates until a time only. |
| Design reviews | `reviews.list` | No: Reviews open in the Mac app from that Mac. | Yes |
| Reading a design review | `reviews.get` | No: Reviews open in the Mac app from that Mac. | Yes |
| Answering a design review | `reviews.respond` | No: Reviews open in the Mac app from that Mac. | Yes |
| What fills its context | `threads.contextUsage` | No: Asked of the CLI on that Mac; the ring's popover there shows the totals only. | No: Not on the phone. |
| Ticking an ask on the card | `threads.tickAsk` | No: Ticks stay on that Mac. | No: The phone sends picks with its answer instead. |
| Editing a message | `threads.edit` | No: It undoes file changes on that Mac, so it waits for a way to show what it undid. | No: Not on the phone. |
Expand All @@ -41,9 +44,6 @@ and web" is the iPhone app and the website, which read every thread through Conv
| An action chip | `actions.run` | No: Patches run on that Mac. | No: No action chips on the phone. |
| Trusting a folder's patches | `patches.trust` | No: Trust is given on that Mac. | No: Not on the phone. |
| Approving a plan | `plans.approve` | No: Not sent through Convex from the Mac yet. | No: Not on the phone yet. |
| Design reviews | `reviews.list` | No: Reviews open in the Mac app from that Mac. | No: Not on the phone. |
| Starting a design review | `reviews.create` | No: Reviews open in the Mac app from that Mac. | No: Not on the phone. |
| Reading a design review | `reviews.get` | No: Reviews open in the Mac app from that Mac. | No: Not on the phone. |
| Saving a design review | `reviews.save` | No: Reviews open in the Mac app from that Mac. | No: Not on the phone. |
| Answering a design review | `reviews.respond` | No: Reviews open in the Mac app from that Mac. | No: Not on the phone. |
| Cancelling a design review | `reviews.cancel` | No: Reviews open in the Mac app from that Mac. | No: Not on the phone. |
24 changes: 22 additions & 2 deletions docs/protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -946,6 +946,25 @@ patch panels are independent of these review windows. Reviews take
pictures, videos and pages, with a live `url` per option opened in the
browser; overlays are deferred.

#### Reviews on the phone

Backend API 83 adds `phone:designReviews(token, threadId, reviewId?)` and
`phone:respondReview(token, threadId, reviewId, revision, draft)`. Both queue
commands on the owning runner. Without an id the first returns pending
review titles; with an id it returns that review's options and current
revision. `phone:command` carries the result. The runner must be online to
read or answer a review. Responses use `reviews.respond`, including its
revision checks and idempotent retry behavior.

The phone's Reviews sheet opens from the pending-review button or a
`review:<id>` link. It shows reference and recommended options, each shot's
still preview, multiple picks, none, per-option notes and a reply. Preview
images use the existing private reply-image storage, with opaque review
sources instead of local paths. HTML and video originals stay on the Mac;
the phone labels their still previews. Loading and failed submissions keep
the user's draft. A stale revision reloads the review and requires another
deliberate send. Older backends keep the Mac-only explanation.

### Reply buttons

Standard since 11 Nov 2026 (it was the `replyButtons` experiment). Mike asked on 7 Nov 2026
Expand Down Expand Up @@ -3086,8 +3105,9 @@ the thread if a sub-agent stalls, so an ask can't stay hidden for good.
opens the turn's working in a sheet instead, and picks the step the same
way from what it has, a step's one line: a command with a description
comes as only the description, so a quote of the command finds nothing
and the sheet opens with no step lit. A `review:` link says it opens on
the Mac. The website has the same one-line steps on the page: a work:
and the sheet opens with no step lit. A `review:` link opens the phone's
Reviews sheet with backend API 83; older backends say it opens on the
Mac. The website has the same one-line steps on the page: a work:
link scrolls to its step, and is only its words if it finds none; so is
a `review:` link, and a `thread:` link on a shared page, as whoever it's
shared with can't open the others.
Expand Down
Loading