shockwave / agent-core

# CLAUDE.md — shared agent runtime (`agent-core/`)

`agent-core/` is the **coding-agent runtime**, wrapping pi (`@earendil-works/pi-coding-agent` + `@earendil-works/pi-ai`). It holds **all** the turn logic — session boot/resume, running + steering a turn, the pi→row mapping, upload-then-clear ordering, resume-from-JSONL, auto-title, model resolution, system-prompt assembly, tools, skills, the model catalog.

It is esbuild-bundled into **both** hosts, so one change lands in both:
- **Desktop** — host in `src/main/codingAgent.ts`; one live session per chat, events → renderer via IPC, persistence → the companion over HTTP (`src/main/api/chats.ts`).
- **Companion** — host in `api/src/agentHost.ts` (`makeCompanionRuntime`); persistence → Postgres directly (`store.ts`), events → the SSE feed. Runs Telegram + cron turns.

Read the root `CLAUDE.md` first. Deep docs for each host: `src/main/CLAUDE.md`, `api/CLAUDE.md`.

## The host/runtime split

**`AgentHost`** (interface, `agent.ts`) is all host-specific I/O, **no logic**. Each host implements it and calls **`createAgentRuntime(host)`**, which returns `{ agentSend, agentPrepare, agentAbort, agentDisposeChat, agentDisposeAll, agentRunningChats }`. The public names say **chat**, never session — a pi session is the private thing inside, and the root `CLAUDE.md`'s terminology rule is enforced at this boundary rather than only in prose.

**`agentPrepare(opts, emit)`** boots the session without running a turn, so a host can do it while waiting on something else — the companion's Telegram path boots alongside transcribing a voice note, since booting needs none of the text. Safe to call and then `agentSend`: `booting` dedups an in-flight boot and `ensureSession` returns the cached entry. It **refuses for a chat with a turn in flight**, because the running entry would have its `emit` re-pointed at the new caller's sink — the bug that froze a reply half-written. Callers check that too; this checks it so a caller that forgets can't cause it. What the host supplies:

- `builtinDir` — path to the bundled built-in skills.
- `machine` — `os.hostname()`, stamped on chats for provenance.
- `extraTools` — the pi tools this host implements: desktop `[open_file, send_message]`, companion `[send_message]`. Every one must also be named in `TOOL_CATALOG` or it is silently dropped (see "Tools" below). **May be a FUNCTION** of `{ chatId, workspacePath, source }`, resolved at session boot where those are in scope — which is how `send_message` learns the workspace whose reply mode it reads and writes. A plain array cannot: the host is built once per process, the workspace is per turn.
- `scratchDir(chatId)` — the AGENT's own directory for the chat: working files, downloads, anything it's producing to send rather than keep, and (companion) the files the user sent it. **Named in the prompt**, so it has to be a real path — `agent.ts` creates it at session boot. Deliberately not `dataDir`: that one is pi's own working memory, and mixing the agent's files in makes the two indistinguishable. It exists because everything in the workspace is committed and synced, so without it a temp file the agent made ends up in the user's repo.
- `getVoiceConfig()` — the voice settings as one value (which vendor listens, which speaks, the per-vendor keys), for the `transcribe` tool and for speaking. Read whole because which key applies depends on which vendor is selected for the job in hand.
- `dataDir(chatId)` — the pi scratch-dir root. **Desktop** returns one global `userData` dir; **companion** returns a **per-session** dir so concurrent runs don't share one `pi-agent/settings.json`.
- Persistence (dumb I/O — the core does all mapping): `getChat`, `upsertChat`, `appendMessages` (must be idempotent by `entryId` and assign ordering itself), `setChatTitle`, `setRunning`, `getTranscript`, `putTranscript`, optional `onError`.
- `chatSearch` — **optional**: `{ searchChats, readChat, recentChats }`, backing the `search_chats` tool. Omit it and the tool isn't offered at all, rather than offered and broken. Companion queries Postgres directly, desktop goes over HTTP.
- Secret getters: `getAgentSecrets()` (decrypted metadata), `getToken(name)` (a usable credential). **Both hosts route `getToken` to the companion**, so OAuth refresh lives in one place (desktop over HTTP, companion via `mintToken` in-process).

The `emit` sink is passed **per `agentSend` call**, not stored on the host — so the desktop can re-target events after a window reload. Events are stamped with `chatId` inside the runtime.

## Files

- `agent.ts` — the runtime: `AgentHost`/`ChatRow`/`RunOpts`/`Entry` types, `createAgentRuntime`, the session lifecycle, `resolveModel`, `listThinkingLevels`.
- `agentTokens.ts` — `makeAgentTokenTools(getSecrets, getToken)` → the `list_agent_secrets` + `get_agent_secret` custom pi tools (getters closed over per-runtime, never module-global).
- `chatSearch.ts` — `search_chats`, the agent's memory of earlier chats in the workspace. ONE tool with three uses picked from the arguments: `query` searches, `chatId`+`around` reads a window, nothing lists recent. No model calls — every shape returns stored messages. Search returns whole CONVERSATIONS (deduped, so N results are N distinct chats), each with the hit, the messages either side, and the chat's opening and closing — a mid-conversation match is meaningless without them. Tool output is not indexed (one directory listing outweighs a whole conversation) and the current chat is excluded. Backed by `host.chatSearch`: the companion queries Postgres directly, the desktop over HTTP — same split as every other chat read.
- `sendMessage.ts` — `makeSendMessageTool(send)` → the `send_message` custom pi tool. One tool definition, two deliveries: the companion passes an in-process `sendTelegramMessage`, the desktop passes a `POST /telegram/send`. Same factory-closed-over-host-I/O shape as `agentTokens.ts`. It carries **one argument, the text**. **How the message is delivered is not the agent's choice** — text, voice or both is the user's setting, chosen with `/voice` and read at the delivery end. There is no per-message override and deliberately no argument for one: it had `output`, the agent passed `both` where the setting said `text`, and the user got a voice note they had switched off. A standing preference anything else can overrule is not a preference, it is a default, and the person who set it cannot tell which they have. The override is also unfalsifiable from outside — the setting says one thing, the messages do another, and nothing in between is wrong enough to look at. The argument existed on the theory that the agent knows when a message carries something worth re-reading; it might, but the user answered that for every message when they chose the mode. **The HTTP route ignores `output` too** (`api/src/server.ts`), because an older desktop still sends one and honouring it would leave the override alive from one machine and not another. It cannot CHANGE the preference either, for a separate reason: a tool that sends a message and also mutates configuration is a category error, and it put a settings write on the end of a path reachable from any Telegram message or repo file. Changing the mode is `/voice`, answered from the database with no turn and no agent — where hermes ended up too.
- `voiceProviders.ts` — **THE table of speech vendors and what each can do**: `VOICE_PROVIDERS`, `providersFor(job)` (+ the `listenProviders`/`speakProviders`/`micProviders` aliases), `canDo`, `voiceConfigOf`, `providerForJob` and the three resolvers it dispatches to, `listenKey`/`micKey`/`speakKey`, `canSpeak`. Here because it is the one fact both directions and both hosts need.

  **THREE JOBS: `listen`, `mic`, `speak`.** The matrix is not square — AssemblyAI listens and cannot speak at all — which is why they are chosen separately rather than by one "voice provider" dropdown. The **microphone is its own job** for a different reason: a vendor can be *permitted* one and not the other, and **Deepgram's key-creation default (`usage:write`) transcribes and cannot mint a streaming token**, with Member behind an "Advanced" toggle. That is the ordinary Deepgram key, so before `micProvider` existed the common setup was a dead microphone with nowhere to go. `mic` is also optional on the table, so a transcribe-only vendor added later cannot inherit the microphone by accident.

  **Keys are per VENDOR, not per job** (`voiceKeys.<slug>`, a wildcard credential): pick Deepgram for all three and you enter one key, because it is one account. Vendor differences used to be four `provider === 'deepgram'` ternaries scattered across the key lookup, the engine name, the token mint and the failure message.

  > **`DEFAULT_LISTEN` is gone. Do not bring back a constant here.** It was `'assemblyai'` and applied whether or not a key for that vendor existed, so an install holding one ElevenLabs key was told *"No AssemblyAI key — add one"* — naming a vendor nobody chose, for a job a working key already covered. `soleKeyedProvider` replaced it: a vendor resolves only when exactly one **capable, keyed** vendor qualifies, which makes the old answer unreachable and leaves ambiguity unset. That is resolution from stored data, not a default. **`speakProviderOf` is excluded from even that** — speaking costs money per reply, so pasting a transcription key must never start synthesizing audio nobody asked for.

  Two more details are load-bearing. **ElevenLabs' streaming token is single-use** where the other two are reusable for 60s, so `mic.singleUse` travels back with the minted token and the renderer's cache keys on it. And **`voiceConfigOf` folds `hasVoiceKey` in when `voiceKeys` is absent** — the renderer never receives key values, and this is what lets the settings page resolve through these same functions instead of reimplementing "which vendor does this job", which is how Settings comes to show one answer while the agent uses another. The stand-in values exist only to be tested for presence; every non-renderer call site reads unstripped settings. Pinned by `tests/voiceProviders.test.js`.
