thursday-agent 0.5.0 → 0.7.0

package/docs/how-it-works.md

@@ -1,63 +1,68 @@
 # How it works
 
-The README says what Thursday is. This says what each part may touch, so you can guess what will happen before you say it.
+What each part does, so you can guess what will happen before you say it.
 
 ## The call
 
-A call is a session with a realtime speech model — OpenAI Realtime or xAI Grok Voice, whichever key you gave. Audio in, audio out, interruptions and all. The model hears a prompt assembled the moment the line opens: who she is, what she remembers about you, which bots exist, what was said on the last calls.
+A call runs on two models: **GPT-Live 1** holds the conversation, and a Responses model (**GPT-5.6 Luna** by default) thinks and uses tools behind it. The voice keeps listening while the backend works.
 
-She holds three things and nothing else:
+![One mind goes silent while it works; two minds keep the call going while a bot does the work](images/two-minds.png)
 
-- **Memory.** A folder of notes about you. She reads a note before answering out of it and writes the moment something worth keeping comes up — one fact per line, dates as dates. A rule you lay down ("answer in Korean", "keep it short") is carried into every call.
-- **One command.** A shell, for the things that take a second: open a file, play something, look at what is in a folder. One command is something she does, not a job she hands over.
-- **The roster.** The bots, by name, and what each is for.
+- **Quick things, she answers herself.** She reads and writes your memory and runs one shell command at a time: open a file, check a folder, play something.
+- **Everything else goes to a bot.** She hands it over and keeps talking. A speech model that ran a browser itself would go silent for minutes.
+- **When a job comes back,** she tells you in a sentence. A file it made opens on your screen, and a question it asks shows up as buttons.
 
-Everything else — anything that takes more than a few seconds — she hands to a bot with `delegate` and keeps talking. That is deliberate: the call must never go silent, and a speech model that runs a browser would be silent for minutes.
+Settings › Thursday picks the voice, the backend model and its reasoning, web search, the wake word and hotkey, and whether she calls you when a job ends.
 
-When a job comes back, it arrives as a system note, not as you speaking. She tells you in one sentence, in her own words. A file the job made opens on your screen by itself; a question the job asks becomes buttons on screen and words in your ear.
+The voice is billed per active minute, silence included; the backend is billed per token. Both use your OpenAI API key, not a ChatGPT subscription.
 
 ## Bots
 
-A bot is a text model — any of OpenAI, Anthropic, Google, xAI, or whatever the Vercel AI Gateway carries — with the whole machine:
+![A bot gets a shell, a real browser, skills, MCP servers, a studio and its own memory](images/machine.png)
 
-- a **shell** in a workspace folder, with no pager and no secrets in its environment
-- a **real browser** (Chromium through Playwright), headless until a sign-in or something you should see, and able to attach to the Chrome you already use
-- the **filesystem**, read anywhere, written only inside the workspace and where you pointed it
-- **skills** — written-down methods it reads before starting: the browser, this Mac, building a page, finding and writing skills
-- **MCP servers** you connected, searched by name and called by schema, with OAuth handled
-- a **studio** of image, video, speech and transcription models
-- **each other**: a bot hands a part of its job to the bot that exists for it, and folds the answer into its own report
+A bot is a text model from any provider you added, with:
 
-A job ends in the thing that was asked for — the account made, the page built, the comparison in a table — and a report, written to be heard, because she reads it out loud. Anything that does not fit in a few lines is a file under `artifacts/`, and the report names it.
+- a **shell** in a workspace folder
+- a **real browser** — its own, or the Chrome you already use
+- **your files** — it reads anywhere and writes where your user can; only its file tool is kept out of the app and the workspace root ([SECURITY.md](../SECURITY.md))
+- **skills**, methods it reads before it starts
+- **MCP servers** you connected
+- a **studio** for images, video, speech, and transcription
+- **each other**, to hand off part of a job
 
-What only you can give — a sign-in it holds no session for, a decision between two real options — stops the job at that point. The bot sets it up one action away, asks, and continues when the answer comes. Credentials you handed it are used only after it asks. A payment is the one thing it never finishes: it takes the purchase to the last screen, leaves that window open on yours, and reports what it buys and for how much.
+The first run lets you pick a few starter bots; more are ready in Settings › Bots, or make your own with a name and one sentence about what it is for. That sentence is how Thursday decides who gets a job. Switch a bot off without deleting it.
 
-Three bots come with the app, split by temperament: **Jarvis** plans a job, hands parts to whoever fits and does the rest; **Navigator** goes and looks; **Scribe** writes. More are ready-made in settings — **Insta** draws, captions and posts to Instagram, **Voyage** plans a trip with a map for each day — or make your own: a name, a sentence about what it is for, optionally a model and a few pinned tools. The sentence is what she reads when deciding who gets the job. A bot can be switched off without being deleted.
+A job ends in the thing you asked for and a short report. Anything longer than a few lines is a file in `artifacts/`. When only you can do something — sign in, choose between two real options — the bot sets it up, asks, and waits. It never presses Pay: a purchase stops on the last screen, left open for you.
 
-Each bot keeps its own memory as files in its folder (`bots/<name>/memory/`), one topic per file, and reads the list at the start of every job. Its page in settings shows them; open one in place or delete it.
+Each bot keeps its own memory as files you can open from its page.
 
 ## Jobs outlive the call
 
-A job runs on the server. It is not in the tab, and it does not stop when you hang up. Every step — the request, each tool call, what came back, the report — is written as a row, and the screen is a projection of those rows. When you come back, the jobs that finished are waiting, and she tells you about them on the next call, or rings you if you turned that on.
+![Hang up mid-sentence and the job keeps going on the server](images/keeps-going.png)
 
-A job that stopped to ask, or ran out of its step budget, is resumed from where it stopped: the same thread, with your answer appended. A long thread is compacted — the model summarizes what happened so far and continues from the summary.
+- A job runs on the local server, not in the call. Hang up and it keeps going.
+- Every step is saved, so a job that stopped to ask picks up where it left off, and you can read the whole thread.
+- Close the app, and after ten seconds running jobs pause. Open it again and they continue, so nothing spends your keys while you are away.
+- A model call that fails is retried once. After that, the job waits for you.
 
-With no browser on the app for ten seconds, running jobs stop where they stand, so nothing spends your keys while nobody is looking. A job the app stopped — a closed tab, a restart, a model call that failed — picks itself back up when it can, up to three times in a row before it waits for you. A job a bot or a person stopped waits for a person.
+## Memory
 
-## Memory you can read
+Memory is a set of notes about you, one fact per line: your name, your language, the people you mention, the rules you give her. A few notes go into every call.
 
-Memory is notes in the database on your disk, in the data folder (`~/.thursday` when installed with `npx`, the checkout otherwise). Each note is a topic — `profile`, `preferences`, `people/…`, and whatever she creates — and holds one fact per line. A few are `alwaysLoad` and travel into every call: your name, your language, how you like to be addressed, the rules you gave her.
+Open any note in Settings › Memory to see exactly what she knows. To change it, type what changed and watch each edit land. Bots read your memory but never write it.
 
-She writes the moment something worth keeping comes up. Each fact remembers the call it was said in, so when a line is not enough she can open that conversation again. Nothing re-reads calls after they end: what is kept is what was written.
+## Where your data lives
 
-You can open any note from settings and read exactly what she knows. To change it, type what changed on the Memory screen, pick a model, and watch each edit land. When the listing gets long she says so in a lull, puts a note on your screen and forgets only what you name.
+```text
+~/.thursday
+├── local.db          calls, memory, bots, jobs, keys
+└── .ai-workspace
+    ├── artifacts/    finished work, a folder per bot
+    ├── projects/     code and longer-lived projects
+    ├── bots/         each bot's memory and saved sessions
+    └── .agents/      skills you installed
+```
 
-Bots read your memory but do not write it. What a bot learns about its own work goes into its own memory files; what it learns about you goes into its report, and whether that is worth keeping is her call, with you.
+When you run from source, the same files live in the checkout. The server listens only on `127.0.0.1`, and there is no login — see [SECURITY.md](../SECURITY.md).
 
-## What is not here
-
-- **No cloud.** The server is the one on your machine; keys are stored locally and sent only to the provider you chose.
-- **No account.** There is nothing to sign up for. There is also no login, which is why the server binds to `127.0.0.1` — see [SECURITY.md](../SECURITY.md).
-- **No prompt engineering on your side.** The prompts are assembled from your data on every session; the one thing you can add is an instruction to her, and one to each bot, in settings.
-
-For the code — which file owns what, and why — read [CLAUDE.md](../CLAUDE.md).
+For contributors: [live calls](live-calls.md) and [thread rooms](thread-rooms.md) are the engine contracts, and [AGENTS.md](../AGENTS.md) maps the code.

package/docs/live-calls.md