- `spokenText.ts` — **the read-aloud rules**: `prepareSpokenText(text, maxChars)`, a fixed set of find-and-replace passes that turn a reply into a script a speech engine can say. Strip markdown, expand symbols (`~` → "about", `°C` → "degrees Celsius", `$1,200` → "1,200 dollars", `%` → "percent", table bars → pauses), fold a heading into the sentence after it, flatten newlines. **Not a model, on purpose**: the promise is that it cannot drop a fact, and only substitution can guarantee that — a rewrite pass can be asked and not held to it. Ported from hermes `tools/tts_text_normalize.py`, which reached the same conclusion. Three deliberate divergences, all marked in the file: bare URLs keep everything but the scheme (hermes deletes them, which loses a fact), a dot before a lowercase letter is left alone (hermes' rule turns `renameOps.ts` into "renameOps. ts"), and a bare `m` is not expanded to "meters". The one deliberate removal is a fenced code block. Pinned by `tests/spokenText.test.js`, whose facts-survive cases are the point of the file.
- `speak.ts` — text to speech, the mirror of `transcribe.ts`: `speakToFile(text, config, outPath, onError)`, `probeSpeak(provider, apiKey, config)`, plus `sniffContainer`/`ensureOgg`. **`probeSpeak` is how Settings verifies a speaking key** — it runs the REAL provider on a two-character script and throws the bytes away, because neither vendor answers "may this key synthesize?" any other way: a key can be valid, list voices happily, and still lack the endpoint scope (ElevenLabs) or the credit. Going through `PROVIDERS` means it exercises the configured voice and model rather than a second copy of the vendor's URL, so adding a vendor is still one function. Like `speakToFile` it never throws. **Nothing checked speaking at all before it**, which is how a broken speech key stayed invisible until a Telegram reply failed to come back as audio. A PROVIDER returns audio bytes and says what container they arrived in; adding a vendor is one function. **Output is Ogg/Opus** because that is what a Telegram voice bubble requires — both vendors emit it directly, so the happy path never converts, but they are *asked* rather than commanded, so the bytes are sniffed and repaired when a vendor ignores the request (hermes carries the same repair after backends silently returned MP3 for Opus; without it you get a file Telegram rejects with no explanation). **It never throws**: every caller is a reply that has already been written, and no synthesis failure should cost the user their answer. Pinned by `tests/speak.test.js`.
- `speechChunks.ts` — **splitting a script into the pieces it gets spoken in** (`splitForSpeech`, `CHARS_PER_SECOND`). Every byte of a voice note is synthesised before any of it is sent, so one long answer is a long silence and then everything at once. Pure: no vendor, no network, no clock. **Delivery keeps two pieces in flight** — the most both vendors allow (Deepgram REST 2, ElevenLabs 2 on Free) — which makes the ladder the whole design: piece N+1 must be finished before the audio already sent runs out, or the listener hits silence. The rule is `make(next) <= window * MARGIN`, where the window is the buffered audio PLUS the previous piece's make time (they overlapped, and that overlap is real). The buffer also ACCUMULATES, since speech plays ~2.7x slower than it generates, so every piece leaves more slack than it spent. **There is no fixed list of budgets**, deliberately: a list is that rule with the derivation thrown away, and it goes quietly wrong when any measurement changes. The constants are measured against the configured voice, not assumed — `650ms + 21.8ms/char` to make, ~17 chars/sec to play, and a cold connection times the same as a warm one, so there is nothing to pre-open and length is the only lever. **A SENTENCE IS ATOMIC** — the one rule the splitter has. Every piece ends where a sentence ends, and the budget therefore sizes a piece by choosing how many sentences it holds, not where to cut. A piece routinely runs past its budget because the sentence it is inside has not finished. Only two things override this, and neither is a preference: a single sentence over the **vendor's input cap** (where the request is rejected outright and the audio lost) or over `LONGEST_SENTENCE` (400 chars, ~24s — a stack trace or a bulleted list is not a sentence, and without a ceiling one made a "five second" piece a minute long). Those get broken at a clause, else a word boundary. `CLAUSE_END` exists for that case and nothing else.

This replaced a tiered scheme where a clause end was a general alternative any small budget could take, and the cost was a **quarter of all clips stopping mid-thought** — `"Sure, I can do that. I'll start by pulling the"` was a real opener. Going sentence-only is paid for in the first sound, and that was measured rather than assumed: over nine real-shaped replies, 33 pieces → 25, mid-sentence cuts 8 → 0, first sound 2.61s → 3.88s. There is no fast opener to be had in "Not quite." followed by 243 characters without a full stop — you either say five words and go quiet or you wait for the sentence. **`FIRST_PIECE_MIN` (30) is what decides that**, and it is separate from `MIN_FILL` because they answer different questions: `MIN_FILL` asks whether a break is worth using at this size, the opener floor says the first piece may not be small whatever is on offer, since everything after it is sized from how long it PLAYS. **It is therefore the knob for "fewer, longer voice notes", and the only honest one** — raising it lifts the whole ladder, where nothing downstream can be dialled directly because piece lengths land wherever a sentence ends. **It was 60 for a day and 60 was wrong.** Raising it does buy pieces on long replies (a 1,093-character answer went six voice notes → four), but it buys them by REJECTING a perfectly good opening sentence and charging the difference to the one wait nothing covers. Measured on a real reply: `"yt-dlp is still the answer, and it's not close."` is 47 characters, fails a floor of 60, so the opener swallows the sentence after it and runs to 169 — **eighteen seconds of audio before the reply starts**, against under three at 30. An extra bubble you can already hear beats eighteen seconds of nothing. Dead air was zero at both values, so the whole trade is against the opening wait and never against a gap mid-answer. **The floor applies to every fallback too** — the word boundary and the over-long-sentence clause break included. An unguarded fallback is what produced that `"pulling the"` opener, losing the phrase AND the size that keeps the ladder growing.

Two promises pinned by `tests/speechChunks.test.js`: **nothing is lost** (the vendor's input limit is a hard cap the split respects, where `speakToFile` alone would CUT — which is how the tail of a long answer was silently never spoken) and **every piece is ready before the ones before it stop playing**, checked by replaying the measured timings over real splits.
- `voiceReply.ts` — the reply mode — `text` | `voice` (audio only) | `both` — plus `sendsText` / `speaks`, the one place those three become the two booleans every delivery path actually asks about, and `isVoiceReply` so `/voice bogus` says so instead of silently setting text. **Pure policy, no disk**: the value lives on the companion as one ordinary settings row, `speech.telegramReply` — named here as `VOICE_REPLY_SETTING_PATH`, because six places have to agree on that string and none can see the others. Not a file in the checkout, because `/voice` is a slash command answered from that database with no checkout prepared. **App-level, and it was per-workspace until 2026-08-06** (`workspace.voice_reply`): the bot's active workspace is chosen independently of the desktop's, so Settings wrote the mode of a workspace the bot was not pointed at and the replies stayed text with nothing on screen able to say why. The workspace row was only ever about not being in the checkout — a storage argument a settings row satisfies identically — and the scope it implied was never intended. Normalized on the way in and out, since the row is plain text and two things write it.
- `transcribe.ts` — speech to text (`transcribeFile`, `transcribeVoice`, `warmTranscription`) plus the `transcribe` tool. A PROVIDER returns timestamped segments and nothing else; adding an engine means writing one function. Which one runs is `settings.transcription.provider` — **`assemblyai`, `deepgram` or `elevenlabs`** — applying to everything that listens, the desktop microphone's streaming socket included. Which key that implies is `voiceProviders.ts`'s job, not this file's and not every caller's: callers pass the whole voice config rather than a key. **ElevenLabs is the odd one on two counts**: it returns a flat WORD list where the other two return speaker turns, so `segmentsFromWords` draws the cue boundaries here (new turn on a speaker change or a 1.5s silence); and its `tag_audio_events` **defaults to true**, which would write "(laughter)" into the middle of a user's voice note and hand it to the model as something they said — so the voice-note path turns it off, along with diarization and word timestamps. That is a correctness fix, not a fast path. Speaker labels are on — a two-person recording without them reads as one voice contradicting itself. **No timeout of its own**: unattended runs are already bounded by `codingAgent.maxRunMinutes`, and a second shorter limit could only fail a transcription that was going to succeed. **Two shapes of work, two APIs:** a RECORDING (`transcribeFile`) can run an hour with several speakers, so it submits an async job and polls; a VOICE NOTE (`transcribeVoice`, companion/Telegram only) is one person for seconds and its text becomes a prompt immediately, so it takes AssemblyAI's **sync** endpoint — one request, ~0.25s against ~3.5s, because what it removes is the SDK's 3-second poll tick. The sync endpoint won't take Telegram's OGG/Opus (the SDK labels every non-PCM part `audio/wav` and the server trusts the label), so the audio is piped through ffmpeg to **raw PCM** — headerless, so unlike a pipe-written WAV there is no RIFF length to be wrong. Over 2 minutes, or any failure, falls back to the job path with a `console.warn`. Full reasoning in `api/CLAUDE.md` under "Voice notes go to the sync API". **Deepgram needs none of that shape**: it has ONE pre-recorded endpoint for both jobs, nothing to poll, no duration ceiling, and it sniffs the container itself — so Telegram's OGG/Opus goes byte-for-byte and **ffmpeg never runs on the Deepgram path**. That is also why `warmTranscription` is an AssemblyAI-only no-op: there is no SDK session to open.
- `dailyNote.ts` — **the one definition of what a daily note is called**, shared with the renderer (`src/renderer/dailyNote.ts` re-exports it). Dependency-free for the same reason as `credentials.ts`, and **no `node:` imports** — the renderer bundles this file and has no Node. Two copies of these rules would drift into the agent writing `2026-08-01.md` while the app looks for `Journal/2026/08/2026-08-01.md`, leaving the user with two notes and neither side finding the other's. **Exactly one function needs a timezone** (`todayISO`, "what is today?"); everything downstream takes a CALENDAR DATE (`YYYY-MM-DD`), which has no timezone by construction, so naming and parsing can't fall back to the machine clock because they never read a clock. That split is the fix for a real disagreement — all three hosts set `process.env.TZ` from `settings.timezone`, the renderer never did, so near midnight the calendar button and the agent resolved different days. `basenameIdentifiesDate` is the other rule worth knowing: a path-style format (`YYYY/MM/DD`) leaves the basename a bare day number, so looking `01` up workspace-wide answers August 1st with July's note — both callers gate their by-basename lookup on it. Pinned by `tests/dailyNote.test.js`.
- `dailyNoteTool.ts` — the `daily_note` tool: the I/O around `dailyNote.ts`, same split as `transcriptFormat.ts` beside `transcribe.ts`. **No `AgentHost` plumbing** — it reads `.shockwave/workspace.json` straight off disk, which exists in both hosts (the companion's cron runner already reads that same file for `builtinSkills`), and re-reads it per call so a settings change mid-chat lands without a session reboot. Built per session with the workspace closed over, like `transcribe` with its scratch pad. **`create` defaults to TRUE** — resolving a daily note is nearly always a prelude to writing in it, and only an explicit `create: false` opts out (tested with `=== false`, so a `null` from a strict provider still creates). It defaulted to false until 2026-08-06, to stop "what did I write last Monday" leaving an empty file dated last Monday. That failure is real but rare and **visible**; the write path's failure is neither. With the old default the agent was told to "call again with create: true", and an agent that reads that can instead reach for `write` and make the file itself — which silently skips the user's template. One extra argument on a read beats a note that never got its template. Creation seeds from that template verbatim (nothing in Shockwave substitutes placeholders) and writes `wx`, since losing a race here costs a day of writing.
- `transcriptFormat.ts` — segments → SRT / WebVTT / prose. Pure and separate so the output format can't drift when the engine changes, and so it's testable without a network call (`tests/transcriptFormat.test.js`). The two subtitle formats differ by one character — SRT uses a comma before the milliseconds, WebVTT a dot.
- `mediaTags.ts` — finding the files the agent asked to send, in the text it wrote (`extractMedia`, `extractLocalFiles`, `validateDeliveryPath`, `deliveryKind`). Ported from hermes-agent. Both hosts need the same rules and the allowed folders differ per host, so the roots are an argument, not knowledge. The two passes are **chained** — the bare-path scan reads what the tag scan cleaned — and that chaining IS the dedup. Dependency-free for the same reason as `credentials.ts`; pinned by `tests/mediaTags.test.js`.
- `defaults/companion.ts` — prompt sections for turns running ON THE COMPANION (Telegram, cron): today, how to send a file. Gated on `source`, and therefore **frozen at chat creation** like everything else in the prompt: a chat created on the desktop never gains the file-delivery section, even when it is later continued over Telegram. That is the accepted cost of a prompt that is written once; what a particular RUN needs to say goes in its first user message instead.
- `attachmentPolicy.ts` — **what a file the user sent IS, and where it goes**: magic-byte sniffing (`sniffImageMime`/`looksLikeImage`), `safeName`, `classify`, `describeAttachment`, and the one write both hosts perform, `writeAttachment(dir, data, opts)`. Here because **both hosts take files from the user** — the companion over Telegram, the desktop through the chat composer — and a second copy would be two answers to "is this a PDF or a picture", which is the answer that decides what the agent is told it is holding. The **directory** is the argument, not knowledge: `chatFilesDir` on the companion, `chatScratchDir` on the desktop. Needs `Buffer` + `node:fs`, so it runs in main / on the server and never in the renderer — which is what the split below exists for. It lived at `api/src/telegram/attachmentPolicy.ts` until the desktop grew the same feature. Pinned by `tests/attachmentPolicy.test.js`.
- `attachmentNotes.ts` — **what the agent is TOLD about that file**: the four bracketed notes, `composeMessage`, `TEXT_INLINE_EXTS`, `MAX_TEXT_INLINE_BYTES`. Strings and nothing else — no `node:path`, no `Buffer`, no filesystem — which is the whole reason it is a separate file: the desktop builds its prompt in the RENDERER while the bytes are sniffed and written in main, so without this seam the renderer would need a bundler polyfill or a second copy of the wording. The wording is hermes-agent's and is the load-bearing part: it tells the agent to **act** on the file and to ask only when the intent is genuinely unclear. Passive wording there made the model reply "what would you like me to do with this?" to a message that already said, which is what makes a bare path pointer work at all.
- `messageImages.ts` — `imagesOf(content)`: the user's images, pulled off a pi message into the shape `ChatRow` carries. **The only thing that gets a picture into storage**, and therefore the only reason chat images render. `textOf` deliberately keeps text alone (`message.content` feeds the search tsvector — base64 there buries every real match), so images need their own carrier. One function covers both clients: desktop and Telegram hand images to pi identically, so they arrive in the same `content` array. Dependency-free for the same reason as `mediaTags.ts`; pinned by `tests/messageImages.test.js`, because its failure mode is silence — nothing errors, nothing logs, pictures just stop appearing.
- `chatNotice.ts` — the **"catching up" defaults** (`enabled`, `afterHours`, `limit`) and `resolveChatNotice`, which fills each field independently. Here for the same reason as `credentials.ts`: **two builds resolve it** — the companion decides whether to send the notice (`api/src/telegram/commands.ts`), the desktop's Telegram settings page renders the numbers in effect — and a second copy is how the page comes to say 24 hours while the bot waits 48, with nothing anywhere to report the disagreement. Every field is optional and unset means unset, so a partial object is the normal case (settings rows are written one leaf at a time). Pinned by `tests/chatNotice.test.js`.
- `credentials.ts` — **THE declaration of which settings fields are credentials**, and the path helpers its consumers share (`getPath`/`deletePath`/`setPathCopy`/`isSet`/`isDeletableCredential`). Nothing to do with the agent runtime; it lives here because `agent-core` is the only code bundled into **both** builds (the desktop's electron-vite build and the companion's esbuild — see `api/Dockerfile`). Dependency-free so `node --test` loads it directly and both TypeScript builds import it without ceremony, same as `keys.ts` and `linkParser.ts`. (It was literally a `.js` file until the test suite learned to name the `.ts` one — see the import rule in `tests/CLAUDE.md`.) Three consumers derive from it: the companion's `api/src/keys.ts` (what to encrypt), `src/main/settingsStore.ts` (what to strip before the renderer), `src/renderer/settingsDiff.ts` (what not to send back). It used to be written out three times, and a mismatch is not cosmetic — miss a field in the strip and it leaks to the screen, miss it in the send guard and an unrelated save deletes it. **Adding a credential is one edit, here.** Pinned by `tests/credentials.test.js`.
- `scratchSweep.ts` — **the TTL rule for per-chat working directories**, run by both hosts: `sweepScratchDirs(bases, { ttlDays, keep })`, `resolveTtlDays`, `DEFAULT_SCRATCH_TTL_DAYS` (7). Deletes a directory whose mtime is older than the TTL **unless its chat is pinned**, in which case age is never consulted. Here, not in either host, because the desktop sweeps one base (`<userData>/agent-scratch`) and the companion three (`work/`, `runs/`, `files/`) off the SAME setting — two copies drift into the two sides deleting different things while Settings shows one number. Dirs are keyed by chatId (the directory name IS the chat id), which is what makes the exemption a set-membership test. Not dependency-free — it's `node:fs`, so the renderer can't import it; the number on the settings page is a placeholder string. Pinned by `tests/scratchSweep.test.js`.
- `modelCatalog.ts` — the models.dev catalog: fetch/cache chain, `getCatalogModels`/`getCatalogModel`, `DEV_KEY` slug map.
- `skillLibrary.ts` — skill scanning + workspace-override resolution; writes the effective skill list into pi's settings at boot. Also names the three roots (`workspaceSkillsDir`, `agentSkillsDir`).
- `skillValidate.ts` — what a skill has to look like before it is written: name, frontmatter, sizes, supporting-file paths. Owns the ONE frontmatter parser (`skillLibrary.ts` imports it) because this module is the one under test. Two deliberate departures from hermes, both because **pi is the loader here**: the name rule is pi's stricter one (lowercase, digits, hyphens; no leading/trailing or consecutive hyphens), and hermes' 60-character description limit is NOT ported — it exists because hermes truncates its own skill index at 57 chars, while pi's `formatSkillsForPrompt` emits the description whole.
- `manageSkill.ts` — the five actions (`create`/`edit`/`patch`/`write_file`/`remove_file`) behind `manage_skill`. **No `delete`** — hermes' delete carries a fail-closed consolidation guard, `absorbed_into` validation, rmtree containment and an archive-vs-remove branch, all of it serving a curator we do not have.
- `fuzzyMatch.ts` — the 9-strategy patcher behind `patch`, ported from hermes `tools/fuzzy_match.py`. **Not from knack's TypeScript copy**, which predates four fixes; each is pinned by a named test in `tests/fuzzyMatch.test.js`.
- `skillTool.ts` — the `manage_skill` pi tool, plus the `read` override that makes read-before-write possible. One factory because they share the set of files this run has loaded.
- `memoryStore.ts` — **the two memory files and everything that decides whether a write to them is correct**: the `§` format, the char budget, substring matching, the atomic write, and a per-path lock. Ported from hermes `tools/memory_tool.py`. Five documented departures, of which two are load-bearing here and nowhere else: the files live **in the workspace repo** (root `MEMORY.md` / `USER.md`, beside `SOUL.md`), and writes are serialized by an **in-process promise chain per path** — the desktop runs several chats against ONE workspace folder, and a naive read-modify-write loses an entry outright, measured. hermes' drift refusal and `.bak` snapshots are deliberately NOT ported: they protect a machine-owned file from human edits, and here the user opening these files in the editor is the point. Pinned by `tests/memoryStore.test.js`, including the two failure modes that were measured before being fixed (concurrent loss, and an unreadable file rewritten as empty).
- `memoryTool.ts` — the `memory` pi tool. Built per session with the workspace and its budgets closed over, same shape as `makeDailyNoteTool`. **The description IS the behaviour** — hermes' `MEMORY_SCHEMA["description"]`, extracted by AST, one substitution (`session_search` → `search_chats`). The batch shape it tells the model to prefer is what lets one call free space and add together; the "don't repeat it" clause is what stops the same write being reissued five times. Returns a `render()` for the prompt block and a `resetTurn()` the runtime calls at the start of every turn.
- `templates.ts` — `readTemplates`: the templates snapshot (folder + `.md` list from `templates.folder` in `.shockwave/workspace.json`, direct children only — same list as the app's picker) baked into the prompt's `# Templates` section at chat creation and frozen with it, like the memory blocks. Anything invalid — no config, folder unset/missing/empty — returns undefined and the section is simply skipped.
- `defaults/conversation.ts` — rendering a stored conversation to text, shared by the two background runs. They are separate processes; this is the one thing they legitimately share.
- `defaults/reviewPrompt.ts` — the review instruction (hermes' `_SKILL_REVIEW_PROMPT`, extracted by AST, eight documented substitutions).
- `defaults/memoryPrompt.ts` — the memory instruction (hermes' `_MEMORY_REVIEW_PROMPT`, extracted by AST, **zero substitutions** — it names one thing outside itself, "the memory tool", and ours is called that). Deliberately four sentences: the rules about what to save live in the tool description, and a second copy here would compete with them. It carries **no bias to action**, unlike the skill prompt — see "Memory" below.
- `defaults/index.ts` — `assembleSystemPrompt` + re-exports. The ONE place a prompt is ever built.
- `defaults/tools.ts` — `TOOL_CATALOG` (the single source for the prompt list AND the pi allowlist), `activeToolNames()`, and **`DENIED`** — what each kind of run may not do, and the sentence it gets when it tries.
- `toolGate.ts` — the inline pi extension that enforces `DENIED`, refusing a call and handing back the reason.
- `defaults/workspaceFiles/` — one module per seeded workspace file, each exporting `<X>_FILENAME` and `DEFAULT_<X>`: `soul.ts` (also `readSoul`, the runtime fallback), `agents.ts`, `memory.ts`, `user.ts`, `ignore.ts`, `gitignore.ts`, and `index.ts` (the `DEFAULT_FILES` manifest + `ensureWorkspaceFiles`/`missingWorkspaceFiles`).
- `defaults/helper.ts` — `buildShockwaveHelper` (the app operating-manual section of the prompt; `UNATTENDED` override). Every section is included on every run now: the tool list no longer varies, so there is no run missing a tool to protect from being told about one.
- `cronValidate.ts` — **pure** rules for a scheduled job: does the schedule parse, will it ever fire, is the name unique, is there a prompt, is `cron.json` still an array. No disk, no host, unit-tested (`tests/cronValidate.test.js`). Same split as `skillValidate.ts` beside `manageSkill.ts`. **Validity is two questions, not one** — `croner` throws on a pattern it can't parse but accepts a datetime that has already passed and simply reports no next run, so a parser alone answers the first and silently passes the second. That second case is the ordinary one-time reminder: the agent knows today's date and never the time of day. Uses the **same croner** the scheduler runs (added to the desktop manifest so `agent-core` resolves it in both builds; `tests/sharedDeps.test.js` pins the versions matching) — a second parser would answer "is this valid" differently from the thing that fires it.
- `cronTool.ts` — the `cron` tool: `create` / `update` / `remove` / `list` / `status`. Writes `cron.json` itself, so validation can't be skipped. `status` is the half that never existed — the companion has recorded every run's outcome in `cron_state` all along and the agent could not see any of it, so it could not tell whether a job it made had registered, or that a nightly job had failed six nights running. Backed by the optional `AgentHost.cronStatus` (companion reads the table + croner in memory, desktop asks over HTTP — same split as `chatSearch`); absent, only `status` is unavailable and the write half still works offline.

**What a single tool is FOR belongs in that tool's description, not here.** `REACHING_THE_USER` (the "send me / notify me / remind me / ping me" → `send_message` mapping), `DAILY_NOTES` and `# Creating skills` all used to live in this file and are now in `sendMessage.ts`, `dailyNoteTool.ts` and `skillTool.ts` respectively. Two reasons, and the second is the structural one: the model reads a tool description at the call site, and **this file is frozen into a chat when the chat is created** — a fix here reaches only chats started afterwards, while a tool description is rebuilt at every session boot and so reaches conversations already in flight. What stays in `helper.ts` is what no single tool owns.
- `defaults/files.ts` — `DEFAULT_FILES` + `ensureWorkspaceFiles`/`missingWorkspaceFiles` (on-disk workspace scaffolding).

## Session lifecycle (`agent.ts`)

**One live pi `AgentSession` per chat**, keyed by `chatId` in a `sessions` map; in-flight boots share a `booting` map (two managers on one JSONL corrupt it). Chat IDs are minted by the **caller** (renderer / cron / telegram) and passed to `SessionManager.create({ id })`, so events route from the first millisecond.

- **Session cache key** (`makeKey`) = `workspacePath|provider|model|apiKey|baseUrl|contextWindow|thinkingLevel`. Any change reboots the session on the next send.
- **Validation** (`agentSend`, throws before any work): no chatId → "agentSend requires a chatId."; no workspacePath → "Open a workspace first."; **no provider → "Coding agent provider not configured."**; no model → "Coding agent model not configured."; non-`openai-compatible` with no apiKey → "…API key not configured." These are the errors the Telegram/cron runners surface when a required setting is unset — there is **no default** for provider/model/key (see the no-defaults policy in `api/CLAUDE.md`).
- **Steer mid-turn**: if the session is running, `session.prompt(text, { streamingBehavior: 'steer' })` — pi delivers it at the next step of the running turn.
  - Checked **before** the provider/model/apiKey validation: a steer joins an already-booted session, so the caller has nothing to supply (the Telegram relay passes no workspace or model at all).
  - `emit` is **not** re-pointed. It used to be, which handed the running turn's event stream to the second caller's sink — on Telegram that froze the first reply half-written and drew the remainder under the wrong message.
- **Create vs open (resume) — the stored transcript ALWAYS wins.** For an existing row, `bootSession` downloads `getTranscript` and overwrites the local file unconditionally, then opens it with the row's frozen `systemPrompt`. No row → `SessionManager.create(...)` with a freshly assembled prompt. **A row with no recoverable transcript throws** — silently starting a real conversation from an empty session is how a whole turn vanishes.
  - The local JSONL is only THIS machine's working copy. It goes stale the instant any other client (desktop, Telegram, cron, a second machine) takes a turn in the same chat, because that client uploads its own transcript and ours knows nothing about it. Anything present only on our disk is by definition something no other client has seen.
  - **Don't add a "keep the local file if it looks newer" test.** Line counts only imply ahead-ness on a shared lineage; once both sides diverge, that test picks the stale local copy — precisely the bug. The only loss from always-copying is pi's context from a turn whose transcript upload failed, and that self-heals (the whole file is re-uploaded every turn), the messages are already stored row-by-row, and the failure is reported via `host.onError`.
  - `findSessionFile` still LOOKS UP pi's file rather than reconstructing the name (pi writes `<timestamp>_<chatId>.jsonl`; the old hand-built `<chatId>.jsonl` never matched).
- **A live session is re-checked before reuse.** `ensureSession` returns the cached entry only after `transcriptMovedOn` confirms the row's `transcriptUpdatedAt` hasn't advanced past the value we last booted from / uploaded (`Entry.transcriptAt`). Without this, a long-lived host — the companion holds one session across Telegram messages — would skip boot entirely and never notice a turn another client took in between. That is exactly how a Telegram reply came back not knowing about a message sent from the desktop.
- **Config-change reboot**: a **running** entry is reused unconditionally (mid-turn config change waits); an idle entry reboots on the same JSONL when `key`/`workspacePath` changed.
- **Messages are stored AS THEY HAPPEN, not in a batch at the end.** `syncEntries` reads `sessionManager.getEntries()` — pi's own append-only log, where each entry already carries a stable unique id — on every `message_end` (and again after the turn), and appends anything not yet sent. So tool calls appear while the turn runs, and a turn that errors, is aborted, or times out keeps everything it managed to do.
  - Identity is pi's `entry.id`, never a position. `seq` used to be the message's index in `session.state.messages` — the RESOLVED LLM context, which legitimately shrinks (compaction), rewinds (branching), and gets spliced on a failed turn — inserted `ON CONFLICT DO NOTHING`. A later message could land on a slot a different earlier message already held and be silently discarded. Keyed by entry id, a conflict means "same message, already stored", so retries and bulk re-sends are safe.
  - **`entry_appended` is NOT a message hook** — don't reach for it. It's declared in `AgentSessionEvent`, but there is exactly one emit site (`dist/core/agent-session.js`): the *extension* API's `appendEntry(customType, data)`, which appends a **custom** entry. Conversation messages go through `sessionManager.appendMessage`, which emits nothing. The session events that actually fire during a turn are `agent_start`, `turn_start`, `message_start`, `message_end`, `message_update`, `turn_end`, `agent_end`, `agent_settled` — hence `message_end` plus a read of `getEntries()` for the ids.
  - Writes are chained per session (`writeChain`) so rows arrive in pi's order; a failed append stays in `pending` and is retried by `flushPending` after the turn.
- **End of turn**: `flushPending` → `uploadTranscript` → **then** `setRunning(null)` → best-effort auto-title. Running clears only after upload, so a cross-client viewer never sees "done" before the rows land. On throw, running clears immediately.
- **Failed-turn splice**: if the turn ended with `[user, assistant(stopReason:'error')]` (e.g. an oversized image), both are spliced out of pi's in-memory state so they don't re-poison later turns; a synthetic `agent_send_failed` event is emitted.
- **Auto-title** (`maybeGenerateTitle`): only when the row has no title; a `completeSimple` call over the first exchange, fire-and-forget.
- **pi→row mapping**: one pi message → one `ChatRow` (assistant → content/reasoning/toolCalls; toolResult → `role:'tool'`; else user). A user row also carries `images` (`messageImages.ts`) — pi holds them beside the text parts and `textOf` drops them, so without that field a picture reaches the model and then vanishes, which is exactly what it used to do. The host's `appendMessages` stores them; the same one append covers both clients.

## System prompt

`assembleSystemPrompt(workspacePath, { unattended, source, scratchDir, timezone, memory })` returns `SOUL + helper`:
- **SOUL** = the workspace's `SOUL.md` (cwd root), else `DEFAULT_SOUL` in memory (never written). `SOUL.md` is a normal file the user edits — there is no settings UI for it.
- **helper** = `buildShockwaveHelper({ tools: TOOL_CATALOG, unattended, … })` — the app operating manual, sections as named consts, the whole tool list interpolated in, and the rendered memory blocks last.

The result is passed to pi as `systemPromptOverride`, replacing pi's built-in prompt. **pi then appends on its own at boot**: discovered `AGENTS.md`/`CLAUDE.md` (cwd→root), the enabled skills list, and `Current date`. So the final order is SOUL → helper → memory blocks → context files → skills → date, and agent-core deliberately does not add the last three.

**The sections that varied by TOOL no longer vary** — every run is offered the whole catalog, so every section is present on every run. What still varies is the handful that depend on WHERE the turn runs, and those are frozen with the prompt at chat creation:

| section | gated on |
|---|---|
| Unattended run | `unattended` (cron, review, memory) |
| Sending the user a file | `source` is Telegram or cron |

A chat created on the desktop therefore never gains the file-delivery section, even when continued over Telegram. That is the accepted cost of writing the prompt once; anything a particular run needs to say goes in its first user message.

The gating machinery in `helper.ts` still works when handed a subset and is pinned that way — nothing calls it so today, but a broken one would fail silently.

The memory **blocks** go in whenever there is content. A review run cannot write memory — the gate refuses the call — but it still gets the facts, because knowing the user makes for better skills.

**The whole prompt is frozen per chat.** It is assembled once, when the chat is created, written to the chat row, and read back verbatim on every boot for the life of that chat. `upsertChat`'s conflict branch touches only `updated_at`, so the row has always held the original — what changed is that nothing regenerates it in memory any more. A chat with no stored prompt cannot be continued and says so, rather than quietly starting under different instructions.

There used to be a `rebuildSystemPrompt` that kept the SOUL and regenerated the helper on every resume, cutting on a `HELPER_MARK` comment. It existed for exactly one reason: the offered tool list varied by source, so a chat started on Telegram and continued on the desktop would advertise its creator's tools while pi enforced a freshly computed allowlist. Every run is offered the whole catalog now and refused per call, so there is nothing left to correct — and a chat's instructions no longer change under it between one message and the next. The marker is gone with it.

**What a particular RUN needs to say goes in its first user message**, which was never frozen. That is where a background run is told its checkout path (the inherited prompt names the source chat's) and that nobody is present.

**Unattended mode (cron):** `assembleSystemPrompt(ws, { unattended: true })` inserts the `UNATTENDED` section, which overrides the "ask first" boundary — a scheduled run has no user, may create/edit/move/delete freely, and its work is committed after the run. Threads through `RunOpts.unattended` → the **create branch only**; a fresh uuid per cron run guarantees that branch, so cron is always unattended.

## Tools (`defaults/tools.ts`)

**`TOOL_CATALOG` is the single source, and it is offered WHOLE to every run.** `activeToolNames()` takes no argument: it is the pi allowlist (`createAgentSession({ tools })`) on every chat of every kind. What a run may not USE is a separate question, answered at call time.

**A catalog entry is a name and an origin — it carries no description, and the prompt lists no tools.** pi sends the model every tool's real name, description and parameter schema as a tool definition (its builtins and our `customTools` alike), so a tool is documented in exactly one place: its own definition. There used to be a `desc` per entry, rendered by `formatToolList` into an "Available tools" section of the system prompt — a second, thinner copy of what already arrives, separately maintained and therefore drifting. `send_message`'s entry advertised an `output` argument (text/voice/both) for months after the tool stopped accepting one, so every Telegram chat's prompt taught an argument the schema rejected, and nothing failed anywhere. hermes reached the same place: it never enumerates its tools and points AT the schema where it writes about them. Both are gone; `tests/helperPrompt.test.js` pins that neither comes back. **If you want the agent to know what a tool does, write it in that tool's `description`.**

What did NOT survive in the tool definitions is the advice about choosing BETWEEN tools — pi's own `bash` snippet recommends the opposite ("Execute bash commands (ls, grep, find, etc.)") — so that moved into the prompt's `# Guidelines`, gated on holding the tools it names.

That constancy is what lets the system prompt be written once at chat creation and read back verbatim forever — a list that varied by source is the only thing the old rebuild-on-resume existed to correct.

Catalog: builtins `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`; customs `list_agent_secrets`, `get_agent_secret`, `open_file`, `send_message`, `transcribe`, `search_chats`, `daily_note`, `memory`, `manage_skill`. **The allowlist is load-bearing:** pi's `discoverAndLoadExtensions` scans `<dataDir>/pi-agent/extensions/` unconditionally and *adds* whatever it finds; a stale extension file once made the prompt advertise 7 tools while pi ran 8. The allowlist bounds the set — a stray tool loads but is filtered out unless `TOOL_CATALOG` names it.

### What a run may not do: `DENIED`, enforced at call time

`DENIED` (in `defaults/tools.ts`) maps a source to the tools it may not use and the sentence the agent is handed when it tries. `toolGate.ts` turns that into an inline pi extension registered on the session's resource loader; pi fires `tool_call` before a tool executes and a handler returning `{ block: true, reason }` stops it, with `reason` becoming that tool's result — nothing prepended, so the sentence we write is the whole thing the model reads. Omit the reason and pi substitutes a generic "Tool execution was blocked", which tells the agent nothing it can act on; `tests/skillTool.test.js` pins that every entry carries one.

Effective sets today: a **review run** can use `read`, `grep`, `find`, `ls`, `manage_skill`; a **memory run** can use `memory`; **cron** is denied `open_file` alone (no app window) and **Telegram** that plus `send_message`; a **desktop chat** is denied nothing.

**One sentence per source, with `per` for the exception.** The reason a review run can't run `bash` is the reason it can't run `edit`, so eleven denials share one sentence. Telegram is the one source where they don't: `open_file` is about there being no app window, `send_message` is about the reply already going to Telegram — and the shared sentence answered the first while leaving the second reading about app windows. `per` maps one tool to its own sentence and replaces the shared one entirely. `send_message`'s says the messages **route** there automatically rather than that the user is present, because the likeliest motive for the call is wanting this one answer spoken and the ordinary reply already goes out under the same `/voice` mode (`sendsText`/`speaks`, `api/src/telegram/webhook.ts`). Pinned both ways in `tests/skillTool.test.js` — the override wins, and the fallback doesn't leak in beside it.

**Why refuse rather than hide.** Two reasons, and the second is the structural one. An agent that can't see a tool can't explain itself — a Telegram run had no idea `open_file` existed, so "I can't open a tab here, but I can send you the file" was not available to it. And hiding meant the offered set varied by source, which forced the prompt to be regenerated on every resume.

**Why a deny list, and its cost.** The policy is per-source — "a review run reads and curates, nothing else" is one line here against eleven scope entries spread across the catalog — and the question a reader actually asks is *what can't this run do?* The cost, stated plainly: **a tool added later is allowed everywhere until someone names it here.** The old explicit allowlists existed to prevent exactly that, and `daily_note` proved it can happen. The tripwire is `tests/skillTool.test.js`, which asserts the *usable* set of each background run by subtraction — add a catalog tool without deciding about it and that test fails.

**Why the event and not a tool override.** pi documents both (its shipped `tool-override.ts` example names access control as a use case, and our own `read` override works that way). The event wins because it is origin-blind: `bash`/`edit`/`write` are pi's and `manage_skill`/`memory` are ours, and one handler sees them all by name. By override it would be seven wrappers, each reproducing its built-in's exact result shape — pi's docs are explicit that the `details` type must match, since the UI and session logic depend on it — for no behaviour of our own. Registered as an inline **factory**, not a path: pi loads path-based extensions through jiti, which would mean shipping a TypeScript file and compiling it at runtime inside a packaged app.

Verified against a live session before it shipped: with `bash` declared and denied, the command's side effect never happened — the file it was told to create did not appear — and the model reported the reason in its own words.

`write`, `edit` and `bash` are denied to a review run because with any of them the containment and read-before-write guards in `manageSkill.ts` are decorative — the agent could edit a `SKILL.md` directly and skip every check. hermes restricts its review fork the same way and for the same reason. A memory run is down to one tool because it has nothing to look up: its input is the conversation it resumed, and the current memory is already in its prompt.

### Read-before-write, and why it hangs off `read`

A review run may not patch a file it has not loaded **that run** — hermes' best idea, and the one guard against rewriting content the model only inferred from a transcript. hermes marks this in `skill_view`; pi has no such tool, because it lists each skill's location and tells the model to use `read`.

So `skillTool.ts` supplies its own `read` for review runs, delegating to pi's exported `createReadToolDefinition` and recording the path. **A custom tool named `read` replaces the built-in** — pi's registry sets built-ins first, then every custom tool by name. Two things testing settled that reading would not: pi's read **throws** on a missing file rather than returning an error result (so the recording sits after the await with no catch), and the marked set lives in the factory closure, never module scope, so two concurrent companion runs cannot see each other's reads.

### Scoping a tool to where the turn runs (`only`)

`only?: ('desktop' | 'cron' | 'telegram')[]` on a catalog entry limits it to those sources (`RunOpts.source`). **Omit it and the tool goes everywhere — that's the default and what most tools want.** Today only `open_file` is scoped (`['desktop']`): it opens a tab in the app UI, and a cron or Telegram run has no UI. `source` is part of `makeKey`, so continuing one chat from a different side reboots the session instead of reusing the other side's tool set.

**A host tool MUST also be named in `TOOL_CATALOG`.** pi filters custom tools against the allowlist exactly like builtins (`_refreshToolRegistry` in pi's `agent-session.js`), so a host tool the catalog doesn't name is dropped in silence. That is precisely what happened to `send_message`: the companion supplied it, the catalog never listed it, and the agent told the user it had no way to reach Telegram. `agent.ts` now filters `host.extraTools` by the same allowlist and `console.warn`s on any tool that doesn't survive, so the drift is visible instead of mysterious.

Custom tools are in-process (`customTools`). `list_agent_secrets`/`get_agent_secret` come from `makeAgentTokenTools(host.getAgentSecrets, host.getToken)` — built once per runtime with the host getters closed over, which is what lets the same tool code run in two hosts. `list_agent_secrets` returns **metadata only**; `get_agent_secret` calls `getToken(name)` → a usable static token or fresh OAuth access token (routed to the companion), with a guideline not to echo the credential.

**There is no `DAILY_NOTES` prompt section, and it should not come back.** It existed until 2026-08-06 and was the largest section in the prompt at 3,175 chars, most of it one person's journaling method — capture verbatim, stamp each entry with the time, append rather than replace, match the file's existing convention. **That is a house style, not app behaviour**, and putting it in the system prompt imposed it on every workspace, including the ones that never open a daily note.

What the app is actually entitled to say — resolve the right filename, don't guess one — is in `daily_note`'s own definition, and was already duplicated there: the description carries *"always use this instead of guessing a filename … a guess silently creates a second note alongside the real one"*, the trigger words ride in its first line (*"the user's daily note (journal / diary)"*), and the **result** text carries *"read it before writing, and add to it rather than replacing what is there"* — delivered at the moment it applies rather than frozen into every chat. A workspace wanting a house style for its journal states it in its own `AGENTS.md`, which pi appends to the prompt; that is the per-workspace instruction surface, and `helper.ts` is not.

`send_message` follows the same pattern from `sendMessage.ts` — one definition, the delivery injected: companion → `sendTelegramMessage` in-process, desktop → `POST /telegram/send`. **The bot token is companion-only**, which is the whole reason the desktop asks rather than sends. Both sides offer the tool, so a Telegram chat answers on Telegram no matter which side runs the turn.

## Model catalog (`modelCatalog.ts`)

Sources the Settings model dropdown from **models.dev** (`/api.json`) — fresher than pi's bundled list; pi stays the execution engine. Cache chain (10-min TTL): live fetch → memory + disk (`<userData>/model-catalog.json`) → stale memory → disk → pi's bundled `getModels()`. Concurrent callers share one in-flight fetch.

**Stale-while-revalidate — a cached copy is returned at ANY age and the refresh happens out of band.** It used to block: the TTL expiring made the *next* caller wait on a live fetch with an 8-second timeout, and on the companion that caller is a Telegram message, because session boot resolves the model through here for anything pi's bundled catalog doesn't carry (i.e. any recent model). So roughly once every ten minutes somebody paid for the refresh with their reply. Nothing about a list of model metadata is urgent enough to sit on that path. A failed background refresh backs off (`RETRY_MS`) so an offline server doesn't start a fresh 8-second fetch on every turn; only a completely cold cache blocks. The only hand-maintained bit is `DEV_KEY` (our slug → models.dev key).

`resolveModel(provider, model)` (used at boot and by `api/src/gitFixer.ts`): pi's bundled `getModel` wins; else **synthesize** a runnable pi Model from the models.dev record by cloning a sibling model's provider wiring and overlaying the metadata. `listThinkingLevels` returns `['off', ...reasoningLevels]`; `toPiThinkingLevel` translates models.dev's top tier **`max` → pi's `xhigh`** (same translation at boot, so the dropdown value is exactly what executes).

## Memory (`memoryStore.ts`, `memoryTool.ts`)

Two files at the workspace root, maintained by the agent:

| file | holds | unset ⇒ |
|---|---|---|
| `MEMORY.md` | what it has learned about working here — conventions, environment facts, what went wrong before | 2,200 chars |
| `USER.md` | who the user is — role, preferences, how they want to be worked with | 1,375 chars |

Ordinary files: committed, synced, diffable, and openable in the editor like anything else. Seeded **empty** by `ensureWorkspaceFiles` (prose in a stub would parse as the agent's first memory and ride in every prompt until something removed it), and created on first write for any workspace that predates them.

**The char cap is the mechanism, not a safety rail.** A write that would exceed it is refused with the current entries attached and an instruction to consolidate *in the same turn* — which is what keeps memory a curated page rather than a growing log. Both numbers are settings (`codingAgent.memoryCharLimit` / `userCharLimit`), read at session boot and passed through `RunOpts`; `clampLimit` refuses a zero or negative one, since a store that can hold nothing fails every write with an error the agent cannot act on.

**Where it lands in the prompt.** The rendered blocks go LAST, after every instruction section, closest to the conversation — hermes' volatile tier. They are rendered from disk once, when the chat is created, and frozen with the rest of the prompt: a chat keeps the memory it started with, and the next chat gets whatever is current. That is hermes' frozen-snapshot behaviour, and here it falls out of the prompt being written once. `PromptOpts.memory` is passed IN rather than read in `defaults/index.ts` because reading is async and the assembly stays a single pass.

**Every source can write it.** `memory` is unscoped in the catalog: "remember that I hate long replies" has to work in the chat where it was said, not up to ten messages later. The background memory pass exists because an agent forgets to save unprompted, not because saving is a background-only act — hermes makes the same split and calls the pass the safety net. The **block** goes into every run including `review`, which cannot write it: memory is knowledge about the user, and a run writing skills is better for having it. Only the how-to-save section is gated on holding the tool.

**The per-turn failure budget is real state.** Three consecutive at-capacity failures and the tool stops asking for a retry and returns a terminal result, because a fragile replace can otherwise loop a turn to exhaustion and suppress the user's reply — a failed memory side effect must never cost the answer. `Entry.resetMemoryTurn` clears it at the start of every turn; a successful write clears it too, since progress is progress.

## Skills (`skillLibrary.ts`)

Two skill kinds, both fed to pi as **explicit absolute paths at boot** (pi never auto-discovers these dirs):
- **Built-in** — bundled under `host.builtinDir`; enabled/disabled **per workspace** via `.shockwave/workspace.json` `builtinSkills` (absent key ⇒ enabled).
- **Workspace/uploaded** — user folders under `<workspace>/.shockwave/skills/<skill>/SKILL.md`; git-synced; presence ⇒ enabled.

`computeEffectivePaths` merges them keyed by lowercased folder name, so an uploaded skill **shadows** a built-in of the same name. The result is written as `skills: []` into `<dataDir>/pi-agent/settings.json` (`writePiSettings`, atomic) each boot; pi reads `skills` only at boot, so Clear-chat reloads a changed set. `SKILL.md` frontmatter (`name`/`description`/`required-secrets`) is parsed by `readSkillFolder`.

There is a **third root we do not wire**: `<workspace>/.agents/skills/`, which pi discovers by itself — its `package-manager.js` scans that path (plus `.pi/skills` and the `~` equivalents) a layer above `loadSkills`, then hands resolved absolute paths down. That is where the agent writes its own skills, and it is git-synced like everything else in the workspace.

> **Ownership is a directory here, and it needs one guard to stay that way.** The three roots are physically separate, so "may the agent write this?" is answered by the path — which is what lets `manageSkill.ts` replace hermes' 1100-line `skill_usage.py` telemetry sidecar. But **pi keeps exactly one skill per name and the `.agents` copy wins**, emitting a `name "dup" collision` diagnostic that nothing surfaces. So the agent can shadow a skill the user uploaded just by choosing its name, silently. `manage_skill`'s `create` therefore refuses a name that exists in **any** root, not only the one it writes to — comparing frontmatter names, since that is what pi keys on. Verified against pi directly.

## Workspace default files (`defaults/files.ts`)

`ensureWorkspaceFiles` seeds **six** files: `SOUL.md`, `AGENTS.md`, `MEMORY.md` and `USER.md` (both **empty** — they are the agent's memory, and prose in a stub would parse as its first entry and ride in every prompt until something removed it), `.ignore` (contains `.git/` — pi's grep runs ripgrep with a hardcoded `--hidden`, and ripgrep honors `.ignore` independently, the only lever from outside pi), and `.gitignore` (OS droppings only — deliberately NOT `.shockwave/`, which should sync). Each entry carries a `purpose` string, which is what the settings menu shows beside the name. Every write is `wx` (fail-if-exists) unless `overwrite:true`. Runs on repo creation (auto) and `workspace:ensureFiles` (manual) — never on clone/adopt or workspace switch.

**`names` narrows the write to part of the manifest**, which is how the settings UI restores one file rather than all six. It composes with `overwrite` rather than replacing it, and that pairing is load-bearing: restoring a file the workspace is *missing* passes `overwrite: false`, so if the list the menu was built from has gone stale in the seconds since it was read — the agent writes these files too — the write fails harmlessly instead of replacing a live file nobody asked about. An unknown name is ignored, not an error; the caller's list came from `DEFAULT_FILES` in the first place.