@@ -0,0 +1,236 @@
+# Live calls
+
+Thursday uses GPT-Live 1 for voice and Responses delegation for short reasoning and
+tool use. The default backend is GPT-5.6 Luna. Background bots keep their own
+models, prompts, durable threads, and execution budgets; the voice settings do not
+change the text or media providers available to them.
+
+This document is the implementation contract for calls. Keep it aligned with the
+code when changing session events, settings, prompts, or persistence.
+
+## Responsibilities
+
+| Runtime | Context and instructions | Work |
+| --- | --- | --- |
+| Live voice | `live.prompt`: who Thursday is; under `## Always` the ending rule, backchannel, interruption and a short delegation policy; profile and preferences with the note listing | Listen, speak, backchannel, handle interruptions, hand everything but conversation to the backend |
+| Responses backend | `thursday.prompt`: who Thursday is, memory with ids, bot roster, threads and what bots can reach, this computer, what to return, earlier calls with their jobs; tool schemas | Recall, update and tidy memory, run short commands, ask before handing work over, route thread messages and cancellations, delegate long work |
+| Background bots | `bot.prompt` and the stored participant transcript | Shell, browser, MCP, skills, and work that outlives a call |
+| Application | Authoritative database and tool implementations | Validate actions, retain results, enforce thread limits, render progress, save call history |
+
+Use Responses delegation because Live supplies conversation context and manages the
+backend connection. Do not build a second transcript-to-thread orchestrator. Client
+delegation is a different integration: its notification contains metadata, not thread
+text, so the application would have to reconstruct the request and operate the backend.
+
+The voice and the backend are one assistant. Both prompts open with the same identity
+(`thursdayIdentity`) and the same rule for ending the call (`callEnding`), read the same
+memory, and neither is told it is part of something else. The voice holds conversation and
+memory only. Right under the identity, `## Always` groups what holds on every turn: the ending
+rule (the only line marked `IMPORTANT`), the guide's starter backchannel and interruption
+policies, and under the guide's `Delegation policy` label three lines — hand everything but
+greetings, small talk and a brief clarification to the backend; hand over whatever the user says
+about themselves, their people, their plans or how they want things done as they say it, unless
+it is already written in the prompt; answer from what the backend returns without guessing while
+waiting. Live decides by itself whether to delegate, so the rule stays even this short. It says
+nothing else about how to speak; it sees no tool schema and no tool name but `end_call`, in the
+ending rule. The backend prompt holds the work: memory (merging a fact that repeats or changes one
+already kept, and tidying with the user past the limits), background work and threads, this
+computer, what to return, and the earlier calls. Before handing work to a bot it returns one question — which bot, a new thread or
+one already open — unless the user already said or left it to Thursday.
+
+## Settings and upgrades
+
+Voice uses the fixed `gpt-live-1` model. Settings › Thursday exposes a voice and
+additional voice instructions; for the backend, a model,
+optional reasoning effort, web search, and additional backend instructions. Both
+instruction fields add to the app's prompts and never replace them. The model list
+shows recent models; an older or custom ID can be typed and saved. Live accepts any
+reasoning settings when the call opens and fails the backend's first response when the
+model does not take one, so the server asks the token-count endpoint first
+(`acceptedReasoning`), once per model and effort. A setting refused by name, the effort or
+the summary, is dropped and not shown; a refused model or key still reaches the user when the
+call opens. Auto reasoning sends no effort.
+Web search adds the `web_search` tool only when switched on. Changes apply from the
+next call.
+
+Settings stay in the browser under the existing `thursday.settings` key, beside wake
+word, shortcut, captions and call-back (`thursday.store`). `migrateLiveSettings`
+upgrades stored values: an OpenAI voice and backend model carry over, a Grok voice is
+retired without touching historical calls or xAI text and media keys, and the old
+shared instruction is copied into both new instruction fields. Each field recovers on
+its own, so one malformed value falls back to its default and leaves the rest.
+
+Every call is kept on this machine. Live transcription needs no separate model or
+request, so there is nothing to switch off to save cost. Keep `store: false` in the
+provider request: local history is distinct from OpenAI session recording and fork
+storage.
+
+## Connection and opening
+
+1. In the user's gesture, before anything awaits, prepare playback. Then request
+   microphone access and gather WebRTC ICE.
+2. Send the SDP offer and the parsed settings to `openCallAction`. The browser sends
+   settings only; the server reads the key.
+3. On the server, assemble both prompts and the current tool manifest. Create the
+   Live session with the fixed voice model, the chosen voice, voice instructions and
+   `delegation.responses` backend settings. No `input`: earlier calls are the backend's to read.
+   Insert the call row only after the provider accepts, so a refusal leaves no open row.
+4. Apply the SDP answer and wait for `session.started`. Do not send Realtime startup
+   configuration, audio commits, or a voice `response.create`.
+5. Send the opening as `session.instructions.append`, so she speaks first: a first call
+   (no profile facts) greets the user and asks what to call them, and any other call opens
+   with a short greeting.
+   Updates that arrived while connecting follow once she has voiced the opening.
+   For work that changed after the last call ended (a call tells what came up during it),
+   the page rings instead of opening a line (call-back): the user answers it like any
+   call, declines it, or lets it ring out after `CALL_BACK.ringMs`. An answered ring opens
+   with the fact that
+   she placed it, ahead of every other opening, and the first open work goes in as soon
+   as she has voiced that, without waiting for a quiet line: why she called is the first
+   thing asked. The opening names no bot text; the work itself follows as commentary.
+
+A hang-up during startup invalidates that attempt, so a connection that finishes
+later is closed rather than taking over the screen. Do not change machine trust,
+certificate, or proxy configuration to hide connection errors.
+
+## Tools and background updates
+
+Live speech and backend work have independent lifecycles. Unwrap `response.event`
+and associate its delegation with the response ID from `response.created`. Collect
+complete function calls from `response.output_item.done`, deduplicate by call ID, and
+run existing server handlers through the tool-call route. Terminal response snapshots
+intentionally omit output items. Submit every function output with
+`response.item.create`, then explicitly continue with one `response.create`. That
+command continues backend work; it does not grant permission for Live to speak. A
+response that ends incomplete after asking for tools is still continued once its outputs
+are in, or the backend turn never finishes; a failed or cancelled response, or a second
+incomplete in a row, only warns. A function call the output cap cuts off arrives as an
+item with status `incomplete` and fragment arguments, and Live ends that handoff with a
+top-level `error` instead of a terminal event: the call is not run and its response
+counts as finished, though calls it completed before the cut still have their results
+continued once. The backend is asked for `reasoning.summary: "auto"` unless the
+effort is `none`. Each finished summary part (nested `response.reasoning_summary_text.done`,
+only while the model reasons) is stored with its call in `call_thought` to look into
+later; while the backend has the turn, the activity line shows the bold title of the latest
+one, and nothing reads it back into a prompt. Tools are sent without `strict`, so each schema that allows it is
+decoded to the schema; `strict: false` would let a model write arguments that are not
+JSON, and `strict: true` is refused while any schema has optional fields. Live has no
+`response.cancel`.
+
+Long work enters the existing bot runner and returns a thread receipt immediately.
+Background questions and results follow the existing durable relay queue. A voice
+interruption never cancels a thread by itself. Route an explicit cancellation or
+correction to the owning thread and report its actual outcome.
+
+| Update | Live event |
+| --- | --- |
+| Opening, idle goodbye, other trusted behavior | `session.instructions.append` |
+| Screen actions the voice should know but need not say | `session.thinking.append` |
+| A bot's result or question to convey | `session.commentary.append` |
+
+Bot output is never sent as instructions. Each append carries a required
+`delegation_id`, `null` for application updates in Responses mode; a response ID is
+not a client delegation ID. Appends are serialized and matched to their
+acknowledgement by `client_event_id`. An update longer than one append is split at
+word boundaries under 480 UTF-8 bytes, which keeps within the 500-token limit for any
+script, and sent chunk by chunk. A rejected or unacknowledged chunk drops the rest of
+its update, warns, and is never replayed. An acknowledgement is not proof of speech.
+
+Live never speaks unprompted, so what waits on the user reaches them only when the page puts
+it in. The relay clock (`useThursday` `relayOpenWork`) reads the inbox once a second and sends
+open work only when neither side's words have been transcribed for `CALL_RELAY.quietMs` and
+no backend work or tool is running: questions not answered, jobs stopped or finished and not
+yet seen, and progress from jobs still running. Up to `CALL_RELAY.perTurn` items of one
+kind go in one commentary append, most pressing first, so an ending never shares an append with
+a question. The activity line carries the update from the moment
+it goes out until her voice has finished it, and nothing else goes in until her voice has started
+and stopped (at most `CALL_RELAY.readMs`). An item is handled when it is answered, marked seen
+by the backend's `thread` `seen` once the user has been told enough, or opened on screen — the
+backend's `thread` `open` opens it in the call screen's room (a `showThread` event). Each item
+goes in once a call (`told`, in memory), and it stays in the inbox and on screen until handled.
+One her voice carried stays out of later calls too while the page is open; one it did not (Live
+refused it, she never spoke, the call ended first) goes in again on the next call, never in a
+loop on this one. The key carries the job's last change, so a job that resumes and asks or ends
+again is a new item, and a reload puts what is still open in once more. Nothing goes in while
+the call is ending or a goodbye has been asked for. A relay is facts only, with no note
+ahead of it.
+
+A relay names the bot and the thread and, for a question, where its answer goes (thread,
+recipient, `replyTo`). The backend reads relays in its conversation and routes the user's
+answer from those facts, so a relay carries no instructions. Relay rows are accepted
+(`acceptThreadRelaysAction`) once Live acknowledges the append; an ending also covers its
+job's progress rows. Being put to her does not mark a result seen.
+
+## Transcript and screen
+
+Input and output transcript events contain `delta`, `start_ms`, and `end_ms`. They
+have no authoritative completed-turn event. The session folds fragments into
+revisable display groups by speaker and time, deduplicates them by event ID, and
+checkpoints changed groups every `LIVE_CALL.transcriptSaveMs` with their exact
+fragments. A late fragment revises its group, which is saved again. Never derive
+actions or cancellations from the grouping. Backend text is not a transcript of spoken
+audio and never becomes a caption.
+
+`call_message.fragments` keeps the original fragments beside each saved group; a
+revision replaces them and keeps the group's `seq`. Rows written before Live have no
+fragments and remain readable.
+
+Track playback and backend work independently, from her audio level and backend events.
+The idle clock rewinds on new transcribed words, her voice and backend work, not on
+microphone level alone, so a noisy room does not hold a call open, and not on an update she
+voices on her own, so waiting results do not either. A sound the transcript writes in
+brackets (`[sigh]`) is not words. After `CALL_IDLE.hangUpMs` the page hangs up without asking
+for a goodbye, which would leave the ending to the model.
+
+## Closing and recovery
+
+The user wanting the call to end, however they say it, sets everything else aside: the
+voice answers yes and hands it to the backend at once, and the backend runs `end_call`
+without deliberating. The ending rule names `end_call` in the voice prompt too, the one tool
+name it holds: without it, ending read as something to say rather than do.
+The page does not close on `end_call` itself: it waits until her voice has been quiet
+for `CALL_END.quietMs`, or `CALL_END.unsaidMs` when nothing was said, never past
+`CALL_END.maxMs`. `end_call` and `emote` (a word of up to eight characters on her face,
+offered only while the face is the ascii orb) are answered by the page, not the tool-call
+route. A call the user did not end — quiet, `end_call`, Live closing the session, a dropped
+connection — leaves the reason in the idle hint until the next call.
+
+Stop accepting new work, send `session.close`, and keep the connection while waiting
+for `session.closed`. Its reason and billed seconds are recorded on the call row
+(`ended_reason`, `seconds`) next to the backend model. Without a confirmation within
+`LIVE_CALL.closeMs`, the call warns and the seconds stay unknown. The screen shows
+Ending until cleanup finishes and blocks a second call during that interval.
+Background jobs follow existing presence rules and survive the call.
+
+A new connection is a new session. Seed it with relevant saved history and current
+thread state. Reconcile completed operations and suppress stale results; never replay
+tools merely because the previous connection disappeared. Live charges active session
+time, including silence and backend waits; backend tokens are separate.
+
+## Validation
+
+`pnpm test:live` covers tool continuation, including the one continuation after an
+incomplete response, fragment grouping and late revision, closing with and without
+confirmation, activity while speaking and working, append ordering, acknowledgement,
+rejection and chunking, the provider request with optional reasoning and web search,
+settings migration, both assembled call prompts and the identity they share, and fragment
+persistence against a migrated database. Also run typecheck, lint, build and
+`pnpm test:bot`, and read both assembled prompts.
+
+Inspect settings on desktop and narrow screens. Real-call checks cover a first
+greeting, overlapping speech, a short tool call, a bot
+question answered during other work, correction, cancellation, a late result,
+reconnect, and the recorded seconds. Count durable tool calls and thread
+messages as well as listening to the actual audio.
+
+## Official references
+
+- [Getting started](https://developers.openai.com/api/docs/guides/live)
+- [Voice prompting](https://developers.openai.com/api/docs/guides/live-prompting)
+- [Sessions, transcripts, and closure](https://developers.openai.com/api/docs/guides/live-conversations)
+- [Responses delegation and updates](https://developers.openai.com/api/docs/guides/live-delegation)
+- [Migration](https://developers.openai.com/api/docs/guides/live-migration)
+- [Partner integrations](https://developers.openai.com/api/docs/guides/live-partner-integrations)
+
+Thursday uses direct browser WebRTC. LiveKit, Pipecat, and telephone integrations
+are not required for this media path.

package/docs/thread-rooms.md

@@ -0,0 +1,71 @@
+# Thread rooms
+
+A thread has one coordinator and a persistent participant for each canonical bot name. Thursday introduces the work to the coordinator. Bots exchange messages and run independently; the coordinator brings the results back to Thursday. A model invocation is one period of activity, not a new bot.
+
+## Identity and context
+
+A participant is identified by `(threadId, bot)`. Every continuation for that participant reads the same stored history, beginning with its original briefing and, after compaction, its latest summary. Requests from a different colleague do not create another context or browser identity. Browser session names derive from the thread and canonical bot name.
+
+`parentId` identifies the conversation to which a continuation returns. It does not identify the participant. If A waits for B and B asks A a question, A handles that question in its own context, returns the answer to B, and keeps its original responsibility to report to Thursday. Only exchanged messages enter the other participant's context. The human can inspect all recorded activity; workspace files remain shared resources.
+
+## Messages and turns
+
+Bots use `send_message(to, text, kind?, options?, replyTo?)`. A send commits before returning a receipt. The sender can continue independent work or end its turn. A natural final message returns to the current correspondent; a silent ending is valid. There is no completion tool or required closing phrase.
+
+An explicit `replyTo` routes a message to an open incoming exchange. An ordinary send to another bot opens a new exchange. For Thursday, `kind: "message"` (the default) sends an update without opening a question or delaying completion. Use `kind: "question"` for user input; it carries an addressable question ID and optional answer choices. Other participants continue while a question is open, but the question ends the asker's turn: until it is answered, that bot runs nothing, messages to it wait in its inbox, and words from the user side addressed to it answer the question. With several questions open and none named, an answer is refused with the list. The screen and the call's `thread` tool can direct an answer or a new message to a particular participant. An answer is words like any other: a question that offers `Continue` among its choices is answered by it, and only a stop the app made is resumed by that word.
+
+The room and its participants have separate lifecycles:
+
+| Continuation state | Meaning |
+| --- | --- |
+| `queued` | Ready for the scheduler. |
+| `running` | Claimed by one live turn. |
+| `waiting` | The turn ended with downstream work still open. |
+| `external` | A message to Thursday awaits a user response. |
+| `paused` | Interrupted work awaits a permitted resume. |
+| `done` | The continuation has no unread messages or open downstream work. |
+| `cancelled` | The user stopped the continuation. |
+
+Incoming messages queue a waiting continuation. At completion, the engine checks the inbox and downstream work in the same transaction that releases the claim. A message racing with an ending is handled by the current turn or its successor.
+
+The coordinator's normal final message completes the thread only when all work has settled. If activity settles without a coordinator report, the scheduler permits one wrap-up turn. An empty final turn leaves an idle, resumable room; it does not cause an automatic retry loop. A participant that already replied with `replyTo` and then ends silently sends nothing more; its reply is the answer.
+
+## Durable state
+
+`room.query.ts` owns transactional scheduling and messaging. `bot.runner.ts` holds live promises and abort controllers. `bot.run.ts` runs one `ToolLoopAgent` and persists events through the runner.
+
+| Table | Responsibility |
+| --- | --- |
+| `thread` | Room status, coordinator, reporting epoch, automatic turn budget. |
+| `thread_work` | Continuations, return routes, claims and claim generations. |
+| `thread_delivery` | Durable inbox and insertion acknowledgement. |
+| `thread_message` | Model history and the human-visible activity projection. |
+| `thread_relay` | Reports and questions awaiting delivery to Thursday. |
+
+A partial unique index allows only one running continuation for a bot in a thread. Model execution never holds the room's command lock. Cancellation and manual resume share that lock; cancellation drains the old runs before a new run can start. Generation checks reject a stale run's attempts to send messages or settle work. Actual tool results received during shutdown are retained before the drain ends.
+
+Message receipts use a stable key derived from the thread, sender and tool call ID. A repeated send returns the committed receipt. Recovery also reconstructs a known receipt when the send committed but its tool-result row did not. Inbox insertion and acknowledgement are transactional. Transcript sequence numbers are allocated at the database boundary, so different bots cannot overwrite each other's rows.
+
+The SDK can prepare another model step before a streaming consumer finishes writing the previous step. A persistence barrier prevents that next step from starting early. Compaction is written before newly consumed inbox messages, preserving the same ordering on resume.
+
+`BOT_RUN` in `config.ts` bounds concurrent participants, distinct participants, pending exchanges, steps per turn and automatic turns across the room. User messages and manual resumes reset the room's turn budget. Browser presence returning does not reset it.
+
+## Interruption and recovery
+
+Closing the last app browser pauses work; returning resumes only work paused for browser absence. A model call that breaks — a dropped or garbled stream, an overload, a model gone quiet, a context refused as too long — is tried once more from the stored conversation after a short wait, with a note saying why. A second break, a provider's refusal (the key, the credit, the model id), the content filter, a server restart, a resource limit such as the step limit, or a user stop waits for a person. The stored conversation and browser identity remain available. Browser processes, login state and element references may require inspection after a restart.
+
+Before a local tool executes, its validated call is stored. Before another model step starts, its result is stored. On resume, a local call with no result receives an interruption result in the model projection: the outcome is unknown and the current state must be inspected before repeating the action. The original audit rows remain intact. Real results are preserved, malformed argument fragments do not become executable calls, and native provider operations without results become explicit interruption notes instead of fabricated local results.
+
+This does not provide exactly-once execution against arbitrary external services. A server can disappear after a remote action succeeds and before its result is stored. The engine preserves that uncertainty and offers manual recovery rather than replaying external actions automatically.
+
+A thread is created together with its coordinator's first continuation, so every thread is a room from its first row.
+
+Thursday relays are persisted independently of whether a thread has been opened on screen. Unaccepted reports remain in the inbox beyond the usual finished-thread limit. Opening a thread, or Thursday marking it seen, settles its relays; so does a resume for the stop it picks up from, and new words for how it last stopped or ended. A call accepts a relay once Live acknowledges the update; this is not proof that the user heard the audio, and an update Live never acknowledged is relayed again on a later call. A question or ending she voiced is not presented again on a later call while the page stays open; it stays on screen until handled.
+
+The screen keeps unanswered questions visible even while other participants work, and keeps unread endings until the user opens them. A thread reads as the conversation between its participants: every message as words, the open tab's bot's own work in full, and each other bot's work between its messages folded into a row that opens in place. It opens on its own bot's tab, which holds every participant; another bot's tab holds only what reached that bot's context. The collapsed thread panel shows both without relying on a call. Thursday's status tool returns up to ten threads, prioritizing open work and filling the remaining places with recent endings; naming a thread returns its full result and pending questions.
+
+## Verification
+
+`pnpm test:bot` runs the real scheduler, SQLite queries, tools, prompts and SDK loop against isolated temporary data and deterministic model streams. It checks continuity, private histories, routing, concurrent questions, completion races, interruption, cancellation, compaction and committed-message recovery. Provider adapter tests inspect serialized OpenAI, Anthropic and Google requests at a mocked HTTP boundary. They do not call live models.
+
+Run `pnpm typecheck`, `pnpm lint` and `pnpm build` as well. Browser checks cover the thread screen, participant selection, separate drafts, Markdown and long URLs. TypeScript alone does not validate Next.js client/server directives or the rendered layout.

package/features/ai/chatgpt.ts

@@ -521,8 +521,7 @@ async function codexFetch(
 /**
  * A 429 is either a rate limit a moment fixes or the plan's usage spent until its window resets
  * — hours, or on Free a month. The second becomes a 402 in the backend's words: the sdk does not
- * retry it, and a job fails with it (model.ts modelFailureOf) instead of waking every few
- * minutes to be refused again.
+ * retry it, so a job fails with it at once instead of being refused again and again.
  */
 async function usageLimitOf(response: Response): Promise<Response> {
   const text = await response.text();

package/features/ai/live.schema.ts

@@ -0,0 +1,128 @@
+import { z } from "zod";
+import { COMMON_VALIDATE } from "@/lib/limits";
+import { LIVE_BACKEND_MODEL } from "@/lib/live/live.schema";
+import { TEXT_MODEL_PROVIDERS } from "./model.schema";
+
+export const LIVE_PROVIDER = {
+  id: "openai",
+  label: "OpenAI",
+  apiKeyName: TEXT_MODEL_PROVIDERS.openai.apiKeyName,
+} as const;
+
+/** Suggestions only: custom voices and older backend model IDs remain valid input. */
+export const LIVE_VOICES = [
+  "marin",
+  "cedar",
+  "gleam",
+  "meridian",
+  "quartz",
+  "ripple",
+  "vesper",
+  "willow",
+  "stone",
+  "bossa",
+  "tempo",
+  "beacon",
+  "delta",
+  "cinder",
+  "alloy",
+  "ash",
+  "ballad",
+  "coral",
+  "echo",
+  "sage",
+  "shimmer",
+  "verse",
+] as const;
+
+/**
+ * Regional influence and presentation, as OpenAI documents them for the voices
+ * GPT-Live adds. The rest — marin, cedar and the voices shared with Realtime —
+ * have no documented character, and an invented one would read as fact.
+ */
+export const LIVE_VOICE_NOTE: Partial<
+  Record<(typeof LIVE_VOICES)[number], string>
+> = {
+  gleam: "North American · feminine",
+  meridian: "North American · masculine",
+  quartz: "Australian · feminine",
+  ripple: "Australian · masculine",
+  vesper: "British · masculine",
+  willow: "Irish · feminine",
+  stone: "Irish · masculine",
+  bossa: "Portuguese · feminine",
+  tempo: "Portuguese · masculine",
+  beacon: "Filipino · masculine",
+  delta: "Southern U.S. · feminine",
+  cinder: "Southern U.S. · masculine",
+};
+
+/** A recorded line in this voice. Only the listed voices have one. */
+export const voiceSamplePath = (voice: string) => `/voices/${voice}.ogg`;
+
+export const LIVE_BACKEND_MODELS = TEXT_MODEL_PROVIDERS.openai.suggestModels;
+export const LIVE_REASONING = [
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+] as const;
+
+const instruction = z.string().max(COMMON_VALIDATE.prompt.max).default("");
+
+export const LiveSettingsSchema = z.object({
+  voice: z.string().trim().min(1).max(128).default("marin"),
+  voicePrompt: instruction,
+  backendModel: z.string().trim().min(1).max(128).default(LIVE_BACKEND_MODEL),
+  backendPrompt: instruction,
+  /**
+   * A call waits out loud, so the backend reasons as little as the work allows.
+   * Null omits the parameter, for a model that only runs on its own default.
+   */
+  reasoningEffort: z.enum(LIVE_REASONING).nullable().default("low"),
+  webSearch: z.boolean().default(false),
+});
+export type LiveSettings = z.infer<typeof LiveSettingsSchema>;
+export const LIVE_DEFAULTS = LiveSettingsSchema.parse({});
+
+/**
+ * Settings stored before Live-only, or hand-edited, into valid ones. An OpenAI
+ * voice and backend model carry over; a Grok voice does not, since its names
+ * mean nothing to Live. The one shared instruction goes into both new fields so
+ * nothing the user wrote is lost. Each field recovers on its own: one bad value
+ * falls back to its default and leaves the rest as they were.
+ */
+export function migrateLiveSettings(value: unknown): Record<string, unknown> {
+  const stored =
+    value && typeof value === "object"
+      ? (value as Record<string, unknown>)
+      : {};
+  const { model, systemPrompt, ...rest } = stored;
+  const legacy = z
+    .object({
+      provider: z.string(),
+      voice: z.string().nullish(),
+      backendModel: z.string().nullish(),
+    })
+    .safeParse(model);
+  const openai =
+    legacy.success && legacy.data.provider === "openai" ? legacy.data : null;
+
+  const candidate: Record<keyof LiveSettings, unknown> = {
+    voice: stored.voice ?? openai?.voice,
+    voicePrompt: stored.voicePrompt ?? systemPrompt,
+    backendModel: stored.backendModel ?? openai?.backendModel,
+    backendPrompt: stored.backendPrompt ?? systemPrompt,
+    reasoningEffort: stored.reasoningEffort,
+    webSearch: stored.webSearch,
+  };
+  const live = Object.fromEntries(
+    (Object.keys(candidate) as (keyof LiveSettings)[]).map((key) => {
+      const parsed = LiveSettingsSchema.shape[key].safeParse(candidate[key]);
+      return [key, parsed.success ? parsed.data : LIVE_DEFAULTS[key]];
+    }),
+  );
+  return { ...rest, ...live };
+}