feat(frontends,conversations,telegram): the agent can hand a file to the human

A phone that slept brings back an SSE socket that never errored and never
delivers: the panel read as live for hours while showing nothing new. Every
chunk now marks the connection alive and a watchdog drops the socket after
40s of silence - twice the server's keepalive - so the loop reconnects.
Each attempt gets its own controller, which is what lets the watchdog (and
a manual refresh) end one connection without ending the loop.

The connection is admitted in one dot beside the rail's search box, tapped
to reconnect at once rather than waiting out the backoff - the pill that
used to say this was dropped in the redesign and the panel had no way to
own up to being stale.

With nothing picked, the shell lands on the freshest open master instead of
a prompt to pick something: what a phone wants when the panel opens. An
explicit pick, and following the active note, still win.

.claude/CLAUDE.md

@@ -6,9 +6,11 @@
 - **NEVER write comments** - code should be self-documenting
 
 ## Layout
-- `src/beaver_gateway` - python, unopinionated primitives (no vault paths, no agent names)
+- `src/beaver_gateway` - python, unopinionated primitives (no vault paths, no agent names, no Russian): one package per capability - `agents`, `backends`, `conversations`, `jobs`, `frontends`, `mcp`, `vault`, `security`, `events`, `storage`; `config.py` loads a setup, `app.py` builds the runtime, `cli.py` is the entrypoint
+- every string shown to a model or a user lives in a `*Texts` dataclass with English defaults (`conversations/texts.py`, `frontends/telegram/texts.py`); a setup overrides them
 - `ui` - SvelteKit SPA (admin + Obsidian panel), served by the gateway from `ui/build`
 - `docs/MISSION.md`, `docs/PRD.md`, `docs/PLAN.md`, `docs/PROGRESS.md` - keep PROGRESS.md current
+- docstrings: one line per module saying what it is for, one line per public configuration field; no section references, phases or history
 
 ## Checking commands
 After writing code, always run (or `make check`):

.env.example

@@ -28,3 +28,7 @@ RAYCAST_BEARER=
 # токен от @BotFather, свой user id - @userinfobot
 TELEGRAM_BOT_TOKEN=
 TELEGRAM_USER_ID=
+
+# Откуда тулза send_file имеет право брать файлы (через ':').
+# Папка входящих вложений разрешена всегда, её дописывает сам фронтенд.
+SEND_FILE_ROOTS=/mnt/hole/shared

.impeccable/design.json

@@ -1,54 +1,452 @@
 {
   "schemaVersion": 2,
-  "generatedAt": "2026-08-28T00:00:00Z",
+  "generatedAt": "2026-08-29T00:00:00Z",
   "title": "Design System: Beaver admin",
   "extensions": {
     "colorMeta": {
-      "primary": { "role": "primary", "displayName": "Mulberry", "canonical": "oklch(0.47 0.13 340)", "dark": "#7c3871", "tonalRamp": ["oklch(0.15 0.13 340)", "oklch(0.26 0.13 340)", "oklch(0.37 0.13 340)", "oklch(0.47 0.13 340)", "oklch(0.58 0.13 340)", "oklch(0.70 0.13 340)", "oklch(0.83 0.13 340)", "oklch(0.95 0.13 340)"] },
+      "primary": {
-      "signal": { "role": "primary", "displayName": "Orchid Signal", "canonical": "oklch(0.48 0.21 342)", "dark": "#ff82f3", "tonalRamp": ["oklch(0.15 0.21 342)", "oklch(0.26 0.21 342)", "oklch(0.37 0.21 342)", "oklch(0.48 0.21 342)", "oklch(0.60 0.21 342)", "oklch(0.72 0.21 342)", "oklch(0.84 0.21 342)", "oklch(0.95 0.21 342)"] },
+        "role": "primary",
-      "ring": { "role": "primary", "displayName": "Focus Ring", "canonical": "oklch(0.55 0.2 342)", "dark": "#ff82f3", "tonalRamp": ["oklch(0.15 0.2 342)", "oklch(0.26 0.2 342)", "oklch(0.38 0.2 342)", "oklch(0.55 0.2 342)", "oklch(0.64 0.2 342)", "oklch(0.74 0.2 342)", "oklch(0.85 0.2 342)", "oklch(0.95 0.2 342)"] },
+        "displayName": "Mulberry",
-      "status-reply": { "role": "secondary", "displayName": "Branch Blue", "canonical": "oklch(0.55 0.14 235)", "dark": "oklch(0.72 0.13 235)", "tonalRamp": ["oklch(0.15 0.14 235)", "oklch(0.26 0.14 235)", "oklch(0.40 0.14 235)", "oklch(0.55 0.14 235)", "oklch(0.65 0.14 235)", "oklch(0.75 0.14 235)", "oklch(0.85 0.14 235)", "oklch(0.95 0.14 235)"] },
+        "canonical": "oklch(0.47 0.13 340)",
-      "status-meeting": { "role": "secondary", "displayName": "Deep Violet", "canonical": "oklch(0.5 0.2 300)", "dark": "oklch(0.72 0.16 300)", "tonalRamp": ["oklch(0.15 0.2 300)", "oklch(0.26 0.2 300)", "oklch(0.38 0.2 300)", "oklch(0.50 0.2 300)", "oklch(0.62 0.2 300)", "oklch(0.74 0.2 300)", "oklch(0.85 0.2 300)", "oklch(0.95 0.2 300)"] },
+        "dark": "#7c3871",
-      "status-work": { "role": "secondary", "displayName": "Job Teal", "canonical": "oklch(0.55 0.13 195)", "dark": "oklch(0.75 0.12 195)", "tonalRamp": ["oklch(0.15 0.13 195)", "oklch(0.26 0.13 195)", "oklch(0.40 0.13 195)", "oklch(0.55 0.13 195)", "oklch(0.65 0.13 195)", "oklch(0.75 0.13 195)", "oklch(0.85 0.13 195)", "oklch(0.95 0.13 195)"] },
+        "tonalRamp": [
-      "status-skip": { "role": "secondary", "displayName": "Fork Grey", "canonical": "oklch(0.5 0.04 340)", "dark": "#a989a3", "tonalRamp": ["oklch(0.15 0.04 340)", "oklch(0.26 0.04 340)", "oklch(0.38 0.04 340)", "oklch(0.50 0.04 340)", "oklch(0.62 0.04 340)", "oklch(0.74 0.04 340)", "oklch(0.85 0.04 340)", "oklch(0.95 0.04 340)"] },
+          "oklch(0.15 0.13 340)",
-      "status-done": { "role": "tertiary", "displayName": "OK Green", "canonical": "oklch(0.55 0.14 155)", "dark": "oklch(0.74 0.14 155)", "tonalRamp": ["oklch(0.15 0.14 155)", "oklch(0.26 0.14 155)", "oklch(0.40 0.14 155)", "oklch(0.55 0.14 155)", "oklch(0.65 0.14 155)", "oklch(0.75 0.14 155)", "oklch(0.85 0.14 155)", "oklch(0.95 0.14 155)"] },
+          "oklch(0.26 0.13 340)",
-      "warn": { "role": "tertiary", "displayName": "Warn Amber", "canonical": "oklch(0.55 0.13 75)", "dark": "oklch(0.8 0.13 75)", "tonalRamp": ["oklch(0.15 0.13 75)", "oklch(0.26 0.13 75)", "oklch(0.40 0.13 75)", "oklch(0.55 0.13 75)", "oklch(0.65 0.13 75)", "oklch(0.75 0.13 75)", "oklch(0.85 0.13 75)", "oklch(0.95 0.13 75)"] },
+          "oklch(0.37 0.13 340)",
-      "note": { "role": "tertiary", "displayName": "Inject Amber", "canonical": "oklch(0.52 0.13 78)", "dark": "oklch(0.84 0.14 88)", "tonalRamp": ["oklch(0.15 0.13 78)", "oklch(0.26 0.13 78)", "oklch(0.40 0.13 78)", "oklch(0.52 0.13 78)", "oklch(0.64 0.13 78)", "oklch(0.75 0.13 78)", "oklch(0.85 0.13 78)", "oklch(0.95 0.13 78)"] },
+          "oklch(0.47 0.13 340)",
-      "destructive": { "role": "tertiary", "displayName": "Error Red", "canonical": "oklch(0.58 0.22 25)", "dark": "oklch(0.62 0.2 25)", "tonalRamp": ["oklch(0.15 0.22 25)", "oklch(0.26 0.22 25)", "oklch(0.40 0.22 25)", "oklch(0.58 0.22 25)", "oklch(0.66 0.22 25)", "oklch(0.75 0.22 25)", "oklch(0.85 0.22 25)", "oklch(0.95 0.22 25)"] },
+          "oklch(0.58 0.13 340)",
-      "background": { "role": "neutral", "displayName": "Blush Paper", "canonical": "oklch(0.99 0.004 340)", "dark": "#22111e", "tonalRamp": ["oklch(0.15 0.004 340)", "oklch(0.26 0.004 340)", "oklch(0.40 0.004 340)", "oklch(0.55 0.004 340)", "oklch(0.70 0.004 340)", "oklch(0.85 0.004 340)", "oklch(0.95 0.004 340)", "oklch(0.99 0.004 340)"] },
+          "oklch(0.70 0.13 340)",
-      "foreground": { "role": "neutral", "displayName": "Plum Ink", "canonical": "oklch(0.24 0.03 340)", "dark": "#f5f5f5", "tonalRamp": ["oklch(0.15 0.03 340)", "oklch(0.24 0.03 340)", "oklch(0.38 0.03 340)", "oklch(0.50 0.03 340)", "oklch(0.62 0.03 340)", "oklch(0.75 0.03 340)", "oklch(0.87 0.03 340)", "oklch(0.95 0.03 340)"] },
+          "oklch(0.83 0.13 340)",
-      "sidebar": { "role": "neutral", "displayName": "Sidebar Layer", "canonical": "oklch(0.975 0.01 340)", "dark": "#2c1b29", "tonalRamp": ["oklch(0.15 0.01 340)", "oklch(0.26 0.01 340)", "oklch(0.40 0.01 340)", "oklch(0.55 0.01 340)", "oklch(0.70 0.01 340)", "oklch(0.85 0.01 340)", "oklch(0.94 0.01 340)", "oklch(0.975 0.01 340)"] },
+          "oklch(0.95 0.13 340)"
-      "sidebar-accent": { "role": "neutral", "displayName": "Sidebar Accent", "canonical": "oklch(0.94 0.016 340)", "dark": "#341d2f", "tonalRamp": ["oklch(0.15 0.016 340)", "oklch(0.26 0.016 340)", "oklch(0.40 0.016 340)", "oklch(0.55 0.016 340)", "oklch(0.70 0.016 340)", "oklch(0.85 0.016 340)", "oklch(0.94 0.016 340)", "oklch(0.98 0.016 340)"] },
+        ]
-      "muted": { "role": "neutral", "displayName": "Muted", "canonical": "oklch(0.96 0.012 340)", "dark": "#40283a", "tonalRamp": ["oklch(0.15 0.012 340)", "oklch(0.26 0.012 340)", "oklch(0.40 0.012 340)", "oklch(0.55 0.012 340)", "oklch(0.70 0.012 340)", "oklch(0.85 0.012 340)", "oklch(0.96 0.012 340)", "oklch(0.99 0.012 340)"] },
+      },
-      "muted-foreground": { "role": "neutral", "displayName": "Muted Ink", "canonical": "oklch(0.5 0.04 340)", "dark": "#a989a3", "tonalRamp": ["oklch(0.15 0.04 340)", "oklch(0.26 0.04 340)", "oklch(0.38 0.04 340)", "oklch(0.50 0.04 340)", "oklch(0.62 0.04 340)", "oklch(0.74 0.04 340)", "oklch(0.85 0.04 340)", "oklch(0.95 0.04 340)"] },
+      "signal": {
-      "icon": { "role": "neutral", "displayName": "Icon", "canonical": "oklch(0.55 0.03 340)", "dark": "#877384", "tonalRamp": ["oklch(0.15 0.03 340)", "oklch(0.26 0.03 340)", "oklch(0.40 0.03 340)", "oklch(0.55 0.03 340)", "oklch(0.65 0.03 340)", "oklch(0.75 0.03 340)", "oklch(0.85 0.03 340)", "oklch(0.95 0.03 340)"] },
+        "role": "primary",
-      "border": { "role": "neutral", "displayName": "Hairline", "canonical": "oklch(0.9 0.02 340)", "dark": "oklch(0.92 0.04 340 / 10%)", "tonalRamp": ["oklch(0.15 0.02 340)", "oklch(0.26 0.02 340)", "oklch(0.40 0.02 340)", "oklch(0.55 0.02 340)", "oklch(0.70 0.02 340)", "oklch(0.80 0.02 340)", "oklch(0.90 0.02 340)", "oklch(0.97 0.02 340)"] }
+        "displayName": "Orchid Signal",
+        "canonical": "oklch(0.48 0.21 342)",
+        "dark": "#ff82f3",
+        "tonalRamp": [
+          "oklch(0.15 0.21 342)",
+          "oklch(0.26 0.21 342)",
+          "oklch(0.37 0.21 342)",
+          "oklch(0.48 0.21 342)",
+          "oklch(0.60 0.21 342)",
+          "oklch(0.72 0.21 342)",
+          "oklch(0.84 0.21 342)",
+          "oklch(0.95 0.21 342)"
+        ]
+      },
+      "ring": {
+        "role": "primary",
+        "displayName": "Focus Ring",
+        "canonical": "oklch(0.55 0.2 342)",
+        "dark": "#ff82f3",
+        "tonalRamp": [
+          "oklch(0.15 0.2 342)",
+          "oklch(0.26 0.2 342)",
+          "oklch(0.38 0.2 342)",
+          "oklch(0.55 0.2 342)",
+          "oklch(0.64 0.2 342)",
+          "oklch(0.74 0.2 342)",
+          "oklch(0.85 0.2 342)",
+          "oklch(0.95 0.2 342)"
+        ]
+      },
+      "status-reply": {
+        "role": "secondary",
+        "displayName": "Branch Blue",
+        "canonical": "oklch(0.55 0.14 235)",
+        "dark": "oklch(0.72 0.13 235)",
+        "tonalRamp": [
+          "oklch(0.15 0.14 235)",
+          "oklch(0.26 0.14 235)",
+          "oklch(0.40 0.14 235)",
+          "oklch(0.55 0.14 235)",
+          "oklch(0.65 0.14 235)",
+          "oklch(0.75 0.14 235)",
+          "oklch(0.85 0.14 235)",
+          "oklch(0.95 0.14 235)"
+        ]
+      },
+      "status-meeting": {
+        "role": "secondary",
+        "displayName": "Deep Violet",
+        "canonical": "oklch(0.5 0.2 300)",
+        "dark": "oklch(0.72 0.16 300)",
+        "tonalRamp": [
+          "oklch(0.15 0.2 300)",
+          "oklch(0.26 0.2 300)",
+          "oklch(0.38 0.2 300)",
+          "oklch(0.50 0.2 300)",
+          "oklch(0.62 0.2 300)",
+          "oklch(0.74 0.2 300)",
+          "oklch(0.85 0.2 300)",
+          "oklch(0.95 0.2 300)"
+        ]
+      },
+      "status-work": {
+        "role": "secondary",
+        "displayName": "Job Teal",
+        "canonical": "oklch(0.55 0.13 195)",
+        "dark": "oklch(0.75 0.12 195)",
+        "tonalRamp": [
+          "oklch(0.15 0.13 195)",
+          "oklch(0.26 0.13 195)",
+          "oklch(0.40 0.13 195)",
+          "oklch(0.55 0.13 195)",
+          "oklch(0.65 0.13 195)",
+          "oklch(0.75 0.13 195)",
+          "oklch(0.85 0.13 195)",
+          "oklch(0.95 0.13 195)"
+        ]
+      },
+      "status-skip": {
+        "role": "secondary",
+        "displayName": "Fork Grey",
+        "canonical": "oklch(0.5 0.04 340)",
+        "dark": "#a989a3",
+        "tonalRamp": [
+          "oklch(0.15 0.04 340)",
+          "oklch(0.26 0.04 340)",
+          "oklch(0.38 0.04 340)",
+          "oklch(0.50 0.04 340)",
+          "oklch(0.62 0.04 340)",
+          "oklch(0.74 0.04 340)",
+          "oklch(0.85 0.04 340)",
+          "oklch(0.95 0.04 340)"
+        ]
+      },
+      "status-done": {
+        "role": "tertiary",
+        "displayName": "OK Green",
+        "canonical": "oklch(0.55 0.14 155)",
+        "dark": "oklch(0.74 0.14 155)",
+        "tonalRamp": [
+          "oklch(0.15 0.14 155)",
+          "oklch(0.26 0.14 155)",
+          "oklch(0.40 0.14 155)",
+          "oklch(0.55 0.14 155)",
+          "oklch(0.65 0.14 155)",
+          "oklch(0.75 0.14 155)",
+          "oklch(0.85 0.14 155)",
+          "oklch(0.95 0.14 155)"
+        ]
+      },
+      "warn": {
+        "role": "tertiary",
+        "displayName": "Warn Amber",
+        "canonical": "oklch(0.55 0.13 75)",
+        "dark": "oklch(0.8 0.13 75)",
+        "tonalRamp": [
+          "oklch(0.15 0.13 75)",
+          "oklch(0.26 0.13 75)",
+          "oklch(0.40 0.13 75)",
+          "oklch(0.55 0.13 75)",
+          "oklch(0.65 0.13 75)",
+          "oklch(0.75 0.13 75)",
+          "oklch(0.85 0.13 75)",
+          "oklch(0.95 0.13 75)"
+        ]
+      },
+      "note": {
+        "role": "tertiary",
+        "displayName": "Inject Amber",
+        "canonical": "oklch(0.52 0.13 78)",
+        "dark": "oklch(0.84 0.14 88)",
+        "tonalRamp": [
+          "oklch(0.15 0.13 78)",
+          "oklch(0.26 0.13 78)",
+          "oklch(0.40 0.13 78)",
+          "oklch(0.52 0.13 78)",
+          "oklch(0.64 0.13 78)",
+          "oklch(0.75 0.13 78)",
+          "oklch(0.85 0.13 78)",
+          "oklch(0.95 0.13 78)"
+        ]
+      },
+      "destructive": {
+        "role": "tertiary",
+        "displayName": "Error Red",
+        "canonical": "oklch(0.58 0.22 25)",
+        "dark": "oklch(0.62 0.2 25)",
+        "tonalRamp": [
+          "oklch(0.15 0.22 25)",
+          "oklch(0.26 0.22 25)",
+          "oklch(0.40 0.22 25)",
+          "oklch(0.58 0.22 25)",
+          "oklch(0.66 0.22 25)",
+          "oklch(0.75 0.22 25)",
+          "oklch(0.85 0.22 25)",
+          "oklch(0.95 0.22 25)"
+        ]
+      },
+      "background": {
+        "role": "neutral",
+        "displayName": "Blush Paper",
+        "canonical": "oklch(0.99 0.004 340)",
+        "dark": "#22111e",
+        "tonalRamp": [
+          "oklch(0.15 0.004 340)",
+          "oklch(0.26 0.004 340)",
+          "oklch(0.40 0.004 340)",
+          "oklch(0.55 0.004 340)",
+          "oklch(0.70 0.004 340)",
+          "oklch(0.85 0.004 340)",
+          "oklch(0.95 0.004 340)",
+          "oklch(0.99 0.004 340)"
+        ]
+      },
+      "foreground": {
+        "role": "neutral",
+        "displayName": "Plum Ink",
+        "canonical": "oklch(0.24 0.03 340)",
+        "dark": "#f5f5f5",
+        "tonalRamp": [
+          "oklch(0.15 0.03 340)",
+          "oklch(0.24 0.03 340)",
+          "oklch(0.38 0.03 340)",
+          "oklch(0.50 0.03 340)",
+          "oklch(0.62 0.03 340)",
+          "oklch(0.75 0.03 340)",
+          "oklch(0.87 0.03 340)",
+          "oklch(0.95 0.03 340)"
+        ]
+      },
+      "sidebar": {
+        "role": "neutral",
+        "displayName": "Sidebar Layer",
+        "canonical": "oklch(0.975 0.01 340)",
+        "dark": "#2c1b29",
+        "tonalRamp": [
+          "oklch(0.15 0.01 340)",
+          "oklch(0.26 0.01 340)",
+          "oklch(0.40 0.01 340)",
+          "oklch(0.55 0.01 340)",
+          "oklch(0.70 0.01 340)",
+          "oklch(0.85 0.01 340)",
+          "oklch(0.94 0.01 340)",
+          "oklch(0.975 0.01 340)"
+        ]
+      },
+      "sidebar-accent": {
+        "role": "neutral",
+        "displayName": "Sidebar Accent",
+        "canonical": "oklch(0.94 0.016 340)",
+        "dark": "#341d2f",
+        "tonalRamp": [
+          "oklch(0.15 0.016 340)",
+          "oklch(0.26 0.016 340)",
+          "oklch(0.40 0.016 340)",
+          "oklch(0.55 0.016 340)",
+          "oklch(0.70 0.016 340)",
+          "oklch(0.85 0.016 340)",
+          "oklch(0.94 0.016 340)",
+          "oklch(0.98 0.016 340)"
+        ]
+      },
+      "muted": {
+        "role": "neutral",
+        "displayName": "Muted",
+        "canonical": "oklch(0.96 0.012 340)",
+        "dark": "#40283a",
+        "tonalRamp": [
+          "oklch(0.15 0.012 340)",
+          "oklch(0.26 0.012 340)",
+          "oklch(0.40 0.012 340)",
+          "oklch(0.55 0.012 340)",
+          "oklch(0.70 0.012 340)",
+          "oklch(0.85 0.012 340)",
+          "oklch(0.96 0.012 340)",
+          "oklch(0.99 0.012 340)"
+        ]
+      },
+      "muted-foreground": {
+        "role": "neutral",
+        "displayName": "Muted Ink",
+        "canonical": "oklch(0.5 0.04 340)",
+        "dark": "#a989a3",
+        "tonalRamp": [
+          "oklch(0.15 0.04 340)",
+          "oklch(0.26 0.04 340)",
+          "oklch(0.38 0.04 340)",
+          "oklch(0.50 0.04 340)",
+          "oklch(0.62 0.04 340)",
+          "oklch(0.74 0.04 340)",
+          "oklch(0.85 0.04 340)",
+          "oklch(0.95 0.04 340)"
+        ]
+      },
+      "icon": {
+        "role": "neutral",
+        "displayName": "Icon",
+        "canonical": "oklch(0.55 0.03 340)",
+        "dark": "#877384",
+        "tonalRamp": [
+          "oklch(0.15 0.03 340)",
+          "oklch(0.26 0.03 340)",
+          "oklch(0.40 0.03 340)",
+          "oklch(0.55 0.03 340)",
+          "oklch(0.65 0.03 340)",
+          "oklch(0.75 0.03 340)",
+          "oklch(0.85 0.03 340)",
+          "oklch(0.95 0.03 340)"
+        ]
+      },
+      "border": {
+        "role": "neutral",
+        "displayName": "Hairline",
+        "canonical": "oklch(0.9 0.02 340)",
+        "dark": "oklch(0.92 0.04 340 / 10%)",
+        "tonalRamp": [
+          "oklch(0.15 0.02 340)",
+          "oklch(0.26 0.02 340)",
+          "oklch(0.40 0.02 340)",
+          "oklch(0.55 0.02 340)",
+          "oklch(0.70 0.02 340)",
+          "oklch(0.80 0.02 340)",
+          "oklch(0.90 0.02 340)",
+          "oklch(0.97 0.02 340)"
+        ]
+      }
     },
     "typographyMeta": {
-      "headline": { "displayName": "Headline", "purpose": "Page titles in page-header.svelte; the sidebar wordmark shares weight and tracking." },
+      "headline": {
-      "title": { "displayName": "Title", "purpose": "Thread title, stat values (tabular), memory file path." },
+        "displayName": "Headline",
-      "body": { "displayName": "Body", "purpose": "Rows, cells, bubbles, dialogs; primary row text at 500." },
+        "purpose": "Page titles in page-header.svelte; the sidebar wordmark shares weight and tracking."
-      "label": { "displayName": "Label", "purpose": "Uppercase section headings; same size without uppercase for table headers, badges, pills, meta lines." },
+      },
-      "mono": { "displayName": "Mono", "purpose": "Raw JSON, tool input/result blocks, event tape, ids, the plaintext token." }
+      "title": {
+        "displayName": "Title",
+        "purpose": "Thread title, stat values (tabular), memory file path."
+      },
+      "body": {
+        "displayName": "Body",
+        "purpose": "Rows, cells, bubbles, dialogs; primary row text at 500."
+      },
+      "label": {
+        "displayName": "Label",
+        "purpose": "Uppercase section headings; same size without uppercase for table headers, badges, pills, meta lines."
+      },
+      "mono": {
+        "displayName": "Mono",
+        "purpose": "Raw JSON, tool input/result blocks, event tape, ids, the plaintext token."
+      }
     },
     "shadows": [
-      { "name": "login-lift", "value": "0 8px 24px -12px rgb(0 0 0 / 0.25)", "purpose": "The sign-in card only (routes/login/+page.svelte). The single application-layer shadow." },
+      {
-      { "name": "popover", "value": "shadow-xl plus ring-1 ring-foreground/5 (10% dark)", "purpose": "Luma dialogs, sheets, menus, selects. Overlay surfaces only." }
+        "name": "login-lift",
+        "value": "0 8px 24px -12px rgb(0 0 0 / 0.25)",
+        "purpose": "The sign-in card only (routes/login/+page.svelte). The single application-layer shadow."
+      },
+      {
+        "name": "popover",
+        "value": "shadow-xl plus ring-1 ring-foreground/5 (10% dark)",
+        "purpose": "Luma dialogs, sheets, menus, selects. Overlay surfaces only."
+      }
     ],
     "motion": [
-      { "name": "pulse-dot", "value": "pulse-dot 1.6s cubic-bezier(0.4, 0, 0.6, 1) infinite", "purpose": "Signal-colored halo (0 to 5px, 55% to 0% alpha) on live and running dots." },
+      {
-      { "name": "rise", "value": "rise 220ms cubic-bezier(0.16, 1, 0.3, 1) both", "purpose": "Opacity 0 to 1 and translateY 3px to 0 when a turn card lands in the activity feed." },
+        "name": "pulse-dot",
-      { "name": "row-hover", "value": "background-color 150ms ease-out", "purpose": "Ink wash at 4% on interactive rows." },
+        "value": "pulse-dot 1.6s cubic-bezier(0.4, 0, 0.6, 1) infinite",
-      { "name": "chevron", "value": "transform 150ms", "purpose": "90 degree rotation of expand chevrons in tool nodes, raw entries, memory tree." },
+        "purpose": "Signal-colored halo (0 to 5px, 55% to 0% alpha) on live and running dots."
-      { "name": "bar-fill", "value": "width 300ms", "purpose": "Utilization bar fill in limit-bar.svelte." },
+      },
-      { "name": "dialog", "value": "fade-in and zoom-in-95 over 100ms", "purpose": "Luma dialog open and close." },
+      {
-      { "name": "reduced-motion", "value": "transition-duration and animation-duration 0.01ms under prefers-reduced-motion", "purpose": "Global kill switch in layout.css." }
+        "name": "rise",
+        "value": "rise 220ms cubic-bezier(0.16, 1, 0.3, 1) both",
+        "purpose": "Opacity 0 to 1 and translateY 3px to 0 when a turn card lands in the activity feed."
+      },
+      {
+        "name": "row-hover",
+        "value": "background-color 150ms ease-out",
+        "purpose": "Ink wash at 4% on interactive rows."
+      },
+      {
+        "name": "chevron",
+        "value": "transform 150ms",
+        "purpose": "90 degree rotation of expand chevrons in tool nodes, raw entries, memory tree."
+      },
+      {
+        "name": "bar-fill",
+        "value": "width 300ms",
+        "purpose": "Utilization bar fill in limit-bar.svelte."
+      },
+      {
+        "name": "dialog",
+        "value": "fade-in and zoom-in-95 over 100ms",
+        "purpose": "Luma dialog open and close."
+      },
+      {
+        "name": "reduced-motion",
+        "value": "transition-duration and animation-duration 0.01ms under prefers-reduced-motion",
+        "purpose": "Global kill switch in layout.css."
+      }
     ],
     "breakpoints": [
-      { "name": "sm", "value": "640px", "purpose": "Sidebar replaces bottom nav; header padding 24px; hidden row columns return." },
+      {
-      { "name": "md", "value": "768px", "purpose": "Memory tree and file split side by side." },
+        "name": "sm",
-      { "name": "lg", "value": "1024px", "purpose": "Thread meta rail (18rem) and two-column dashboard sections." }
+        "value": "640px",
-    ]
+        "purpose": "Sidebar replaces bottom nav; header padding 24px; hidden row columns return."
+      },
+      {
+        "name": "md",
+        "value": "768px",
+        "purpose": "Memory tree and file split side by side."
+      },
+      {
+        "name": "lg",
+        "value": "1024px",
+        "purpose": "Thread meta rail (18rem) and two-column dashboard sections."
+      },
+      {
+        "name": "panel-rail",
+        "value": "768px",
+        "purpose": "Panel container width, not viewport: below it the switcher bar names the thread, from it the 18rem conversation rail shows."
+      }
+    ],
+    "obsidian": {
+      "root": ".beaver-root",
+      "source": "beaver-plugin-obsidian/src/tailwind.css",
+      "aliases": {
+        "background": "--background-primary",
+        "card": "--background-primary-alt",
+        "popover": "--background-secondary",
+        "sidebar": "--background-secondary",
+        "foreground": "--text-normal",
+        "muted-foreground": "--text-muted",
+        "icon": "--text-muted",
+        "status-skip": "--text-faint",
+        "border": "--background-modifier-border",
+        "input": "--background-modifier-border",
+        "muted": "--background-modifier-hover",
+        "secondary": "--background-modifier-hover",
+        "accent": "--background-modifier-hover",
+        "sidebar-accent": "--background-modifier-hover",
+        "primary": "--color-accent",
+        "signal": "--color-accent",
+        "ring": "--color-accent",
+        "status-new": "--color-accent",
+        "primary-foreground": "--text-on-accent",
+        "link": "--link-color, --text-accent",
+        "destructive": "--text-error",
+        "font-sans": "--font-interface",
+        "font-mono": "--font-monospace"
+      },
+      "radii": {
+        "button, select-trigger": "--button-radius",
+        "input, tabs-trigger, menu items": "--input-radius",
+        "tabs-list, skeleton, dialog, popover, menus": "--radius-m (8px)",
+        "rows and notes": "--radius 0.45rem"
+      },
+      "overlays": {
+        "border": "1px var(--border)",
+        "shadow": "var(--shadow-s)",
+        "menuBackground": "var(--popover), opaque, no backdrop",
+        "portal": ".beaver-root.beaver-portal on body at --layer-menu (65)"
+      },
+      "tabs": {
+        "list": "color-mix(in oklab, var(--text-normal) 6%, transparent)",
+        "active": "color-mix(in oklab, var(--text-normal) 14%, transparent)"
+      }
+    }
   },
   "components": [
     {
@@ -153,12 +551,51 @@
       "Light and dark modes, both tinted toward hue 340; dark borders are 10% alpha overlays"
     ],
     "rules": [
-      { "name": "The Pink Ration Rule", "body": "signal marks live state (pulsing dots, running rows, busy sessions, the running count) and selection (active mobile nav, master kind). It never decorates a heading, a button, or a static surface. Hover is a 4% ink wash, not pink.", "section": "colors" },
+      {
-      { "name": "The Twelve Percent Rule", "body": "Every colored chip is its hue at 12% alpha behind full-strength text of the same hue (kind-badge.svelte, sidebar running count). Solid colored chips do not exist.", "section": "colors" },
+        "name": "The Pink Ration Rule",
-      { "name": "The Two Layers Rule", "body": "Navigation and rails sit on sidebar (or sidebar/50); content sits on background. There is no third surface color; depth beyond that is a hairline.", "section": "colors" },
+        "body": "signal marks live state (pulsing dots, running rows, busy sessions, the running count) and selection (active mobile nav, master kind). It never decorates a heading, a button, or a static surface. Hover is a 4% ink wash, not pink.",
-      { "name": "The Tabular Rule", "body": "Every number - durations, token counts, money, percentages, timestamps, ids, byte sizes - carries the tabular utility (font-variant-numeric: tabular-nums, layout.css). Numeric table columns are right-aligned.", "section": "typography" },
+        "section": "colors"
-      { "name": "The One Heading Rule", "body": "A page has one headline (the header) and any number of uppercase 12px section labels; there is no intermediate heading size. Section labels are h2 elements, not decorative kickers.", "section": "typography" },
+      },
-      { "name": "The Flat Ledger Rule", "body": "Nothing inside the main column casts a shadow. Overlays (dialog, sheet, menu) and the login card are the only lifted surfaces.", "section": "elevation" }
+      {
+        "name": "The Twelve Percent Rule",
+        "body": "Every colored chip is its hue at 12% alpha behind full-strength text of the same hue (kind-badge.svelte, sidebar running count). Solid colored chips do not exist.",
+        "section": "colors"
+      },
+      {
+        "name": "The Two Layers Rule",
+        "body": "Navigation and rails sit on sidebar (or sidebar/50); content sits on background. There is no third surface color; depth beyond that is a hairline.",
+        "section": "colors"
+      },
+      {
+        "name": "The Tabular Rule",
+        "body": "Every number - durations, token counts, money, percentages, timestamps, ids, byte sizes - carries the tabular utility (font-variant-numeric: tabular-nums, layout.css). Numeric table columns are right-aligned.",
+        "section": "typography"
+      },
+      {
+        "name": "The One Heading Rule",
+        "body": "A page has one headline (the header) and any number of uppercase 12px section labels; there is no intermediate heading size. Section labels are h2 elements, not decorative kickers.",
+        "section": "typography"
+      },
+      {
+        "name": "The Flat Ledger Rule",
+        "body": "Nothing inside the main column casts a shadow. Overlays (dialog, sheet, menu) and the login card are the only lifted surfaces.",
+        "section": "elevation"
+      },
+      {
+        "name": "The Host Accent Rule",
+        "body": "Inside Obsidian signal and primary are one variable. Live dots, running rows, the running count, the selected row, the primary button and the focus ring all take the user's accent; the Pink Ration Rule becomes an accent ration with the same two meanings, live and selected.",
+        "section": "obsidian"
+      },
+      {
+        "name": "The Borrowed Corner Rule",
+        "body": "No control chooses its own radius. Rows and notes use --radius; luma primitives are re-rounded to Obsidian's --button-radius, --input-radius and --radius-m so the panel sits beside the app's own settings and menus without a seam.",
+        "section": "obsidian"
+      },
+      {
+        "name": "The Alias Only Rule",
+        "body": "Panel components use token aliases (bg-primary/5, text-link, border-b) and the panel.css utilities. A literal colour, font or radius in ui/src/lib/panel/ breaks the Obsidian mapping.",
+        "section": "obsidian"
+      }
     ],
     "dos": [
       "Do build lists as ledger-grid rows with border-b and a per-row column template; use a native table when there are more than four numeric columns.",
@@ -170,7 +607,10 @@
       "Do put secondary surfaces (rails, trees) on bg-sidebar/50 with a hairline, not on a card.",
       "Do show every error as error-note.svelte with a retry and every empty list as empty-state.svelte with a one-line hint.",
       "Do respect prefers-reduced-motion; new motion must be a CSS transition or one of animate-pulse-dot and animate-rise.",
-      "Do keep the luma primitives as shipped; compose them with size=\"sm\" and variant=\"outline\" or \"ghost\" for in-page actions."
+      "Do keep the luma primitives as shipped; compose them with size=\"sm\" and variant=\"outline\" or \"ghost\" for in-page actions.",
+      "Do write panel components (ui/src/lib/panel/) against token aliases and panel.css utilities only, and check them in both the admin and the plugin.",
+      "Do decide panel layout from the panel's own width (@container, bind:clientWidth); 768px is where the rail replaces the switcher.",
+      "Do add conversation actions to actions.svelte.ts so the header menu and the row menu stay one list."
     ],
     "donts": [
       "Don't put a card inside a card, or wrap ledger rows in a bordered container.",
@@ -179,7 +619,10 @@
       "Don't introduce a heading size between the page headline (1rem) and the section label (0.75rem uppercase).",
       "Don't render solid colored chips; chips are hue/12 behind hue text.",
       "Don't use hue-chip, hairline, touch-shown or scrollbar-none from layout.css as if they were system rules - they are defined and currently unused by the admin.",
-      "Don't apply this palette inside Obsidian; the panel takes Obsidian's variables (PRODUCT.md brand commitment)."
+      "Don't apply this palette inside Obsidian; the panel takes Obsidian's variables (PRODUCT.md brand commitment).",
+      "Don't expect pills inside Obsidian; every radius there is the host's (--button-radius, --input-radius, --radius-m).",
+      "Don't mark an active tab with bg-background in panel code; the plugin overrides it to ink at 14%.",
+      "Don't let a menu or dialog render inside the sidedock; overlays mount in .beaver-root.beaver-portal at --layer-menu."
     ]
   }
 }

.impeccable/surfaces/beaver-gateway-ui-src-lib-panel.md

@@ -0,0 +1,13 @@
+---
+version: 1
+slug: "beaver-gateway-ui-src-lib-panel"
+primary_target: "beaver-gateway/ui/src/lib/panel"
+related_targets: ["beaver-gateway/ui/src/routes/panel","beaver-plugin-obsidian/src/ui"]
+---
+
+Scope: the Beaver panel as an Obsidian view (sidedock column, tab, mobile) and its browser twin at /admin/panel. Mode: Operate.
+Audience and job: the operator (Kit) watching and steering the agent next to their notes; the task is to see what runs, answer, branch, send a branch back to Telegram, close a deep chat.
+Constraints: shared components in ui/src/lib/panel, bundled into the plugin by esbuild ($lib alias, one Svelte runtime, svelte-sonner shimmed to Notice); container queries, never viewport breakpoints, because the same tree lives in a 300px column and a 1400px tab; Obsidian's variables only through .beaver-root (beaver-calendar is the reference); nothing pink inside Obsidian.
+Direction: the agent's terminal, thread always on screen; below 48rem the switcher popover in the header, above it the grouped rail (master, branches, deep chats, jobs) on the left; one action list (actions.svelte.ts) behind the header menu and the row context menu; markdown through Obsidian's renderer with [[links]] opening notes.
+Memorable moment: the panel follows the note you open and the running turn's tool tree grows in place.
+Unresolved: a "new conversation" affordance in the panel; keyboard navigation beyond ↑/↓ and /; the pinned one-line summary when a branch returns to Telegram (§8.2) is not produced by the gateway yet.

Makefile

@@ -25,7 +25,7 @@ ui-build:
 	cd ui && bun run build
 
 db:
-	docker compose --project-directory ../beaver-agent --profile db up -d postgres
+	docker compose -f ../beaver-agent/docker-compose.yml --project-directory ../beaver-agent --profile db up -d postgres
 
 db-down:
-	docker compose --project-directory ../beaver-agent --profile db down
+	docker compose -f ../beaver-agent/docker-compose.yml --project-directory ../beaver-agent --profile db down

README.md

@@ -1,2 +1,74 @@
-# Beaver Gateway
+# beaver-gateway
-[![AI Slop Inside](https://sladge.net/badge.svg)](https://sladge.net)
+
+A gateway for personal agents built on the Claude Agent SDK: conversations
+with a lifecycle, windows to talk through, jobs, memory hooks, and a policy
+boundary - without an opinion about what the agent is for. A setup is one
+`config.py` (or a package next to it) that assembles a `Gateway`; this repo
+holds the primitives, [beaver-agent](https://git.kotikot.com/beaver/beaver-agent)
+is a full setup built on them.
+
+![The admin: what is in motion, what waits for an answer, the context and the quotas, the graph around the master](preview/shots/admin-now.webp)
+
+## What it gives a setup
+
+- **agents/** - what an agent is: a Claude agent with a prompt per
+  conversation kind, skill sets per kind, gateway tools, a `PreToolUse`
+  policy; a Raycast agent for cheap fast answers.
+- **backends/** - how a turn runs: the Claude Agent SDK subprocess with a
+  session pool, transcripts and session stores; the Raycast wire.
+- **conversations/** - the model of a conversation: kinds (master, branch,
+  deep, job, fork), rows and windows, the inject queue with priorities,
+  seeds, turns, questions, closing through a distiller, master rotation,
+  the envelope, the in-process gateway tools.
+- **jobs/** - cron, webhook and event jobs on pgqueuer, deferred injects,
+  the subscription budget.
+- **frontends/** - the windows: Telegram (master = General, topic = branch,
+  files out of the agent through `send_file`),
+  markdown files in a vault, `/api` + the admin SPA, an Anthropic-compatible
+  `/anthropic/v1/messages`, MCP re-exposure at `/mcp/<name>`, and
+  `WebhookFrontend` for a window a setup declares itself - its own request
+  and response schema, its own agent, its own token scope
+  (`docs/FRONTEND-PLUGINS.md`).
+- **mcp/** - MCP servers a setup declares (stdio, http, python tools),
+  aggregated in-process and handed to agents by name.
+- **vault/** - watching a directory of notes for the envelope.
+- **security/** - bearer tokens, the audit log, credential redaction.
+- **events/** - the in-process bus every frontend taps, and the stream
+  event protocol backends emit.
+- **storage/** - SQLModel tables and the Postgres session store.
+
+`config.py` defines `Gateway` and loads a setup; `app.py` builds the runtime
+from it; `cli.py` is the entrypoint. The admin SPA in `ui/` is the browser
+window on all of it: conversations by day, the thread with the tree of tool
+calls, the context of the last turn, memory, jobs, usage, tokens and the audit.
+
+![A conversation in the admin: the thread, the queue, the details](preview/shots/admin-thread.webp)
+
+![The Context tab: what the model held on the last turn - harness, prompt granules, skills, the notes the thread reached](preview/shots/admin-context.webp) Every string the gateway puts in front of
+a model or a user has an English default and is overridable
+(`ConversationTexts`, `TelegramTexts`).
+
+## Run
+
+```sh
+cd examples
+CLAUDE_CODE_OAUTH_TOKEN=$(claude setup-token) docker compose up --build
+```
+
+`examples/config.py` is the smallest setup that starts: one agent, one
+python tool, one cron job, the built-in frontends on port 8000; the compose
+file next to it adds Postgres. Without Docker: `uv sync`, build the SPA with
+`cd ui && bun install && bun run build`, then run `uv run beaver-gateway` with
+`DATABASE_URL` and `CONFIG_PATH` set. A setup's own secrets come from `.env`
+next to its config (`load_dotenv` runs before the config is executed).
+
+## Develop
+
+```sh
+make check   # ruff format --check, ruff check, ty, pytest
+make fix
+```
+
+No comments in code: modules carry a one-line docstring saying what they are
+for, public configuration fields carry a one-line docstring saying what they
+mean; everything else is the code.

examples/config.py

@@ -1,219 +1,64 @@
-# Sample user config — grows alongside the implementation phases.
+"""The smallest setup: one agent, one tool, one job, the built-in frontends.
-#
+
-# Loader (beaver_gateway/config_loader.py) execs this file with
+The loader execs this file with ``ClaudeAgent``, ``RaycastAgent``,
-# ClaudeAgent, RaycastAgent, McpServer, ExposedMcp, Gateway already
+``McpServer``, ``ExposedMcp`` and ``Gateway`` already bound; the imports
-# bound — so importing them is optional. We import explicitly here so
+below are for type checkers. A real setup grows into a package next to
-# IDEs and type-checkers see real symbols instead of free variables.
+this file (see beaver-agent).
+"""
+
+import logging
 import tempfile
-from datetime import date
+from datetime import UTC, datetime
 from pathlib import Path
 
 from beaver_gateway.agents.base import ExposedMcp
-from beaver_gateway.agents.claude import ClaudeAgent
+from beaver_gateway.agents.claude import ClaudeAgent, Prompts
-from beaver_gateway.agents.raycast import RaycastAgent, RemoteTool, UserPreferences
+from beaver_gateway.config import Gateway
-from beaver_gateway.core.registry import Gateway
-from beaver_gateway.core.turn_record import slugify
 from beaver_gateway.frontends.admin import AdminFrontend
 from beaver_gateway.frontends.anthropic import AnthropicMessagesFrontend
+from beaver_gateway.frontends.api import ApiFrontend
 from beaver_gateway.frontends.markdown import MarkdownFrontend
 from beaver_gateway.frontends.mcp_server import McpServerFrontend
+from beaver_gateway.jobs.scheduler import Job, JobRun
 from beaver_gateway.mcp.types import McpServer
 
+log = logging.getLogger("example")
 
-def chat_path(title: str, agent: str, vault: Path) -> Path:  # noqa: ARG001
+VAULT = Path(tempfile.mkdtemp(prefix="beaver-vault-")).resolve()
-    """Where a new chat file lands in the vault.
+PROMPT = VAULT / "assistant.md"
-
+PROMPT.write_text(
-    Called by ``MarkdownFrontend`` for every conversation that needs a
+    "You are a concise assistant. When asked the time, call `current_time`.\n"
-    file: a ``deep`` chat spawned by the dispatcher, a ``/v1/messages``
+)
-    chat (``title`` = first user message), or with ``log_all_chats=True``
-    the archive of a stateless agent's turns. Return value can be
-    absolute or relative; relative paths are anchored under ``vault``.
-
-    Layout below: ``<vault>/<YYYY-MM>/<YYYY-MM-DD>_<topic>.md``.
-    """
-    today = date.today()
-    return vault / f"{today:%Y-%m}" / f"{today:%Y-%m-%d}_{slugify(title, maxlen=40)}.md"
 
 
 def current_time() -> str:
-    """Return the current local time as an ISO-8601 string.
+    return datetime.now(UTC).astimezone().isoformat()
 
-    Trivial demo tool for the Phase 2.1 internal MCP aggregator —
-    confirms a ``python_tool`` namespace is reachable on
-    ``http://127.0.0.1:<INTERNAL_MCP_PORT>/mcp/time``.
-    """
-    from datetime import datetime
 
-    return datetime.now().astimezone().isoformat()
+async def heartbeat(run: JobRun) -> None:
+    master = await run.master()
+    log.info("heartbeat: master=%s", master.external_id if master else None)
 
 
 gateway = Gateway(
     agents=[
-        # Phase 2.2 — ClaudeCodeBackendAdapter routes this agent's
-        # ``/v1/messages`` calls through ``claude-code-api``. The
-        # ``time`` MCP gets exposed as ``mcp__time__current_time`` to
-        # the subscription claude session via
-        # ``BackendOptions.mcp_servers`` pointing at the internal
-        # aggregator on ``127.0.0.1:INTERNAL_MCP_PORT/mcp/time/``.
-        #
-        # Fresh empty tempdir (not a hardcoded ``/tmp``) for two
-        # reasons: claude-code-api derives the JSONL project-key from
-        # ``cwd``, but claude itself writes the JSONL using the cwd's
-        # realpath — on macOS ``/tmp`` and ``/var/folders/...`` are
-        # both ``/private/...`` symlinks, so unresolved cwds make
-        # ``JsonlWatcher`` time out waiting on the wrong path. The
-        # explicit ``.resolve()`` collapses the symlink before claude
-        # ever sees the dir, and ``mkdtemp`` guarantees the directory
-        # is empty so claude does not pick up leftover files.
         ClaudeAgent(
-            name="stub",
+            name="assistant",
-            model="claude-sonnet-4-6",
+            model="claude-sonnet-5",
-            # ``system_prompt`` is appended to claude's built-in agent
+            cwd=VAULT,
-            # prompt (via ``--append-system-prompt``) — so it adds the
+            prompts=Prompts(master=(PROMPT,), branch=(PROMPT,), deep=(PROMPT,)),
-            # agent's identity on top of claude-code's baseline tool
+            gateway_tools=("spawn", "say", "schedule"),
-            # knowledge, rather than replacing it. Same shape as the
-            # RaycastAgent's ``system_prompt → additional_system_instructions``
-            # mapping. For full ``BackendOptions`` knobs (timeouts,
-            # extra_args, history mode, etc.) import ``ClaudeCodeOptions``
-            # and pass ``options=ClaudeCodeOptions(...)``.
-            system_prompt=(
-                "You are a stub agent used to validate the Phase 0 skeleton.\n"
-                "If asked the current time, call the `current_time`"
-                " MCP tool instead of guessing."
-            ),
-            cwd=Path(tempfile.mkdtemp(prefix="beaver-stub-cwd-")).resolve(),
             expose_mcps=(ExposedMcp(name="time"),),
-        ),
+        )
-        # Phase 1.2 — a RaycastAgent the AnthropicMessagesFrontend will
-        # route via RaycastBackend. Phase 1.5 added the per-agent knobs
-        # (`temperature` / `additional_system_instructions` / etc.) —
-        # only `model`, `system_prompt`, and at least one of the others
-        # is mandatory.
-        RaycastAgent(
-            name="research",
-            model="Gemini 3.1 Flash Lite",
-            system_prompt=(
-                "You are a research assistant. "
-                "Reply in the user's language. Cite URLs when you use web search."
-            ),
-            temperature=0.5,
-            available_native_tools=(RemoteTool.WEB_SEARCH, RemoteTool.READ_PAGE),
-            # Lambda so today's date is rebuilt on every request while
-            # locale/timezone stay pinned. ``True`` would give the same
-            # fresh-date behaviour but would also auto-pick host locale
-            # and timezone (``en-US`` / system tz), which isn't what we
-            # want here.
-            user_preferences=lambda: UserPreferences(
-                locale="en-GB",
-                timezone="Europe/Berlin",
-                current_date=date.today().isoformat(),  # noqa: DTZ011 — local date is intended
-            ),
-        ),
-    ],
-    mcps=[
-        # Phase 2.1 — bundle of plain Python callables exposed as one
-        # FastMCP namespace. The internal aggregator mounts it under
-        # ``/mcp/time`` on ``127.0.0.1:INTERNAL_MCP_PORT``; Phase 2.2's
-        # ClaudeCode adapter forwards that URL into
-        # ``BackendOptions.mcp_servers``. Phase 3's ``McpServerFrontend``
-        # reverse-proxies the same internal URL out to external clients.
-        McpServer.python_tool(name="time", tools=[current_time])
-        # Phase 3 — illustrates the ``lenient`` flag. Real-world stdio MCPs
-        # sometimes print "Processing..." or other chatter to stdout before
-        # their actual JSON-RPC frames; the default mcp client forwards
-        # those parse failures downstream as warnings (visible in
-        # Cursor/Cline). With ``lenient=True`` we silently drop non-JSON
-        # lines, so downstream UIs see clean JSON-RPC only. The command
-        # below is just a placeholder — replace with whatever stdio MCP
-        # you actually want gateway to ingest (e.g. an obsidian-mcp).
-        #
-        # Commented out by default: example users won't have the binary
-        # installed and an unreachable command makes ``docker compose up``
-        # surface a confusing "command not found" line at first request.
-        # Uncomment after pointing ``command`` at a real stdio MCP.
-        #
-        # McpServer.stdio(
-        #     name="obsidian",
-        #     command=["uvx", "mcp-obsidian"],
-        #     env={"OBSIDIAN_API_KEY": "..."},
-        #     lenient=True,
-        # ),
     ],
+    mcps=[McpServer.python_tool(name="time", tools=[current_time])],
     frontends=[
-        # Phase 1.4 — expose the agents as `model=<name>` on an
+        AnthropicMessagesFrontend(),
-        # Anthropic-compatible Messages endpoint. Auth comes from
+        McpServerFrontend(),
-        # `BOOTSTRAP_TOKENS` in the env (`name1:value1,name2:value2`).
+        AdminFrontend(),
-        #
+        ApiFrontend(master_agent="assistant", branch_agent="assistant"),
-        # Behind a reverse proxy (Caddy / nginx / Cloudflare) pass
+        MarkdownFrontend(vault_path=VAULT / "chats", default_agent="assistant"),
-        # `public_base_url=` so the admin dashboard advertises the
-        # outside URL instead of `host:port`. Caddy strips its own
-        # prefix and the frontend's internal paths (`/v1/messages`,
-        # `/v1/models`) get appended:
-        #   Caddy:  handle_path /ai/*  { reverse_proxy localhost:8000 }
-        #   Config: AnthropicMessagesFrontend(
-        #               port=8000,
-        #               public_base_url="https://domain.com/ai")
-        #   Result: https://domain.com/ai/v1/messages
-        AnthropicMessagesFrontend(host="0.0.0.0", port=8000),
-        # Phase 3 — re-exposes every declared `McpServer` outside the
-        # gateway with bearer auth + audit log. Each namespace lives
-        # at `/<name>/` on this port (the port itself disambiguates
-        # MCP traffic — no extra `/mcp` segment in the route); a flat
-        # bundle is published at `/all/`. Discovery page (HTML,
-        # auth-gated) at `/` with copy-pastable Cursor / Claude
-        # Desktop snippets. Auth re-uses `BOOTSTRAP_TOKENS`.
-        #
-        # Same `public_base_url=` knob as above. Caddy strips its
-        # prefix; the frontend's `/<name>/` segment gets appended:
-        #   Caddy:  handle_path /mcp/* { reverse_proxy localhost:8001 }
-        #   Config: McpServerFrontend(
-        #               port=8001,
-        #               public_base_url="https://domain.com/mcp")
-        #   Result: https://domain.com/mcp/<name>/  (and /mcp/all/)
-        McpServerFrontend(host="0.0.0.0", port=8001),
-        # Phase 4.3 — browser admin UI. Creds come from
-        # `ADMIN_USER`/`ADMIN_PASS`; the session cookie is signed with
-        # `SESSION_SECRET`. Use it to mint tokens (Argon2-hashed in
-        # the DB), revoke them, and watch the audit log. Scope is
-        # enforced on the bearer frontends: tokens minted with scope
-        # `messages` only work on `/v1/messages`; `mcp` only on
-        # `/mcp/<name>`; `*` works everywhere.
-        AdminFrontend(host="0.0.0.0", port=8002),
-        # Obsidian-vault chat frontend. Each `.md` is one conversation
-        # (User/Assistant turn pairs). The Obsidian companion plugin
-        # POSTs `{filename, content?}` to `/chat` — the frontend reads
-        # the file, runs the agent if the last turn is `user`, and
-        # appends the assistant reply back. With `log_all_chats=True`
-        # *every* turn (from Anthropic Messages too) is mirrored into
-        # `{vault}/_logs/<agent>/` so the vault is the central archive.
-        #
-        # `vault_path` here points at a per-restart tempdir so the
-        # example boots cleanly; in real deployments mount the
-        # Obsidian-sync container's vault volume to a stable path and
-        # pass that instead.
-        MarkdownFrontend(
-            host="0.0.0.0",
-            port=8003,
-            # Point at the dedicated chats subdir of your real Obsidian
-            # vault — the gateway has no idea (and no need) about other
-            # notes outside it. Path resolution / vault-escape checks
-            # are anchored here, so absolute-path attempts (and ``..``
-            # tricks) can't reach notes alongside it.
-            #
-            #   vault_path=Path("/Users/me/Obsidian/Personal/chats"),
-            #
-            # Per-restart tempdir kept here so the example boots even
-            # without a real vault on the host.
-            vault_path=Path(tempfile.mkdtemp(prefix="beaver-vault-")).resolve(),
-            default_agent="research",
-            log_all_chats=True,
-            # ``chat_path`` (optional) overrides the default
-            # ``{vault}/_logs/<agent>/<date>_<slug>.md`` layout. Heads up:
-            # any custom path forces ``warm_index`` to scan the entire
-            # vault on startup so the fingerprint→file map of archived
-            # stateless chats survives a restart no matter where you put
-            # files.
-            chat_path=chat_path,
-        ),
     ],
+    jobs=[Job("heartbeat", heartbeat, cron="0 * * * *")],
+    tz="UTC",
 )

examples/docker-compose.yml

@@ -1,34 +1,36 @@
-# Minimal compose for the Phase 0 DoD: build the image, mount a
-# single-file user config, watch the process print its summary line
-# and exit cleanly.
-#
-# Real deployments add a postgres service, raycast-config.json bind,
-# ~/.config/claude bind, etc. — Phase 5 lives in a separate example
-# repo (see PLAN §5.1).
-
 services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: beaver
+      POSTGRES_PASSWORD: beaver
+      POSTGRES_DB: beaver
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U beaver -d beaver"]
+      interval: 5s
+      timeout: 3s
+      retries: 20
+
   gateway:
     build:
       context: ..
-      dockerfile: Dockerfile
+    depends_on:
+      postgres:
+        condition: service_healthy
     environment:
-      DATABASE_URL: "sqlite:///./gateway.db"
+      CONFIG_PATH: /config/config.py
-      ADMIN_USER: "admin"
+      DATABASE_URL: postgresql+psycopg://beaver:beaver@postgres:5432/beaver
-      ADMIN_PASS: "change-me"
+      ADMIN_USER: admin
-      SESSION_SECRET: "dev-secret-change-me"
+      ADMIN_PASS: change-me
-      # Phase 1.4 — comma-separated `name:value` pairs. The frontend
+      SESSION_SECRET: change-me-too
-      # 401s every request until at least one token is set.
+      BOOTSTRAP_TOKENS: dev:change-me:*
-      BOOTSTRAP_TOKENS: "cursor:dev-token-change-me"
+      CLAUDE_CODE_OAUTH_TOKEN: ${CLAUDE_CODE_OAUTH_TOKEN}
-      # RAYCAST_BEARER / RAYCAST_DEVICE_ID + a raycast.json bind go
-      # here once you wire up an actual RaycastAgent. The example
-      # config.py declares one, so set these (or remove the agent)
-      # before exposing port 8000.
     ports:
-      # /v1/messages frontend
       - "8000:8000"
-      # MCP server frontend
-      - "8001:8001"
-      # Admin UI (Phase 4.3) — change ADMIN_USER/ADMIN_PASS/SESSION_SECRET
-      - "8002:8002"
     volumes:
       - ./config.py:/config/config.py:ro
+
+volumes:
+  postgres-data:

pyproject.toml

@@ -14,11 +14,13 @@ dependencies = [
     "anthropic>=0.103.0",
     "anyio>=4.13.0",
     "argon2-cffi>=25.1.0",
-    "claude-agent-sdk>=0.2.146",
+    "claude-agent-sdk>=0.2.150",
+    "croniter>=6.2.4",
     "fastapi>=0.136.1",
     "fastmcp>=3.3.1",
     "greenlet>=3.5.0",
     "itsdangerous>=2.2.0",
+    "pgqueuer>=1.3.2",
     "psutil>=7.2.2",
     "psycopg[binary]>=3.3.4",
     "pydantic>=2.13.4",
@@ -27,6 +29,7 @@ dependencies = [
     "sqlmodel>=0.0.38",
     "uvicorn[standard]>=0.47.0",
     "uvloop>=0.22.1",
+    "watchfiles>=1.2.0",
 ]
 
 [project.optional-dependencies]

src/beaver_gateway/agents/base.py

@@ -17,9 +17,8 @@ from pydantic import BaseModel, ConfigDict
 class ExposedMcp:
     """Reference to an ``McpServer`` (by name) exposed to a single agent.
 
-    ``tools`` is an allowlist of tool names (``None`` = every tool);
+    ``tools`` allowlists tool names (``None`` = all); ``deny`` removes
-    ``deny`` is a tuple of ``fnmatch`` patterns removed on top of that,
+    ``fnmatch`` patterns on top, e.g. ``("delete_*",)``.
-    e.g. ``("delete_*",)``.
     """
 
     name: str

src/beaver_gateway/agents/claude.py

@@ -1,24 +1,23 @@
 """Claude agent definition, backed by the Claude Agent SDK.
 
-The system prompt is ``system_prompt`` verbatim or, per conversation kind,
+``system_prompt`` is used verbatim, or per-kind granules from ``prompts``
-the granules named in ``prompts`` assembled at every session spawn (see
+are assembled via ``agents/prompts.py``. ``skill_sets`` are
-``core/prompt.py``). ``skill_sets`` are directories of ``<skill>/SKILL.md``
+``<skill>/SKILL.md`` directories, each becoming a local SDK plugin.
-folders; each becomes a local SDK plugin. Nothing from disk is loaded
-otherwise: the adapter runs with ``setting_sources=[]``.
 """
 
 from __future__ import annotations
 
-from collections.abc import Mapping  # noqa: TC003 - pydantic runtime
+from collections.abc import Mapping  # noqa: TC003
-from pathlib import Path  # noqa: TC003 - pydantic runtime
+from pathlib import Path  # noqa: TC003
 
 from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 from beaver_gateway.agents.base import BaseAgent
-from beaver_gateway.core.kinds import KINDS, Kind
+from beaver_gateway.agents.policy import PolicyRule  # noqa: TC001
-from beaver_gateway.core.prompt import PromptSource  # noqa: TC001 - pydantic runtime
+from beaver_gateway.agents.prompts import PromptSource  # noqa: TC001
+from beaver_gateway.conversations.kinds import KINDS, Kind
 
-__all__ = ["ClaudeAgent", "ClaudeOptions", "Prompts"]
+__all__ = ["ClaudeAgent", "ClaudeOptions", "Prompts", "SkillSets"]
 
 
 class ClaudeOptions(BaseModel):
@@ -47,10 +46,10 @@ class ClaudeOptions(BaseModel):
 
 
 class Prompts(BaseModel):
-    """Prompt assembly per conversation kind (§3.12): the granules, in order.
+    """Prompt assembly per conversation kind: the granules, in order.
 
-    A kind left ``None`` is not served by the agent; ``ClaudeAgent.kinds``
+    A kind left ``None`` is not served; ``ClaudeAgent.kinds`` follows from
-    follows from the kinds set here.
+    the kinds set here.
     """
 
     model_config = ConfigDict(frozen=True)
@@ -69,6 +68,21 @@ class Prompts(BaseModel):
         return tuple(k for k in KINDS if self.for_kind(k) is not None)
 
 
+class SkillSets(BaseModel):
+    """Skill-set directories per conversation kind; ``None`` means none."""
+
+    model_config = ConfigDict(frozen=True)
+
+    master: tuple[Path, ...] | None = None
+    branch: tuple[Path, ...] | None = None
+    deep: tuple[Path, ...] | None = None
+    job: tuple[Path, ...] | None = None
+    fork: tuple[Path, ...] | None = None
+
+    def for_kind(self, kind: Kind) -> tuple[Path, ...]:
+        return getattr(self, kind) or ()
+
+
 class ClaudeAgent(BaseAgent):
     cwd: Path
     system_prompt: str = ""
@@ -76,16 +90,21 @@ class ClaudeAgent(BaseAgent):
 
     prompts: Prompts = Field(default_factory=Prompts)
     kinds: tuple[Kind, ...] = ()
-    """Conversation kinds this agent serves; ``create``/``spawn`` reject the
+    """Conversation kinds this agent serves; ``create``/``spawn`` reject the rest.
-    rest. Defaults to the kinds ``prompts`` covers, or ``("deep",)`` for a
+    Defaults to what ``prompts`` covers, or ``("deep",)`` for a verbatim prompt."""
-    verbatim ``system_prompt``."""
+
+    skill_sets: tuple[Path, ...] | SkillSets = ()
+    """Skill-set directories, each a local plugin: one tuple for every kind,
+    or a ``SkillSets`` giving each kind its own (``None`` = no skills)."""
 
-    skill_sets: tuple[Path, ...] = ()
     gateway_tools: tuple[str, ...] = ()
     """Gateway tools exposed in-process (``read_conversation``, ``spawn``,
     ``say``, ``schedule``, ``inject``); empty = no gateway MCP server."""
 
     options: ClaudeOptions = Field(default_factory=ClaudeOptions)
+    policy: tuple[PolicyRule, ...] = ()
+    """``PreToolUse`` rules, run in order on every tool call; the first
+    ``Deny`` is what the model reads back. See ``agents/policy.py``."""
 
     @model_validator(mode="after")
     def _kinds_follow_prompts(self) -> ClaudeAgent:
@@ -102,5 +121,10 @@ class ClaudeAgent(BaseAgent):
     def prompt_for(self, kind: Kind) -> tuple[PromptSource, ...] | None:
         return self.prompts.for_kind(kind)
 
+    def skills_for(self, kind: Kind) -> tuple[Path, ...]:
+        if isinstance(self.skill_sets, SkillSets):
+            return self.skill_sets.for_kind(kind)
+        return self.skill_sets
+
     def serves(self, kind: str) -> bool:
         return kind in self.kinds

src/beaver_gateway/agents/policy.py

@@ -0,0 +1,167 @@
+"""PreToolUse policy - the boundary without permission prompts.
+
+A rule is a callable ``(ToolCall) -> Deny | None`` declared per agent
+(``ClaudeAgent.policy``); the first :class:`Deny` becomes the tool result
+the model reads back. A rule that raises is a deny too: fails closed.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+import logging
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Mapping, MutableMapping
+
+__all__ = [
+    "AuditSink",
+    "Decision",
+    "Deny",
+    "PolicyRule",
+    "ToolAudit",
+    "ToolCall",
+    "brief",
+    "evaluate",
+    "hook_output",
+]
+
+_log = logging.getLogger("beaver_gateway.policy")
+
+PATH_KEYS: tuple[str, ...] = ("file_path", "notebook_path", "path")
+"""Input keys built-in file tools use for their target."""
+
+Decision = Literal["allow", "deny"]
+
+
+@dataclass(frozen=True, slots=True)
+class Deny:
+    """Refusal with the reason the model reads as the tool result."""
+
+    reason: str
+
+
+@dataclass(frozen=True, slots=True)
+class ToolCall:
+    """One tool invocation as the hook sees it.
+
+    ``state`` is a mutable per-session dict rules may write to (which
+    skills were opened, what was already asked); it lives as long as the
+    claude process and is empty again after a resume.
+    """
+
+    tool: str
+    input: Mapping[str, Any]
+    agent: str
+    kind: str
+    conversation: str
+    cwd: Path
+    state: MutableMapping[str, Any] = field(default_factory=dict)
+
+    @property
+    def mcp(self) -> tuple[str, str] | None:
+        """``(server, tool)`` for ``mcp__<server>__<tool>`` names, else ``None``."""
+        if not self.tool.startswith("mcp__"):
+            return None
+        _, _, rest = self.tool.partition("__")
+        server, sep, name = rest.partition("__")
+        return (server, name) if sep else (server, "")
+
+    def path(self, *keys: str) -> Path | None:
+        """Target of a file tool, absolute; relative paths resolve against ``cwd``."""
+        for key in keys or PATH_KEYS:
+            raw = self.input.get(key)
+            if isinstance(raw, str) and raw:
+                return self.resolve(raw)
+        return None
+
+    def resolve(self, raw: str) -> Path:
+        """Absolute path for ``raw``, normalised lexically.
+
+        Not via ``Path.resolve``, which would follow symlinks on the host,
+        not the model's view.
+        """
+        path = Path(raw).expanduser()
+        if not path.is_absolute():
+            path = self.cwd / path
+        return Path(*_normalize(path.parts))
+
+
+def _normalize(parts: Iterable[str]) -> list[str]:
+    out: list[str] = []
+    for part in parts:
+        if part == "..":
+            if len(out) > 1:
+                out.pop()
+        elif part != ".":
+            out.append(part)
+    return out
+
+
+type PolicyRule = Callable[[ToolCall], Deny | None | Awaitable[Deny | None]]
+"""A rule; sync or async. First ``Deny`` wins, ``None`` passes to the next."""
+
+
+@dataclass(frozen=True, slots=True)
+class ToolAudit:
+    agent: str
+    conversation: str
+    kind: str
+    tool: str
+    decision: Decision
+    reason: str | None
+    brief: str
+
+
+AuditSink = "Callable[[ToolAudit], Awaitable[None]]"
+
+
+async def evaluate(
+    rules: Iterable[Callable[[ToolCall], Any]], call: ToolCall
+) -> Deny | None:
+    """Run ``rules`` in order; the first deny wins, an exception is a deny."""
+    for rule in rules:
+        try:
+            verdict = rule(call)
+            if inspect.isawaitable(verdict):
+                verdict = await verdict
+        except Exception:  # noqa: BLE001
+            name = getattr(rule, "__name__", repr(rule))
+            _log.exception("policy rule %s failed on %s", name, call.tool)
+            return Deny(reason=f"policy rule {name} failed; the call is refused")
+        if isinstance(verdict, Deny):
+            return verdict
+    return None
+
+
+def hook_output(deny: Deny | None) -> dict[str, Any]:
+    """``PreToolUse`` hook JSON for a verdict: empty means allow."""
+    if deny is None:
+        return {}
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": deny.reason,
+        }
+    }
+
+
+def brief(tool_input: Mapping[str, Any], *, limit: int = 240) -> str:
+    """Short, log-safe summary of a call: the path, the command, or the args."""
+    for key in (*PATH_KEYS, "command", "skill", "pattern", "query", "url"):
+        value = tool_input.get(key)
+        if isinstance(value, str) and value:
+            return _cut(value, limit)
+    try:
+        return _cut(json.dumps(tool_input, ensure_ascii=False, sort_keys=True), limit)
+    except (TypeError, ValueError):
+        return _cut(repr(tool_input), limit)
+
+
+def _cut(text: str, limit: int) -> str:
+    return text if len(text) <= limit else text[: limit - 1] + "…"

src/beaver_gateway/agents/prompts.py

@@ -1,12 +1,7 @@
 """System prompt assembly from a list of source files.
 
-The gateway holds no prompt text: an agent names its granules (paths from
+:func:`assemble` concatenates an agent's granules in order. A source is a
-``config.py``) and :func:`assemble` concatenates them in that order, so the
+path, or a ``(tag, path)`` pair whose content is wrapped in ``<tag>...</tag>``.
-result is byte-for-byte identical for every session of the same agent as
-long as the files are. A source is a path, or a ``(tag, path)`` pair whose
-content is wrapped in ``<tag>...</tag>`` - the markup lives here, the vault
-keeps plain markdown. Each granule's hash is logged at assembly so a
-drifted prompt can be traced to the file that changed.
 """
 
 from __future__ import annotations
@@ -21,12 +16,13 @@ if TYPE_CHECKING:
 
 __all__ = ["PromptSource", "assemble"]
 
-_log = logging.getLogger("beaver_gateway.core.prompt")
+_log = logging.getLogger("beaver_gateway.agents.prompts")
 
 PromptSource = str | Path | tuple[str, str | Path]
 
 
 def assemble(sources: Iterable[PromptSource]) -> str:
+    """Concatenate ``sources`` in order into one system prompt."""
     parts: list[str] = []
     for source in sources:
         tag, raw = source if isinstance(source, tuple) else (None, source)

src/beaver_gateway/agents/raycast.py

@@ -1,31 +1,12 @@
 """Raycast agent definition.
 
-Field set is the union of ``raycast_api.ChatAPI.stream`` parameters that
+Field set is the union of ``raycast_api.ChatAPI.stream`` parameters useful
-make sense as **per-agent defaults**. Per-request values (currently:
+as per-agent defaults; per-request values override them where both exist.
-``temperature``) win when both are set; the rest fall back to whatever
-the agent declared, then to Raycast's own defaults.
-
-``BaseAgent.system_prompt`` maps onto Raycast's wire field
-``additional_system_instructions`` (the slot the real client uses for
-*content*); the wire field ``system_instructions`` stays at the Raycast
-source default — ``"markdown"`` for ``AI_CHAT``, ``"plain"`` otherwise.
-We don't expose that wire dichotomy to the user — they get one
-conceptual "system prompt".
-
-Excluded on purpose:
-
-* ``buffer_id``/``message_id``/``current_date`` — per-call ephemeral
-* ``provider`` override — escape hatch for non-catalog models, no clear
-  use case yet (revisit in PRD §14 when discovery lands)
-* ``locale`` — process-wide via ``Settings.raycast_locale`` because we
-  only spin up one ``raycast_api.Client`` per gateway
-* ``system_instructions`` (wire) — that's a format marker, not content;
-  the SDK fills it from the source default and we let it
 """
 
 from __future__ import annotations
 
-from raycast_api import (  # noqa: F401  — UserPreferences re-exported for user configs
+from raycast_api import (  # noqa: F401
     RemoteTool,
     Source,
     UserPreferences,
@@ -36,44 +17,21 @@ from beaver_gateway.agents.base import BaseAgent
 
 
 class RaycastAgent(BaseAgent):
-    """Agent backed by ``raycast-api``.
+    """Agent backed by ``raycast-api``."""
-
-    ``available_native_tools`` is the closed set of Raycast's server-side
-    "remote tools" (``web_search``, ``search_images``, ``read_page``) —
-    typed as ``RemoteTool`` so config-time IDE completion lists exactly
-    the three valid values. Pydantic also coerces string literals, so
-    ``("web_search", "read_page")`` keeps working unchanged.
-
-    ``user_preferences`` toggles the auto-generated ``<user-preferences>``
-    block Raycast prepends to ``additional_system_instructions``:
-
-    * ``True`` (default) → auto from host locale/timezone/today, rebuilt
-      every request so the date stays fresh;
-    * ``False`` → omit the block entirely;
-    * ``UserPreferences(...)`` instance → used verbatim (frozen at the
-      time the agent was loaded, so the date won't auto-update);
-    * ``Callable[[], UserPreferencesArg]`` → re-invoked on every request.
-      Use this for the common case "fresh date but custom
-      locale/timezone": ``user_preferences=lambda:
-      UserPreferences(locale="ru-RU", timezone="Europe/Berlin",
-      current_date=date.today().isoformat())``. Callables may nest
-      (a lambda returning a lambda…) but there's no real reason to.
-
-    The library uses this block for date/locale-aware formatting, not
-    for personalisation/memory — those are out of scope upstream.
-
-    ``reasoning_effort`` values vary by model: GPT-5 takes
-    ``"minimal"|"low"|"medium"|"high"``; Anthropic exposes nothing here
-    (Claude reasoning lives in a separate ``…-reasoning`` model variant
-    in the catalog). Unknown effort for the chosen model is ignored
-    server-side, so we stay loose as ``str | None``.
-    """
 
     streaming: bool = True
     available_native_tools: tuple[RemoteTool, ...] = ()
+    """Raycast's server-side "remote tools": ``web_search``, ``search_images``,
+    ``read_page``."""
+
     source: Source = Source.AI_CHAT
 
     temperature: float | None = None
     reasoning_effort: str | None = None
+    """Model-specific (e.g. GPT-5: ``"minimal"``/``"low"``/``"medium"``/``"high"``);
+    ignored server-side if the model doesn't support it."""
+
     tool_choice: str | None = None
     user_preferences: UserPreferencesArg = True
+    """Auto-fills the ``<user-preferences>`` block from host locale/timezone/date;
+    ``False`` omits it, or pass ``UserPreferences(...)`` / a zero-arg callable."""

src/beaver_gateway/app.py

@@ -0,0 +1,447 @@
+"""Build the runtime from a ``Gateway`` and run every part of it until shutdown."""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import logging
+from contextlib import AsyncExitStack
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import psycopg
+import uvicorn
+from pgqueuer import PsycopgDriver
+from raycast_api import Client as RaycastClient
+from raycast_api.config import Config as RaycastConfig
+
+from beaver_gateway.agents.claude import ClaudeAgent
+from beaver_gateway.agents.raycast import RaycastAgent
+from beaver_gateway.backends.claude_sdk import (
+    ClaudeSdkBackend,
+    RunnerConfig,
+    UsageEvent,
+)
+from beaver_gateway.backends.raycast import RaycastBackend
+from beaver_gateway.backends.sessions import SessionPool
+from beaver_gateway.conversations.envelope import Envelope
+from beaver_gateway.conversations.rotation import Rotation, RotationPolicy
+from beaver_gateway.conversations.service import Conversations
+from beaver_gateway.conversations.tools import build_tool_server
+from beaver_gateway.events.bus import EventBus
+from beaver_gateway.frontends.base import GatewayRuntime
+from beaver_gateway.frontends.bearer import require_token
+from beaver_gateway.frontends.root import build_root_app
+from beaver_gateway.jobs.scheduler import Scheduler
+from beaver_gateway.mcp.internal_app import build_internal_app
+from beaver_gateway.security.auth import TokenStore, scopes_with
+from beaver_gateway.storage import (
+    Database,
+    PostgresSessionStore,
+    Usage,
+    append_audit,
+    append_usage,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator
+
+    from claude_agent_sdk import McpSdkServerConfig
+    from fastmcp import FastMCP
+    from fastmcp.tools.base import Tool as FastMCPTool
+    from starlette.applications import Starlette
+    from starlette.requests import Request
+    from starlette.types import ASGIApp
+
+    from beaver_gateway.agents.base import BaseAgent
+    from beaver_gateway.agents.policy import ToolAudit
+    from beaver_gateway.backends.base import Backend
+    from beaver_gateway.config import Gateway
+    from beaver_gateway.mcp.types import McpServerT
+    from beaver_gateway.settings import Settings
+
+__all__ = ["AgentRegistry", "McpRegistry", "run"]
+
+_log = logging.getLogger("beaver_gateway.app")
+
+
+class AgentRegistry:
+    def __init__(self, agents: Iterable[BaseAgent]) -> None:
+        self._agents: dict[str, BaseAgent] = {}
+        for a in agents:
+            if a.name in self._agents:
+                msg = f"duplicate agent name: {a.name!r}"
+                raise ValueError(msg)
+            self._agents[a.name] = a
+
+    def __getitem__(self, name: str) -> BaseAgent:
+        return self._agents[name]
+
+    def get(self, name: str) -> BaseAgent | None:
+        return self._agents.get(name)
+
+    def __iter__(self) -> Iterator[BaseAgent]:
+        return iter(self._agents.values())
+
+    def __len__(self) -> int:
+        return len(self._agents)
+
+    def __contains__(self, name: object) -> bool:
+        return name in self._agents
+
+
+class McpRegistry:
+    def __init__(self, mcps: Iterable[McpServerT]) -> None:
+        self._mcps: dict[str, McpServerT] = {}
+        for m in mcps:
+            if m.name in self._mcps:
+                msg = f"duplicate mcp name: {m.name!r}"
+                raise ValueError(msg)
+            self._mcps[m.name] = m
+
+    def __getitem__(self, name: str) -> McpServerT:
+        return self._mcps[name]
+
+    def get(self, name: str) -> McpServerT | None:
+        return self._mcps.get(name)
+
+    def __iter__(self) -> Iterator[McpServerT]:
+        return iter(self._mcps.values())
+
+    def __len__(self) -> int:
+        return len(self._mcps)
+
+    def __contains__(self, name: object) -> bool:
+        return name in self._mcps
+
+
+async def run(gateway: Gateway, settings: Settings) -> None:
+    agents = AgentRegistry(gateway.agents)
+    mcps = McpRegistry(gateway.mcps)
+    db = Database(settings.database_url)
+    await db.create_all()
+    token_store = TokenStore(
+        db,
+        bootstrap=TokenStore.parse_bootstrap(settings.bootstrap_tokens),
+        bootstrap_scopes=TokenStore.parse_bootstrap_scopes(settings.bootstrap_tokens),
+    )
+
+    async with AsyncExitStack() as stack:
+        stack.push_async_callback(db.dispose)
+        await token_store.start()
+        stack.push_async_callback(token_store.stop)
+        internal_app, internal_urls, mcp_servers = _build_internal_mcp(
+            gateway.mcps, settings=settings
+        )
+        mcp_tools = await _prefetch_mcp_tools(mcp_servers)
+
+        pool = SessionPool()
+        bus = EventBus()
+        late = _LateConversations()
+        session_store = PostgresSessionStore(db)
+        backends = await _build_backends(
+            settings=settings,
+            agents=agents,
+            stack=stack,
+            db=db,
+            session_store=session_store,
+            mcp_internal_urls=internal_urls,
+            mcp_servers=mcp_servers,
+            mcp_tools=mcp_tools,
+            pool=pool,
+            late=late,
+        )
+        conversations = Conversations(
+            db=db,
+            agents=agents,
+            backends=backends,
+            bus=bus,
+            pool=pool,
+            store=session_store,
+            texts=gateway.texts,
+            frontends=gateway.frontends,
+            envelope=Envelope(
+                watch=gateway.watch, tz=gateway.tz, recall=gateway.recall
+            ),
+            distiller=gateway.distiller,
+            user_sink=gateway.user_sink,
+        )
+        late.conversations = conversations
+        scheduler = Scheduler(
+            conversations=conversations,
+            jobs=gateway.jobs,
+            driver=await _pgqueuer_driver(settings.database_url, stack),
+            budget=gateway.budget,
+            rotation=Rotation(
+                conversations, gateway.rotation or RotationPolicy(tz=gateway.tz)
+            ),
+            tz=gateway.tz,
+        )
+        conversations.scheduler = scheduler
+
+        runtime = GatewayRuntime(
+            agents=agents,
+            mcps=mcps,
+            backends=backends,
+            token_store=token_store,
+            db=db,
+            mcp_internal_urls=internal_urls,
+            admin_user=settings.admin_user,
+            admin_pass=settings.admin_pass,
+            session_secret=settings.session_secret,
+            frontends=tuple(gateway.frontends),
+            conversations=conversations,
+            bus=bus,
+            pool=pool,
+            scheduler=scheduler,
+            public_url=gateway.public_url.rstrip("/") if gateway.public_url else None,
+            scopes=scopes_with(fe.scope for fe in gateway.frontends),
+            send_file_roots=_roots(settings.send_file_roots),
+        )
+        for fe in gateway.frontends:
+            fe.configure(runtime)
+
+        _log.info(
+            "beaver-gateway: loaded %d agents, %d mcps, %d frontends",
+            len(agents),
+            len(mcps),
+            len(gateway.frontends),
+        )
+        if not gateway.frontends:
+            return
+
+        await conversations.start()
+        stack.push_async_callback(conversations.stop)
+        await scheduler.start()
+        stack.push_async_callback(scheduler.stop)
+        hooks = scheduler.app(
+            functools.partial(_authorize_hook, runtime=runtime, scope="api")
+        )
+        async with asyncio.TaskGroup() as tg:
+            tg.create_task(pool.reap_loop())
+            if internal_app is not None:
+                tg.create_task(_serve_internal_mcp(internal_app, settings=settings))
+            tg.create_task(_serve_root(gateway, extra={"/hooks": hooks}))
+            if gateway.watch is not None:
+                tg.create_task(gateway.watch.run())
+            for fe in gateway.frontends:
+                tg.create_task(fe.serve())
+
+
+async def _authorize_hook(
+    request: Request, *, runtime: GatewayRuntime, scope: str
+) -> str:
+    return await require_token(request, runtime, scope=scope)
+
+
+async def _pgqueuer_driver(url: str, stack: AsyncExitStack) -> PsycopgDriver | None:
+    plain = _plain_postgres_url(url)
+    if plain is None:
+        return None
+    conn = await psycopg.AsyncConnection.connect(plain, autocommit=True)
+    stack.push_async_callback(conn.close)
+    return PsycopgDriver(conn)
+
+
+def _plain_postgres_url(url: str) -> str | None:
+    for prefix in ("postgresql+psycopg://", "postgresql://", "postgres://"):
+        if url.startswith(prefix):
+            return "postgresql://" + url[len(prefix) :]
+    return None
+
+
+async def _serve_root(gateway: Gateway, *, extra: dict[str, ASGIApp]) -> None:
+    app = build_root_app(gateway.frontends, extra=extra)
+    config = uvicorn.Config(app, host=gateway.host, port=gateway.port, log_level="info")
+    _log.info(
+        "gateway on http://%s:%d - %s",
+        gateway.host,
+        gateway.port,
+        ", ".join([*(fe.path for fe in gateway.frontends if fe.path), *extra])
+        or "no http frontends",
+    )
+    await uvicorn.Server(config).serve()
+
+
+def _build_internal_mcp(
+    mcps: list[McpServerT], *, settings: Settings
+) -> tuple[Starlette | None, dict[str, str], dict[str, FastMCP]]:
+    if not mcps:
+        return None, {}, {}
+    return build_internal_app(mcps, host="127.0.0.1", port=settings.internal_mcp_port)
+
+
+async def _prefetch_mcp_tools(
+    servers: dict[str, FastMCP],
+) -> dict[str, list[FastMCPTool]]:
+    out: dict[str, list[FastMCPTool]] = {}
+    for name, server in servers.items():
+        try:
+            out[name] = list(await server.list_tools())
+        except Exception:  # noqa: BLE001
+            _log.exception("failed to list tools for MCP %r, skipping", name)
+            out[name] = []
+    return out
+
+
+async def _serve_internal_mcp(app: Starlette, *, settings: Settings) -> None:
+    config = uvicorn.Config(
+        app,
+        host="127.0.0.1",
+        port=settings.internal_mcp_port,
+        log_level="warning",
+        loop="uvloop",
+    )
+    _log.info(
+        "internal MCP aggregator on http://127.0.0.1:%d/mcp/<name>",
+        settings.internal_mcp_port,
+    )
+    await uvicorn.Server(config).serve()
+
+
+def _roots(value: str) -> tuple[Path, ...]:
+    return tuple(Path(p) for p in value.split(":") if p.strip())
+
+
+class _LateConversations:
+    conversations: Conversations | None = None
+
+    def server(
+        self, key: str, _kind: str, names: tuple[str, ...]
+    ) -> McpSdkServerConfig | None:
+        if self.conversations is None or not names:
+            return None
+        return build_tool_server(self.conversations, conversation_key=key, names=names)
+
+    async def ask(self, key: str, payload: dict[str, Any]) -> str:
+        if self.conversations is None:
+            msg = "conversations service is not up yet"
+            raise RuntimeError(msg)
+        answer = await self.conversations.ask(key, payload)
+        return self.conversations.answer_text(answer)
+
+
+async def _build_backends(
+    *,
+    settings: Settings,
+    agents: AgentRegistry,
+    stack: AsyncExitStack,
+    db: Database,
+    session_store: PostgresSessionStore,
+    mcp_internal_urls: dict[str, str],
+    mcp_servers: dict[str, FastMCP],
+    mcp_tools: dict[str, list[FastMCPTool]],
+    pool: SessionPool,
+    late: _LateConversations,
+) -> dict[str, Backend]:
+    backends: dict[str, Backend] = {}
+
+    raycast_agents = [a for a in agents if isinstance(a, RaycastAgent)]
+    if raycast_agents:
+        client = await _try_open_raycast_client(settings, stack)
+        if client is not None:
+            raycast_backend = RaycastBackend(
+                client, mcp_servers=mcp_servers, mcp_tools=mcp_tools
+            )
+            for a in raycast_agents:
+                backends[a.name] = raycast_backend
+
+    runner = RunnerConfig(user=settings.claude_runner_user, home=settings.claude_home)
+    mcp_tool_names = {
+        name: [t.name for t in tools] for name, tools in mcp_tools.items()
+    }
+
+    async def record_usage(event: UsageEvent) -> None:
+        row = Usage(
+            agent_name=event.agent_name,
+            conversation_id=event.conversation_id,
+            session_id=event.session_id,
+            model=event.model,
+            effort=event.effort,
+            input_tokens=event.usage.input_tokens,
+            output_tokens=event.usage.output_tokens,
+            cache_read_tokens=event.usage.cache_read_tokens,
+            cache_creation_tokens=event.usage.cache_creation_tokens,
+            context_tokens=event.usage.context_tokens,
+            cost_usd=event.usage.cost_usd,
+            duration_ms=event.usage.duration_ms,
+            num_turns=event.usage.num_turns,
+            model_usage=event.usage.model_usage,
+        )
+        try:
+            async with db.session() as session:
+                await append_usage(session, row)
+        except Exception:  # noqa: BLE001
+            _log.exception("usage write failed for %s", event.agent_name)
+
+    async def record_tool(event: ToolAudit) -> None:
+        detail = {
+            "conversation": event.conversation,
+            "kind": event.kind,
+            "tool": event.tool,
+            "decision": event.decision,
+            "reason": event.reason,
+            "brief": event.brief,
+        }
+        try:
+            async with db.session() as session:
+                await append_audit(
+                    session,
+                    actor=f"agent:{event.agent}",
+                    kind="tool_call",
+                    agent_name=event.agent,
+                    detail=detail,
+                )
+        except Exception:  # noqa: BLE001
+            _log.exception("tool audit write failed for %s", event.agent)
+
+    for a in agents:
+        if isinstance(a, ClaudeAgent):
+            adapter = ClaudeSdkBackend(
+                agent=a,
+                mcp_internal_urls=mcp_internal_urls,
+                session_store=session_store,
+                mcp_tool_names=mcp_tool_names,
+                runner=runner,
+                usage_sink=record_usage,
+                pool=pool,
+                tool_server=functools.partial(late.server, names=a.gateway_tools),
+                asker=late.ask,
+                audit_sink=record_tool,
+            )
+            await stack.enter_async_context(adapter)
+            backends[a.name] = adapter
+
+    return backends
+
+
+async def _try_open_raycast_client(
+    settings: Settings, stack: AsyncExitStack
+) -> RaycastClient | None:
+    if not settings.raycast_bearer:
+        _log.warning(
+            "RaycastAgent present but RAYCAST_BEARER is unset; those agents 503"
+        )
+        return None
+    if not settings.raycast_device_id:
+        _log.warning(
+            "RaycastAgent present but RAYCAST_DEVICE_ID is unset, those agents 503 "
+            "(generate once with `python -c 'import secrets; "
+            "print(secrets.token_hex(32))'`)"
+        )
+        return None
+    if not settings.raycast_config_path.exists():
+        _log.warning(
+            "RaycastAgent present but %s is missing, those agents 503",
+            settings.raycast_config_path,
+        )
+        return None
+
+    config = RaycastConfig.load(settings.raycast_config_path)
+    client = RaycastClient(
+        config=config,
+        bearer_token=settings.raycast_bearer,
+        device_id=settings.raycast_device_id,
+        locale=settings.raycast_locale,
+    )
+    return await stack.enter_async_context(client)

src/beaver_gateway/backends/__init__.py

@@ -1,6 +1,6 @@
 """Backend adapters.
 
 Each backend wraps a provider SDK (``raycast-api``, ``claude-agent-sdk``)
-and yields the unified :class:`~beaver_gateway.core.events.MessageStreamEvent`
+and yields the unified :class:`~beaver_gateway.events.stream.MessageStreamEvent`
 family. The Anthropic-style frontend serialises events straight to SSE.
 """

src/beaver_gateway/backends/base.py

@@ -1,19 +1,8 @@
 """Backend protocol.
 
 A backend turns an Anthropic-style turn (``messages`` + agent definition)
-into a stream of :class:`~beaver_gateway.core.events.MessageStreamEvent`
+into a stream of :class:`~beaver_gateway.events.stream.MessageStreamEvent`
-records. The frontend serializes whatever comes out straight to SSE, so
+records; provider quirks are translated here, not in the frontend.
-backends are the only place where provider quirks are translated.
-
-Implementations are plain :class:`typing.Protocol` conformers - no ABC
-subclassing - to keep them swappable in tests with bare async generators.
-
-``**options`` is the one extension point. Known keys, all optional and
-ignored by backends that don't keep state: ``conversation_id`` (stable id
-the backend may pin a live session to), ``session_id`` (backend session to
-resume when nothing is live), ``capture`` (a
-:class:`~beaver_gateway.core.turn_capture.TurnCapture` the backend fills
-after the stream closes).
 """
 
 from __future__ import annotations
@@ -26,7 +15,7 @@ if TYPE_CHECKING:
     from anthropic.types import MessageParam
 
     from beaver_gateway.agents.base import BaseAgent
-    from beaver_gateway.core.events import MessageStreamEvent
+    from beaver_gateway.events.stream import MessageStreamEvent
 
 
 class Backend(Protocol):
@@ -40,5 +29,13 @@ class Backend(Protocol):
         system: str | None = None,
         **options: Any,
     ) -> AsyncIterator[MessageStreamEvent]:
-        """Yield Anthropic stream events for one turn against ``agent``."""
+        """Yield Anthropic stream events for one turn against ``agent``.
+
+        ``**options`` keys are optional and ignored by backends that don't
+        keep state: ``conversation_id`` (stable id the backend may pin a
+        live session to), ``session_id`` (backend session to resume when
+        nothing is live), ``capture`` (a
+        :class:`~beaver_gateway.backends.capture.TurnCapture` the backend
+        fills after the stream closes).
+        """
         ...

src/beaver_gateway/backends/capture.py

@@ -1,10 +1,7 @@
 """Side channel for what a backend learned during one turn.
 
 Frontends pass ``capture=TurnCapture()`` through ``Backend.complete``'s
-``**options``. Backends that keep state per conversation (the Claude SDK
+``**options``; only backends that keep state per conversation fill it in.
-adapter) fill it in after the stream closes; backends that don't
-(anthropic, raycast) drop the kwarg and the frontend falls back to a
-text-only history.
 """
 
 from __future__ import annotations
@@ -27,6 +24,12 @@ class TurnUsage:
     model_usage: dict[str, Any] | None = None
     """``ResultMessage.model_usage`` verbatim: per-model tokens, cost, web searches."""
 
+    context_tokens: int = 0
+    """Input of the last API call in the turn (fresh + cached + written to
+    cache) - the context size the model actually ran with, what Claude Code
+    shows as the context. The token fields above are sums over every API
+    call of the turn and grow with the number of tool calls."""
+
 
 @dataclass
 class TurnCapture:

src/beaver_gateway/backends/claude_sdk.py

@@ -1,29 +1,7 @@
 """Claude Agent SDK backend adapter.
 
-One :class:`ClaudeSdkBackend` per :class:`ClaudeAgent`. A live session is
+One :class:`ClaudeSdkBackend` per :class:`ClaudeAgent`; its sessions live in
-one ``ClaudeSDKClient`` (one claude subprocess) and runs one turn at a
+a shared :class:`~beaver_gateway.backends.sessions.SessionPool`.
-time; the sessions of every agent live in one shared
-:class:`~beaver_gateway.core.sessions.SessionPool` that owns TTL and
-memory-pressure eviction. Sessions are keyed by ``conversation_id`` when
-the caller passes one or by a text-only fingerprint of ``messages[:-1]``
-for stateless callers (``/v1/messages``). Without a live session the
-adapter resumes ``session_id`` from the session store (after closing any
-``tool_use`` left open by a crash), or seeds the incoming history into the
-store via ``core/transcript`` and resumes that.
-
-Per-turn ``**options`` beyond the protocol's: ``kind`` (conversation kind,
-picks the prompt assembly and the pool TTL), ``pinned`` (never evicted),
-``tools=False`` (no MCP at all - forks and jobs), ``observer`` (callback
-receiving every raw SDK message, subagent ones included), ``turn_id``.
-
-Events on the wire are the Anthropic ``MessageStreamEvent`` family: one
-``message_start``/``message_stop`` envelope per turn, block indices
-rebased across the API calls claude makes inside the turn.
-
-Process isolation: claude is spawned through a small exec wrapper that
-drops every inherited environment variable outside a whitelist and, when
-``RunnerConfig.user`` is set, switches to that uid before exec (done in the
-wrapper rather than via ``subprocess(user=...)``, which uvloop rejects).
 """
 
 from __future__ import annotations
@@ -53,11 +31,13 @@ from claude_agent_sdk import (
     CanUseToolShadowedWarning,
     ClaudeAgentOptions,
     ClaudeSDKClient,
+    HookMatcher,
     MirrorErrorMessage,
     PermissionResultAllow,
     PermissionResultDeny,
     ResultMessage,
     StreamEvent,
+    TaskNotificationMessage,
     TextBlock,
     ThinkingBlock,
     ToolResultBlock,
@@ -66,8 +46,18 @@ from claude_agent_sdk import (
     project_key_for_directory,
 )
 
-from beaver_gateway.core import prompt as prompt_assembly
+from beaver_gateway.agents import policy as policy_mod
-from beaver_gateway.core.events import (
+from beaver_gateway.agents import prompts as prompt_assembly
+from beaver_gateway.backends.capture import TurnCapture, TurnUsage
+from beaver_gateway.backends.sessions import Session, SessionClient, SessionPool
+from beaver_gateway.backends.transcript import (
+    build_entries,
+    close_open_tool_uses,
+    fingerprint,
+    text_of,
+)
+from beaver_gateway.conversations.kinds import as_kind
+from beaver_gateway.events.stream import (
     StopReason,
     build_content_block_stop,
     build_input_json_delta,
@@ -81,18 +71,16 @@ from beaver_gateway.core.events import (
     build_thinking_delta,
     build_tool_use_block_start,
 )
-from beaver_gateway.core.kinds import as_kind
-from beaver_gateway.core.sessions import Session, SessionClient, SessionPool
-from beaver_gateway.core.transcript import (
-    build_entries,
-    close_open_tool_uses,
-    fingerprint,
-    text_of,
-)
-from beaver_gateway.core.turn_capture import TurnCapture, TurnUsage
 
 if TYPE_CHECKING:
-    from collections.abc import AsyncIterator, Awaitable, Callable, Iterable, Sequence
+    from collections.abc import (
+        AsyncIterator,
+        Awaitable,
+        Callable,
+        Coroutine,
+        Iterable,
+        Sequence,
+    )
 
     from anthropic.types import MessageParam
     from claude_agent_sdk import (
@@ -101,21 +89,22 @@ if TYPE_CHECKING:
         SessionStore,
         ToolPermissionContext,
     )
+    from claude_agent_sdk.types import HookEvent
 
     from beaver_gateway.agents.base import BaseAgent
     from beaver_gateway.agents.claude import ClaudeAgent
-    from beaver_gateway.core.events import MessageStreamEvent
+    from beaver_gateway.conversations.kinds import Kind
+    from beaver_gateway.events.stream import MessageStreamEvent
 
 
 _log = logging.getLogger("beaver_gateway.backends.claude_sdk")
 
-# §3.7: in bypass the callback only ever sees AskUserQuestion, and that is
-# exactly the one we want - the SDK's warning about the rest is noise here.
 warnings.filterwarnings("ignore", category=CanUseToolShadowedWarning)
 
 ASK_TOOL = "AskUserQuestion"
 
 __all__ = [
+    "AuditSink",
     "ClaudeSdkBackend",
     "RunnerConfig",
     "SessionClient",
@@ -166,11 +155,12 @@ ClientFactory = "Callable[[ClaudeAgentOptions], SessionClient]"
 UsageSink = "Callable[[UsageEvent], Awaitable[None]]"
 ToolServerFactory = "Callable[[str, str], McpSdkServerConfig | None]"
 """``(conversation_key, kind) -> in-process MCP server config`` or ``None``."""
+AuditSink = "Callable[[policy_mod.ToolAudit], Awaitable[None]]"
+"""Receives every tool call the PreToolUse hook saw, allowed or denied."""
 Asker = "Callable[[str, dict[str, Any]], Awaitable[str]]"
 """``(conversation_key, AskUserQuestion input) -> text the model reads as the
 tool result``. The only channel an answer has in bypass mode is
-``PermissionResultDeny.message`` (spike S1, s05): ``updated_input`` never
+``PermissionResultDeny.message``: ``updated_input`` never reaches the model."""
-reaches the model."""
 
 
 @dataclass(frozen=True, slots=True)
@@ -218,8 +208,18 @@ class ClaudeSdkBackend:
         pool: SessionPool | None = None,
         tool_server: Callable[[str, str], McpSdkServerConfig | None] | None = None,
         asker: Callable[[str, dict[str, Any]], Awaitable[str]] | None = None,
+        audit_sink: Callable[[policy_mod.ToolAudit], Awaitable[None]] | None = None,
+        waker: Callable[[str, str], Coroutine[Any, Any, None]] | None = None,
     ) -> None:
+        """One backend per Claude agent.
+
+        ``waker(key, note)`` is called when a session starts a turn by itself
+        (a background task reported back); the caller then attaches.
+        """
         self._agent = agent
+        self.waker = waker
+        self._tasks: set[asyncio.Task[None]] = set()
+        self._audit_sink = audit_sink
         self._store = session_store
         self._runner = runner or RunnerConfig()
         self._usage_sink = usage_sink
@@ -272,13 +272,62 @@ class ClaudeSdkBackend:
     def live(self, key: str) -> Session | None:
         return self._pool.get(key)
 
-    async def repair_session(self, session_id: str) -> int:
+    def has_pending(self, key: str) -> bool:
+        """A turn the session started on its own is waiting for ``attach``."""
+        live = self._pool.get(key)
+        return live is not None and bool(live.pending)
+
+    def pending_note(self, key: str) -> str | None:
+        live = self._pool.get(key)
+        return live.note if live is not None else None
+
+    async def attach(
+        self,
+        *,
+        key: str,
+        capture: TurnCapture | None = None,
+        observer: Callable[[Any], None] | None = None,
+        turn_id: str | None = None,
+    ) -> AsyncIterator[MessageStreamEvent]:
+        """Consume the turn a live session started by itself as a normal turn.
+
+        The CLI runs one when a background task (a subagent) reports back:
+        no prompt goes out, the events are what the model said in reply to
+        the report, the turn ends on that result.
+        """
+        live = self._pool.get(key)
+        if live is None or not live.pending:
+            return
+        message_id = f"msg_{uuid.uuid4().hex}"
+        yield build_message_start(message_id=message_id, model=self._agent.model)
+        turn = _Turn()
+        async with live.lock:
+            live.running_turn = turn_id or message_id
+            live.last_used = time.monotonic()
+            async for event in self._run_turn(live, None, turn, observer, capture):
+                yield event
+            live.turns += 1
+            live.last_used = time.monotonic()
+            live.running_turn = None
+        usage, _ = await self._after_turn(
+            live, turn, conversation_id=key, history=[], capture=capture
+        )
+        yield build_message_delta(
+            stop_reason=turn.stop_reason, usage=_wire_usage(usage)
+        )
+        yield build_message_stop()
+
+    async def repair_session(
+        self, session_id: str, *, text: str = "interrupted"
+    ) -> int:
         """Close ``tool_use`` blocks a crash left without a result; count added."""
         key = self._store_key(session_id)
         entries = await self._store.load(cast("Any", key))
         if not entries:
             return 0
-        fixes = close_open_tool_uses(cast("list[Mapping[str, Any]]", entries))
+        fixes = close_open_tool_uses(
+            cast("list[Mapping[str, Any]]", entries), text=text
+        )
         if fixes:
             await self._store.append(cast("Any", key), cast("Any", fixes))
             _log.warning(
@@ -293,17 +342,31 @@ class ClaudeSdkBackend:
         *,
         agent: BaseAgent,
         messages: Iterable[MessageParam],
-        system: str | None = None,  # noqa: ARG002 - the agent owns its prompt
+        system: str | None = None,  # noqa: ARG002
         conversation_id: str | None = None,
         session_id: str | None = None,
+        reseed: bool = False,
         capture: TurnCapture | None = None,
         kind: str = "deep",
         pinned: bool = False,
         tools: bool = True,
         observer: Callable[[Any], None] | None = None,
         turn_id: str | None = None,
-        **options: Any,  # noqa: ARG002 - per-request knobs are not supported
+        **options: Any,  # noqa: ARG002
     ) -> AsyncIterator[MessageStreamEvent]:
+        """Run one turn against ``agent``, yielding Anthropic stream events.
+
+        Sessions are keyed by ``conversation_id`` when given, else a
+        text-only fingerprint of ``messages[:-1]``. Without a live session,
+        resumes ``session_id`` (closing any ``tool_use`` a crash left open),
+        or seeds ``messages[:-1]`` via ``backends/transcript.py`` and resumes
+        that. ``kind`` picks the prompt assembly and pool TTL; ``pinned``
+        sessions are never evicted; ``tools=False`` mounts no MCP servers
+        (forks and jobs); ``observer`` sees every raw SDK message.
+
+        A resumed session that dies before any event reached the caller is
+        reseeded from history and retried once.
+        """
         if agent.name != self._agent.name:
             msg = f"backend bound to {self._agent.name!r}, got {agent.name!r}"
             raise ValueError(msg)
@@ -311,11 +374,13 @@ class ClaudeSdkBackend:
         if not history or history[-1].get("role") != "user":
             msg = "the last message must be a user turn"
             raise ValueError(msg)
-        prompt = _prompt_text(history[-1].get("content"))
+        prompt = _prompt(history[-1].get("content"))
         prior = history[:-1]
         key = conversation_id or fingerprint(prior)
         spec = _SessionSpec(kind=kind, pinned=pinned, tools=tools)
-        live = await self._acquire(key, session_id=session_id, history=prior, spec=spec)
+        live = await self._acquire(
+            key, session_id=session_id, history=prior, spec=spec, reseed=reseed
+        )
         message_id = f"msg_{uuid.uuid4().hex}"
         yield build_message_start(message_id=message_id, model=self._agent.model)
         turn = _Turn()
@@ -323,8 +388,6 @@ class ClaudeSdkBackend:
             live.running_turn = turn_id or message_id
             live.last_used = time.monotonic()
             try:
-                # Events go out as the CLI produces them: the frontends
-                # stream text and thinking live, the turn is not buffered.
                 async for event in self._run_turn(
                     live, prompt, turn, observer, capture
                 ):
@@ -332,8 +395,6 @@ class ClaudeSdkBackend:
             except Exception:
                 live.running_turn = None
                 await self._pool.close(key)
-                # A dead resume can be reseeded from history, but only
-                # while nothing of this turn has reached the caller yet.
                 if not (live.resumed and live.turns == 0) or turn.events:
                     raise
                 _log.exception(
@@ -380,7 +441,7 @@ class ClaudeSdkBackend:
             live.session_id = turn.result.session_id
         if conversation_id is None:
             self._rekey(live.key, fingerprint([*history, *turn.synthesized]))
-        usage = _usage_of(turn.result)
+        usage = _usage_of(turn.result, context_tokens=turn.context_tokens)
         interrupted = live.interrupt_requested
         live.interrupt_requested = False
         if capture is not None:
@@ -404,27 +465,84 @@ class ClaudeSdkBackend:
     async def _run_turn(
         self,
         live: Session,
-        prompt: str,
+        prompt: str | list[dict[str, Any]] | None,
         turn: _Turn,
         observer: Callable[[Any], None] | None = None,
         capture: TurnCapture | None = None,
     ) -> AsyncIterator[MessageStreamEvent]:
-        """Run one prompt, yielding wire events as they arrive.
+        """Run one prompt, or attach to a self-started one, yielding events.
 
         ``turn`` is filled in place (result, synthesized history, count of
         events already yielded) so the caller can finish bookkeeping - and
         decide whether a retry is still possible - after a failure. The
         session id lands in ``capture`` with the first frame, so a turn cut
         by a restart still leaves a resumable session behind.
+
+        A result whose ``origin`` is not the human's ends a turn the CLI ran
+        on its own; inside a prompted turn it is passed over, the events it
+        came with stay in this turn rather than getting lost.
         """
-        streaming = self._agent.options.include_partial_messages
         raw: list[Any] = []
-        next_index = 0
+        cursor = _Cursor()
-        offset = 0
+        live.observer = observer
-        await live.client.query(prompt)
+        live.attached = True
-        async for message in live.client.receive_response():
+        for queued in live.pending:
+            live.inbox.put_nowait(queued)
+        live.pending.clear()
+        try:
+            if prompt is not None:
+                await live.client.query(
+                    prompt if isinstance(prompt, str) else _stream(prompt)
+                )
+            while True:
+                message = await live.inbox.get()
+                if message is _END:
+                    if prompt is not None:
+                        msg = f"claude exited before answering ({live.session_id})"
+                        raise RuntimeError(msg)
+                    break
+                if isinstance(message, BaseException):
+                    raise message
                 if observer is not None:
                     observer(message)
+                if not self._note(live, message, capture):
+                    continue
+                if isinstance(message, ResultMessage):
+                    if prompt is not None and _self_started(message):
+                        _log.info(
+                            "session %s: a self-started turn ended inside a "
+                            "prompted one, folded in",
+                            live.session_id,
+                        )
+                        continue
+                    turn.result = message
+                    turn.stop_reason = _STOP_REASONS.get(
+                        message.stop_reason or "", "end_turn"
+                    )
+                    break
+                for out in self._emit(message, turn, cursor, raw):
+                    turn.events += 1
+                    yield out
+            if turn.events == 0:
+                for out in _emit_whole(raw, cursor):
+                    turn.events += 1
+                    yield out
+        finally:
+            live.attached = False
+            live.woken = False
+        turn.synthesized = synthesize_turn_messages(raw)
+        _log.info(
+            "turn: agent=%s session=%s events=%d synthesized=%d stop=%s",
+            self._agent.name,
+            live.session_id,
+            turn.events,
+            len(turn.synthesized),
+            turn.stop_reason,
+        )
+
+    @staticmethod
+    def _note(live: Session, message: Any, capture: TurnCapture | None) -> bool:
+        """Session bookkeeping for one message; False if not the main thread's."""
         session_id = getattr(message, "session_id", None)
         if isinstance(session_id, str) and session_id and live.session_id is None:
             live.session_id = session_id
@@ -437,45 +555,72 @@ class ClaudeSdkBackend:
                 live.session_id,
                 message.error,
             )
-                continue
+            return False
-            if getattr(message, "parent_tool_use_id", None) is not None:
+        if isinstance(message, TaskNotificationMessage):
-                continue
+            live.note = _note_of(message)
+            return False
+        return getattr(message, "parent_tool_use_id", None) is None
+
+    def _emit(
+        self, message: Any, turn: _Turn, cursor: _Cursor, raw: list[Any]
+    ) -> Iterable[MessageStreamEvent]:
+        streaming = self._agent.options.include_partial_messages
         if isinstance(message, StreamEvent):
             event = message.event
             if event.get("type") == "message_start":
-                    offset = next_index
+                cursor.offset = cursor.next_index
-                    continue
+                turn.context_tokens = _context_of(event.get("message"))
+                return
             index = event.get("index")
             if isinstance(index, int):
-                    next_index = max(next_index, offset + index + 1)
+                cursor.next_index = max(cursor.next_index, cursor.offset + index + 1)
                 if streaming:
-                        for out in _emit_stream_event(event, offset + index):
+                    yield from _emit_stream_event(event, cursor.offset + index)
-                            turn.events += 1
-                            yield out
         elif isinstance(message, AssistantMessage):
             raw.append(message)
             if not streaming:
                 for block in message.content:
-                        for out in _emit_block(block, next_index):
+                    yield from _emit_block(block, cursor.next_index)
-                            turn.events += 1
+                    cursor.next_index += 1
-                            yield out
-                        next_index += 1
         elif isinstance(message, UserMessage):
             raw.append(message)
-            elif isinstance(message, ResultMessage):
+
-                turn.result = message
+    async def _read(self, live: Session) -> None:
-                turn.stop_reason = _STOP_REASONS.get(
+        """Read the client for the session's whole life.
-                    message.stop_reason or "", "end_turn"
+
-                )
+        During a turn every message goes to the turn's inbox. Between turns
-        turn.synthesized = synthesize_turn_messages(raw)
+        a subagent still running is shown to the last observer, and the
-        _log.info(
+        first frame of the main thread means the CLI started a turn by
-            "turn: agent=%s session=%s events=%d synthesized=%d stop=%s",
+        itself: it is buffered in ``pending`` and the waker is told once.
-            self._agent.name,
+        """
-            live.session_id,
+        try:
-            turn.events,
+            async for message in live.client.receive_messages():
-            len(turn.synthesized),
+                if live.attached:
-            turn.stop_reason,
+                    live.inbox.put_nowait(message)
-        )
+                    continue
+                if isinstance(message, TaskNotificationMessage):
+                    live.note = _note_of(message)
+                if _main_thread(message):
+                    live.pending.append(message)
+                    if not live.woken:
+                        live.woken = True
+                        self._wake(live)
+                elif live.observer is not None:
+                    live.observer(message)
+            live.inbox.put_nowait(_END)
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:  # noqa: BLE001
+            _log.error("session %s: reader died: %s", live.session_id, exc)
+            live.dirty = True
+            live.inbox.put_nowait(exc)
+
+    def _wake(self, live: Session) -> None:
+        if self.waker is None:
+            return
+        task = asyncio.create_task(self.waker(live.key, live.note or ""))
+        self._tasks.add(task)
+        task.add_done_callback(self._tasks.discard)
 
     async def _acquire(
         self,
@@ -484,10 +629,13 @@ class ClaudeSdkBackend:
         session_id: str | None,
         history: list[dict[str, Any]],
         spec: _SessionSpec,
+        reseed: bool = False,
     ) -> Session:
         live = self._pool.get(key)
         if live is not None:
+            if not reseed:
                 return live
+            await self._pool.close(key)
         resume = session_id
         if resume is not None:
             await self.repair_session(resume)
@@ -537,7 +685,7 @@ class ClaudeSdkBackend:
             spec.tools,
             self._runner.user,
         )
-        return Session(
+        live = Session(
             key=key,
             agent=self._agent.name,
             kind=spec.kind,
@@ -546,6 +694,8 @@ class ClaudeSdkBackend:
             resumed=resume is not None,
             pinned=spec.pinned,
         )
+        live.reader = asyncio.create_task(self._read(live))
+        return live
 
     def _default_factory(self, options: ClaudeAgentOptions) -> SessionClient:
         return _RunnerClient(options, uid=self._uid)
@@ -559,8 +709,9 @@ class ClaudeSdkBackend:
         if self._runner.home is not None:
             env["HOME"] = str(self._runner.home)
             env.setdefault("CLAUDE_CONFIG_DIR", str(self._runner.home / ".claude"))
-        plugins = self._plugins()
+        kind = as_kind(spec.kind)
-        sources = agent.prompt_for(as_kind(spec.kind))
+        plugins = self._plugins(kind)
+        sources = agent.prompt_for(kind)
         system_prompt = (
             prompt_assembly.assemble(sources) if sources else agent.system_prompt
         )
@@ -588,6 +739,7 @@ class ClaudeSdkBackend:
             cli_path=str(self._exec_wrapper(extra_keep=tuple(env))),
             include_partial_messages=opt.include_partial_messages,
             can_use_tool=self._can_use_tool(key) if self._asker else None,
+            hooks=self._hooks(key, spec),
             session_store=self._store,
             session_store_flush=cast("Any", opt.session_store_flush),
             resume=resume,
@@ -604,6 +756,12 @@ class ClaudeSdkBackend:
     ) -> Callable[
         [str, dict[str, Any], ToolPermissionContext], Awaitable[PermissionResult]
     ]:
+        """Build the ``can_use_tool`` callback for one session.
+
+        In bypass mode the SDK only ever calls this back for
+        ``AskUserQuestion``; the warning about the rest is suppressed at
+        import time.
+        """
         asker = self._asker
 
         async def can_use_tool(
@@ -623,10 +781,54 @@ class ClaudeSdkBackend:
 
         return can_use_tool
 
-    def _plugins(self) -> list[dict[str, str]]:
+    def _hooks(
+        self, key: str, spec: _SessionSpec
+    ) -> dict[HookEvent, list[HookMatcher]] | None:
+        """One in-process ``PreToolUse`` hook: policy rules, then audit."""
+        agent = self._agent
+        if not agent.policy and self._audit_sink is None:
+            return None
+
+        async def pre_tool_use(
+            hook_input: Any, _tool_use_id: str | None, _ctx: Any
+        ) -> dict[str, Any]:
+            live = self._pool.get(key)
+            call = policy_mod.ToolCall(
+                tool=str(hook_input.get("tool_name", "")),
+                input=hook_input.get("tool_input") or {},
+                agent=agent.name,
+                kind=spec.kind,
+                conversation=key,
+                cwd=agent.cwd,
+                state=live.state if live is not None else {},
+            )
+            deny = await policy_mod.evaluate(agent.policy, call)
+            if deny is not None:
+                _log.info(
+                    "policy: %s denied %s: %s", agent.name, call.tool, deny.reason
+                )
+            if self._audit_sink is not None:
+                audit = policy_mod.ToolAudit(
+                    agent=agent.name,
+                    conversation=key,
+                    kind=spec.kind,
+                    tool=call.tool,
+                    decision="deny" if deny else "allow",
+                    reason=deny.reason if deny else None,
+                    brief=policy_mod.brief(call.input),
+                )
+                try:
+                    await self._audit_sink(audit)
+                except Exception:  # noqa: BLE001
+                    _log.exception("tool audit failed for %s", call.tool)
+            return policy_mod.hook_output(deny)
+
+        return {"PreToolUse": [HookMatcher(hooks=[cast("Any", pre_tool_use)])]}
+
+    def _plugins(self, kind: Kind) -> list[dict[str, str]]:
         plugins: list[dict[str, str]] = []
-        root = self._work_dir / "plugins" / self._agent.name
+        root = self._work_dir / "plugins" / self._agent.name / kind
-        for raw in sorted(self._agent.skill_sets, key=str):
+        for raw in sorted(self._agent.skills_for(kind), key=str):
             source = Path(str(raw))
             name = source.name
             target = root / name
@@ -642,6 +844,12 @@ class ClaudeSdkBackend:
         return plugins
 
     def _exec_wrapper(self, *, extra_keep: tuple[str, ...]) -> Path:
+        """Path to a generated wrapper that execs claude with a whitelisted env.
+
+        Drops every inherited variable outside the whitelist and, when
+        ``RunnerConfig.user`` is set, switches to that uid before exec - done
+        here rather than via ``subprocess(user=...)``, which uvloop rejects.
+        """
         if self._wrapper is not None:
             return self._wrapper
         keep = sorted({*ENV_KEEP, *self._agent.options.env_keep, *extra_keep})
@@ -677,10 +885,22 @@ class _SessionSpec:
     tools: bool
 
 
+_END = object()
+
+
+@dataclass
+class _Cursor:
+    next_index: int = 0
+    offset: int = 0
+
+
 @dataclass
 class _Turn:
     events: int = 0
     """Wire events already yielded to the caller."""
+
+    context_tokens: int = 0
+    """Input size of the latest API call (``message_start`` usage)."""
     synthesized: list[dict[str, Any]] = field(default_factory=list)
     result: ResultMessage | None = None
     stop_reason: StopReason = "end_turn"
@@ -780,14 +1000,54 @@ def _mcp_disallowed(
     return out
 
 
-def _prompt_text(content: Any) -> str:
+def _prompt(content: Any) -> str | list[dict[str, Any]]:
+    """Plain text when the turn is text only; the block list when images ride along."""
     text = text_of(content)
     if not text:
         msg = "user message has no text content"
         raise ValueError(msg)
+    if isinstance(content, list) and any(
+        isinstance(b, dict) and b.get("type") != "text" for b in content
+    ):
+        return [dict(b) for b in content if isinstance(b, dict)]
     return text
 
 
+async def _stream(content: list[dict[str, Any]]) -> AsyncIterator[dict[str, Any]]:
+    yield {
+        "type": "user",
+        "message": {"role": "user", "content": content},
+        "parent_tool_use_id": None,
+    }
+
+
+def _emit_whole(raw: Iterable[Any], cursor: _Cursor) -> Iterable[MessageStreamEvent]:
+    """Blocks of a turn that streamed no deltas, e.g. one reported whole."""
+    for message in raw:
+        if isinstance(message, AssistantMessage):
+            for block in message.content:
+                yield from _emit_block(block, cursor.next_index)
+                cursor.next_index += 1
+
+
+def _self_started(result: ResultMessage) -> bool:
+    origin = result.origin
+    return origin is not None and origin.get("kind") != "human"
+
+
+def _main_thread(message: Any) -> bool:
+    if getattr(message, "parent_tool_use_id", None) is not None:
+        return False
+    return isinstance(
+        message, (StreamEvent, AssistantMessage, UserMessage, ResultMessage)
+    )
+
+
+def _note_of(message: TaskNotificationMessage) -> str:
+    summary = message.summary or message.data.get("description") or message.task_id
+    return f"{summary} ({message.status})"
+
+
 def synthesize_turn_messages(raw: Iterable[Any]) -> list[dict[str, Any]]:
     out: list[dict[str, Any]] = []
     for message in raw:
@@ -836,11 +1096,23 @@ def _block_to_dict(block: Any) -> dict[str, Any]:
     raise TypeError(msg)
 
 
-def _usage_of(result: ResultMessage | None) -> TurnUsage:
+def _context_of(message: Any) -> int:
+    usage = message.get("usage") if isinstance(message, dict) else None
+    if not isinstance(usage, dict):
+        return 0
+    return (
+        _int(usage.get("input_tokens"))
+        + _int(usage.get("cache_read_input_tokens"))
+        + _int(usage.get("cache_creation_input_tokens"))
+    )
+
+
+def _usage_of(result: ResultMessage | None, *, context_tokens: int = 0) -> TurnUsage:
     if result is None:
-        return TurnUsage()
+        return TurnUsage(context_tokens=context_tokens)
     usage = result.usage or {}
     return TurnUsage(
+        context_tokens=context_tokens,
         input_tokens=_int(usage.get("input_tokens")),
         output_tokens=_int(usage.get("output_tokens")),
         cache_read_tokens=_int(usage.get("cache_read_input_tokens")),

src/beaver_gateway/backends/raycast.py

@@ -1,32 +1,8 @@
 """Raycast backend adapter.
 
-Translates between Anthropic's ``/v1/messages`` wire vocabulary (incoming
+Translates between Anthropic's ``/v1/messages`` wire vocabulary and the
-``MessageParam`` history, outgoing ``MessageStreamEvent`` SSE) and the
+``raycast-api`` SDK, splicing MCP tools into Raycast's ``tool_calls`` and
-``raycast-api`` SDK (``Message`` history, ``ChatStreamChunk`` SSE).
+routing them back in-process where the agent declares ``expose_mcps``.
-
-Two halves live here:
-
-* :func:`_to_raycast_messages` — pure conversion of an Anthropic message
-  list into ``list[raycast_api.Message]``. ``tool_result`` blocks carry no
-  tool name in Anthropic; we recover it by remembering each ``tool_use``
-  id we saw upstream.
-* :meth:`RaycastBackend.complete` — opens a ``client.chat.stream`` and
-  walks chunks through a tiny block-state machine. The state machine
-  exists only because Raycast streams ``tool_calls`` in three phases
-  (open with id+name, deltas with empty id, final summary with the full
-  ``arguments``) — Anthropic wants one ``content_block_start`` → deltas
-  → ``content_block_stop`` per block, so we de-duplicate the final
-  summary against the per-delta increments already emitted.
-
-MCP wiring: Raycast has no native MCP concept, so when an agent declares
-``expose_mcps`` we splice each MCP's tools into the wire request as
-``Tool.local(name=f"{mcp}__{tool}", ...)`` and run a gateway-internal
-loop. Every time the model emits a tool_call for one of those local
-tools we route it back to the underlying MCP in-process, append the
-result as a ``tool`` message, and re-issue the stream — all inside one
-Anthropic envelope (one ``message_start`` … one ``message_stop``). The
-tool_use blocks DO surface to the caller (mirrors what
-``ClaudeSdkBackend`` does), but tool_results stay internal.
 """
 
 from __future__ import annotations
@@ -42,7 +18,7 @@ from raycast_api import Message as RaycastMessage
 from raycast_api import RemoteTool, Tool, ToolCall
 
 from beaver_gateway.agents.raycast import RaycastAgent
-from beaver_gateway.core.events import (
+from beaver_gateway.events.stream import (
     StopReason,
     build_content_block_stop,
     build_input_json_delta,
@@ -65,7 +41,7 @@ if TYPE_CHECKING:
     from raycast_api import ChatStreamChunk, Client
 
     from beaver_gateway.agents.base import BaseAgent
-    from beaver_gateway.core.events import MessageStreamEvent
+    from beaver_gateway.events.stream import MessageStreamEvent
 else:
     from collections.abc import Mapping
 
@@ -76,11 +52,9 @@ __all__ = ["RaycastBackend"]
 _log = logging.getLogger("beaver_gateway.backends.raycast")
 
 
-# Cap on consecutive tool-call turns inside one Anthropic envelope.
-# Real conversations rarely chain more than a handful; the limit only
-# fires on a model that loops, and surfaces as a clean ``end_turn``
-# with an error tool_result rather than a hang.
 _MAX_TOOL_TURNS = 20
+"""Cap on consecutive tool-call turns inside one Anthropic envelope; a model
+that loops hits this and gets a clean ``end_turn`` instead of a hang."""
 
 
 _RAYCAST_TO_ANTHROPIC_STOP: dict[str, StopReason] = {
@@ -392,7 +366,7 @@ class _BlockState:
 
     def __init__(self) -> None:
         self.index: int = -1
-        self.kind: str | None = None  # "text" | "thinking" | "tool_use" | None
+        self.kind: str | None = None
         self.tool_id_to_block: dict[str, int] = {}
         self.tool_idx_to_id: dict[int, str] = {}
 
@@ -428,11 +402,14 @@ class RaycastBackend:
         self._client = client
         self._mcp_servers: Mapping[str, FastMCP] = mcp_servers or {}
         self._mcp_tools: Mapping[str, list[FastMCPTool]] = mcp_tools or {}
-        # Cached per-agent catalog — agents are immutable, so a single
-        # render at first use covers the gateway's lifetime.
         self._agent_catalog: dict[str, _AgentToolCatalog] = {}
 
     def _catalog_for(self, agent: RaycastAgent) -> _AgentToolCatalog:
+        """Build (or reuse) the tool catalog for ``agent``.
+
+        Agents are immutable, so a single render at first use covers the
+        gateway's lifetime.
+        """
         cached = self._agent_catalog.get(agent.name)
         if cached is not None:
             return cached
@@ -448,31 +425,26 @@ class RaycastBackend:
         system: str | None = None,
         **options: Any,
     ) -> AsyncIterator[MessageStreamEvent]:
+        """Run one turn against ``agent``, yielding Anthropic stream events.
+
+        On the wire Raycast uses ``system_instructions`` as a format marker
+        (``"markdown"``/``"plain"``, filled from the source default when we
+        pass ``None``) and ``additional_system_instructions`` for the actual
+        prompt content; ``system`` (or ``agent.system_prompt``) flows into
+        the latter.
+        """
         if not isinstance(agent, RaycastAgent):
             msg = f"RaycastBackend requires RaycastAgent, got {type(agent).__name__}"
             raise TypeError(msg)
 
         raycast_messages = _to_raycast_messages(messages)
         catalog = self._catalog_for(agent)
-        # Native remote tools + spliced MCP locals. ``None`` keeps the
-        # SDK from sending a ``tools`` field at all when neither is
-        # declared.
         tools_arg: list[Tool | RemoteTool | str] | None = (
             list(catalog.tools) if catalog.tools else None
         )
 
-        # On the wire Raycast uses ``system_instructions`` as a format
-        # marker (``"markdown"`` for AI_CHAT, ``"plain"`` otherwise —
-        # filled in by the SDK from the source default when we pass
-        # ``None``) and ``additional_system_instructions`` as the actual
-        # prompt content. So our ``system_prompt`` (or the per-request
-        # Anthropic ``system``, if present) flows into the *additional*
-        # slot. The SDK still prepends ``<user-preferences>`` to whatever
-        # we hand it via ``_build_preamble``.
         prompt_content = system if system is not None else agent.system_prompt
 
-        # Per-request options win over agent defaults; agent defaults
-        # win over Raycast SDK defaults. ``None`` means "fall back".
         async for event in self._stream(
             agent=agent,
             raycast_messages=raycast_messages,
@@ -499,12 +471,16 @@ class RaycastBackend:
         reasoning_effort: str | None,
         tool_choice: str | None,
     ) -> AsyncIterator[MessageStreamEvent]:
+        """Yield one Anthropic envelope spanning one or more ``chat.stream`` calls.
+
+        A tool_call not in ``mcp_routing`` is left to bubble out as a
+        regular ``tool_use`` block instead, for the caller to answer with a
+        ``tool_result`` the usual way.
+        """
         message_id = f"msg_{uuid.uuid4().hex}"
         yield build_message_start(message_id=message_id, model=agent.model)
 
         state = _BlockState()
-        # ``working_messages`` is the rolling history fed back to
-        # Raycast as we resolve MCP tool_calls turn by turn.
         working_messages = list(raycast_messages)
         last_usage: dict[str, int] | None = None
         last_finish: str | None = None
@@ -517,9 +493,6 @@ class RaycastBackend:
                 model=agent.model,
                 messages=working_messages,
                 source=agent.source,
-                # ``system_instructions=None`` → SDK substitutes the
-                # source default (``"markdown"`` / ``"plain"``). Real
-                # prompt goes into ``additional_system_instructions``.
                 additional_system_instructions=prompt_content,
                 user_preferences=agent.user_preferences,
                 tools=tools,
@@ -540,27 +513,16 @@ class RaycastBackend:
             if acc.usage:
                 last_usage = acc.usage
 
-            # Figure out which (if any) tool_calls land on our MCP
-            # routing table. Anything not in the table is left to bubble
-            # out of the envelope as a regular tool_use block — the
-            # Anthropic caller can then respond with a tool_result the
-            # usual way, and the next ``complete`` invocation will
-            # carry it back in.
             pending_mcp_calls = [
                 tid for tid in acc.tool_order if acc.tool_names.get(tid) in mcp_routing
             ]
             if not pending_mcp_calls:
                 break
 
-            # Close whatever block is still open before we step into
-            # tool execution — the next turn's chunks start a fresh
-            # block sequence.
             if state.kind is not None:
                 yield build_content_block_stop(state.index)
                 state.kind = None
 
-            # Echo the assistant turn so Raycast sees its own reply +
-            # tool_calls in subsequent context.
             assistant_text = "".join(acc.text_parts)
             assistant_tool_calls = [
                 ToolCall(
@@ -576,10 +538,6 @@ class RaycastBackend:
                 )
             )
 
-            # Dispatch each MCP-routed call and append a ``tool``
-            # message. Calls not in the routing table get a placeholder
-            # error so the model can correct itself rather than the
-            # gateway hanging the conversation.
             for tid in acc.tool_order:
                 tool_name = acc.tool_names.get(tid, "")
                 args_str = "".join(acc.tool_args.get(tid, [])) or "{}"
@@ -588,16 +546,12 @@ class RaycastBackend:
                         tool_name=tool_name, args_json=args_str, mcp_routing=mcp_routing
                     )
                 else:
-                    # Non-MCP tool — shouldn't really happen because we
-                    # haven't surfaced any other locals, but defend.
                     result_text = f"Tool {tool_name!r} is not handled by the gateway."
                 working_messages.append(
                     RaycastMessage.tool(
                         tool_call_id=tid, name=tool_name, result=result_text
                     )
                 )
-
-            # Loop: re-stream with the new history.
         else:
             _log.warning(
                 "raycast tool-call loop hit %d-turn cap for agent %r; "
@@ -606,7 +560,6 @@ class RaycastBackend:
                 agent.name,
             )
 
-        # Close whatever block is still open before the final delta.
         if state.kind is not None:
             yield build_content_block_stop(state.index)
             state.kind = None
@@ -716,6 +669,12 @@ class RaycastBackend:
         the final-summary chunk's arguments string is dropped because the
         deltas already streamed it.
 
+        Providers disagree on how ``arguments`` arrives: streaming ones
+        (GPT) send deltas across chunks and then restate the full string in
+        a final summary chunk (skip it, already streamed); non-streaming
+        ones (Gemini) send it only in that final summary (emit it once,
+        since nothing streamed it first).
+
         Side-effects on ``acc`` mirror what gets emitted to the wire so
         the gateway can rebuild a full ``ToolCall`` for the next Raycast
         turn (it needs the joined ``arguments`` JSON string, which the
@@ -728,9 +687,6 @@ class RaycastBackend:
             raw_tc = raw_tcs[i] if i < len(raw_tcs) else {}
             idx_field = raw_tc.get("index") if isinstance(raw_tc, dict) else None
 
-            # Resolve this entry to a tool-id key, mirroring
-            # `raycast_api.ChatResult._merge_tool_calls`. Phase 1 carries
-            # id+index, phase 2 only index, phase 3 only id.
             tool_id: str | None = None
             if tc.id:
                 tool_id = tc.id
@@ -743,7 +699,6 @@ class RaycastBackend:
 
             block_idx = state.tool_id_to_block.get(tool_id)
             if block_idx is None:
-                # New tool_use block. Close any open text/thinking block first.
                 if state.kind is not None:
                     events.append(build_content_block_stop(state.index))
                 state.index += 1
@@ -756,22 +711,11 @@ class RaycastBackend:
                         block_idx, tool_use_id=tool_id, name=tc.name or ""
                     )
                 )
-                # Streaming providers (GPT) deliver arguments as deltas
-                # across chunks and re-state the full string in a final
-                # summary chunk; non-streaming-args providers (Gemini)
-                # only send args in the final summary. Emit args in
-                # both cases when this is the first appearance — final
-                # summary then IS the full string.
                 if tc.arguments:
                     events.append(build_input_json_delta(block_idx, tc.arguments))
                     acc.add_tool_args(tool_id, tc.arguments)
                 continue
 
-            # Existing block. Final summary chunks restate the full args
-            # string; if we already streamed deltas, that restatement is
-            # a duplicate (skip). If we streamed nothing (the streaming
-            # provider didn't send mid-arg deltas — Gemini path again),
-            # the summary IS the args — emit it once.
             if is_final_summary:
                 if tc.arguments and not acc.tool_args.get(tool_id):
                     events.append(build_input_json_delta(block_idx, tc.arguments))

src/beaver_gateway/backends/sessions.py

@@ -1,13 +1,9 @@
-"""Pool of live Agent SDK sessions across every Claude agent (§3.2).
+"""Pool of live Agent SDK sessions across every Claude agent.
 
-One :class:`Session` is one ``ClaudeSDKClient`` (one claude subprocess).
+One :class:`Session` is one ``ClaudeSDKClient`` (one claude subprocess). The
-The pool owns the two decisions the adapters used to make on their own:
+pool decides when a session is closed for idleness (TTL by conversation
-when a session is closed for idleness (TTL by conversation kind) and
+kind) and which one goes when memory runs out (RSS of the subprocess tree
-which one goes when memory runs out (measured RSS of the subprocess tree
+against the cgroup limit, or ``max_live`` with no limit).
-against the cgroup limit, ``max_live`` where there is no limit). Eviction
-only ever picks ``idle && !running_turn && !pending_question`` sessions
-that are neither pinned (the master) nor ``dirty`` (mirror gap not yet
-repaired); forks and jobs go first.
 """
 
 from __future__ import annotations
@@ -24,11 +20,17 @@ from typing import TYPE_CHECKING, Any, Protocol
 import psutil
 
 if TYPE_CHECKING:
-    from collections.abc import AsyncIterator, Iterator, Mapping
+    from collections.abc import (
+        AsyncIterable,
+        AsyncIterator,
+        Callable,
+        Iterator,
+        Mapping,
+    )
 
 __all__ = ["DEFAULT_TTL", "Session", "SessionClient", "SessionPool", "cgroup_limit"]
 
-_log = logging.getLogger("beaver_gateway.core.sessions")
+_log = logging.getLogger("beaver_gateway.backends.sessions")
 
 DEFAULT_TTL: Mapping[str, float | None] = {
     "master": None,
@@ -45,8 +47,8 @@ _RSS_HEADROOM = 0.8
 
 class SessionClient(Protocol):
     async def connect(self) -> None: ...
-    async def query(self, prompt: str) -> None: ...
+    async def query(self, prompt: str | AsyncIterable[dict[str, Any]]) -> None: ...
-    def receive_response(self) -> AsyncIterator[Any]: ...
+    def receive_messages(self) -> AsyncIterator[Any]: ...
     async def interrupt(self) -> None: ...
     async def disconnect(self) -> None: ...
 
@@ -68,6 +70,22 @@ class Session:
     last_used: float = field(default_factory=time.monotonic)
     created_at: float = field(default_factory=time.monotonic)
     turns: int = 0
+    state: dict[str, Any] = field(default_factory=dict)
+    """Scratch for policy rules (``agents/policy.py``); dies with the process."""
+
+    reader: asyncio.Task[None] | None = None
+    """Reads the client for the session's whole life, not only during a turn."""
+    inbox: asyncio.Queue[Any] = field(default_factory=asyncio.Queue)
+    """Where the reader puts messages while a turn is attached."""
+    pending: list[Any] = field(default_factory=list)
+    """A turn the CLI started on its own (a background task reported back),
+    buffered until a consumer attaches."""
+    attached: bool = False
+    woken: bool = False
+    note: str | None = None
+    """Summary of the last task notification, the pending turn's prompt."""
+    observer: Callable[[Any], None] | None = None
+    """The last turn's observer; sees subagent traffic between turns."""
 
     @property
     def busy(self) -> bool:
@@ -75,6 +93,10 @@ class Session:
 
     @property
     def evictable(self) -> bool:
+        """Never evict a pinned (master) session or a ``dirty`` one.
+
+        ``dirty`` means a mirror gap not yet repaired.
+        """
         return not (self.pinned or self.dirty or self.busy or self.pending_question)
 
     @property
@@ -165,6 +187,7 @@ class SessionPool:
         return len(self._sessions) >= self._max_live
 
     def victims(self) -> list[Session]:
+        """Evictable sessions, forks/jobs first, then oldest idle."""
         candidates = [s for s in self._sessions.values() if s.evictable]
         candidates.sort(key=lambda s: (_EVICT_ORDER.get(s.kind, 1), s.last_used))
         return candidates
@@ -189,6 +212,8 @@ class SessionPool:
         if session is None:
             return
         _log.info("closing session %s (%s, %s)", session.session_id, session.kind, key)
+        if session.reader is not None and session.reader is not asyncio.current_task():
+            session.reader.cancel()
         try:
             await session.client.disconnect()
         except Exception:  # noqa: BLE001
@@ -235,6 +260,7 @@ class SessionPool:
                 "turns": s.turns,
                 "busy": s.busy,
                 "running_turn": s.running_turn,
+                "pending": len(s.pending),
                 "pending_question": s.pending_question,
                 "pinned": s.pinned,
                 "dirty": s.dirty,

src/beaver_gateway/backends/transcript.py

@@ -1,16 +1,7 @@
 """Anthropic messages <-> Agent SDK transcript entries.
 
-:func:`build_entries` renders a message list as the entries the Claude CLI
+:func:`build_entries` renders a message list as entries the Claude CLI
-itself writes (reference: ``t/spike_sdk/entries_reference.json``, CLI
+itself writes; :func:`messages_from_entries` is the projection back.
-2.1.248 via ``import_session_to_store``): one ``user`` entry per prompt,
-one ``assistant`` entry per content block sharing a message id, one
-``user`` entry per ``tool_result`` parented on the matching ``tool_use``
-entry. Only ``user``/``assistant`` entries are produced - no attachments,
-titles or queue markers. Appending the result to a session store and
-resuming that session id seeds an external history into the SDK.
-
-:func:`messages_from_entries` is the projection back, used by tests and by
-anything that needs Anthropic-shape history out of a mirrored transcript.
 """
 
 from __future__ import annotations
@@ -22,7 +13,9 @@ from datetime import UTC, datetime
 from typing import TYPE_CHECKING, Any
 
 try:
-    from claude_agent_sdk._cli_version import __cli_version__ as _cli_version
+    from claude_agent_sdk._cli_version import __cli_version__
+
+    _cli_version = str(__cli_version__)
 except ImportError:  # pragma: no cover
     _cli_version = "2.1.248"
 
@@ -59,6 +52,14 @@ def build_entries(
     permission_mode: str = "bypassPermissions",
     now: datetime | None = None,
 ) -> list[dict[str, Any]]:
+    """Render ``messages`` as entries a session store can resume from.
+
+    One ``user`` entry per prompt, one ``assistant`` entry per content
+    block sharing a message id, one ``user`` entry per ``tool_result``
+    parented on the matching ``tool_use``. Appending the result to a
+    session store and resuming that session id seeds external history
+    into the SDK.
+    """
     stamp = (now or datetime.now(UTC)).strftime("%Y-%m-%dT%H:%M:%S.") + (
         f"{(now or datetime.now(UTC)).microsecond // 1000:03d}Z"
     )
@@ -160,7 +161,10 @@ def build_entries(
     return entries
 
 
-def messages_from_entries(entries: Iterable[Mapping[str, Any]]) -> list[dict[str, Any]]:
+def messages_from_entries(
+    entries: Iterable[Mapping[str, Any]], *, with_ts: bool = False
+) -> list[dict[str, Any]]:
+    """Messages as the model saw them; ``with_ts`` adds when each one was written."""
     out: list[dict[str, Any]] = []
     last_message_id: str | None = None
     for entry in entries:
@@ -179,7 +183,13 @@ def messages_from_entries(entries: Iterable[Mapping[str, Any]]) -> list[dict[str
             ):
                 out[-1]["content"].extend(results)
             else:
-                out.append({"role": "user", "content": _user_content(content)})
+                message_out: dict[str, Any] = {
+                    "role": "user",
+                    "content": _user_content(content),
+                }
+                if with_ts:
+                    message_out["ts"] = entry.get("timestamp")
+                out.append(message_out)
             last_message_id = None
             continue
         blocks = _assistant_blocks(content)
@@ -192,7 +202,10 @@ def messages_from_entries(entries: Iterable[Mapping[str, Any]]) -> list[dict[str
         ):
             out[-1]["content"].extend(blocks)
         else:
-            out.append({"role": "assistant", "content": blocks})
+            message_out: dict[str, Any] = {"role": "assistant", "content": blocks}
+            if with_ts:
+                message_out["ts"] = entry.get("timestamp")
+            out.append(message_out)
         last_message_id = message_id
     return out
 
@@ -291,10 +304,8 @@ def _zero_usage() -> dict[str, Any]:
     }
 
 
-# ---- repair, windows, projections ---------------------------------------
-
 _PROMPT_TYPES = ("user", "assistant")
-_INTERRUPTED = "прервано"
+_INTERRUPTED = "interrupted"
 
 
 def open_tool_uses(

src/beaver_gateway/cli.py

@@ -1,424 +1,41 @@
-"""Process entrypoint.
+"""Process entrypoint: logging, signals, ``.env``, the config, then ``app.run``."""
-
-Phase 1.4 — async ``main``: install uvloop, load the user config, build
-registries + per-agent backends (only ``RaycastBackend`` so far), wire
-each frontend with a ``GatewayRuntime``, and run all
-``frontend.serve()`` coroutines concurrently. Without any frontends we
-still print the Phase 0 DoD line and exit cleanly so the bare skeleton
-keeps working.
-
-Phase 2.1 — when the user declares any ``McpServer``, we additionally
-build the internal MCP aggregator app and run it on
-``127.0.0.1:INTERNAL_MCP_PORT`` as another task inside the same
-TaskGroup. URLs are surfaced through ``GatewayRuntime.mcp_internal_urls``
-so Phase 2.2's ClaudeCode adapter can find them.
-
-Phase 3 — the same aggregator backs the external ``McpServerFrontend``;
-``cli`` doesn't have to know that the frontend reverse-proxies into it,
-it just keeps the aggregator running for anyone who needs it.
-"""
 
 from __future__ import annotations
 
 import asyncio
 import contextlib
-import functools
 import logging
 import signal
-from contextlib import AsyncExitStack
-from typing import TYPE_CHECKING, Any
 
-import uvicorn
 import uvloop
 from dotenv import load_dotenv
-from raycast_api import Client as RaycastClient
-from raycast_api.config import Config as RaycastConfig
 
-from beaver_gateway import config_loader
+from beaver_gateway import app, config
-from beaver_gateway.agents.claude import ClaudeAgent
+from beaver_gateway.security.redact import install as install_redaction
-from beaver_gateway.agents.raycast import RaycastAgent
+from beaver_gateway.security.redact import load_secrets as load_secrets_to_mask
-from beaver_gateway.backends.claude_sdk import (
-    ClaudeSdkBackend,
-    RunnerConfig,
-    UsageEvent,
-)
-from beaver_gateway.backends.raycast import RaycastBackend
-from beaver_gateway.core.auth import TokenStore
-from beaver_gateway.core.bus import EventBus
-from beaver_gateway.core.conversations import Conversations
-from beaver_gateway.core.gateway_tools import build_tool_server
-from beaver_gateway.core.registry import AgentRegistry, McpRegistry
-from beaver_gateway.core.sessions import SessionPool
-from beaver_gateway.frontends.base import GatewayRuntime
-from beaver_gateway.mcp.internal_app import build_internal_app
 from beaver_gateway.settings import Settings
-from beaver_gateway.storage import Database, PostgresSessionStore, Usage, append_usage
-
-if TYPE_CHECKING:
-    from claude_agent_sdk import McpSdkServerConfig
-    from fastmcp import FastMCP
-    from fastmcp.tools.base import Tool as FastMCPTool
-    from starlette.applications import Starlette
-
-    from beaver_gateway.backends.base import Backend
-    from beaver_gateway.mcp.types import McpServerT
-
-
-_log = logging.getLogger("beaver_gateway.cli")
 
 
 def main() -> None:
-    """Sync wrapper: uvloop loop factory + asyncio.run."""
     logging.basicConfig(
         level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s"
     )
-    _install_sigterm_handler()
+    install_redaction()
-    asyncio.run(_async_main(), loop_factory=uvloop.new_event_loop)
+    _sigterm_as_interrupt()
+    asyncio.run(_run(), loop_factory=uvloop.new_event_loop)
 
 
-def _install_sigterm_handler() -> None:
+async def _run() -> None:
-    """Turn SIGTERM into a normal interpreter exit.
+    load_dotenv(override=False)
+    load_secrets_to_mask()
+    settings = Settings()  # ty: ignore[missing-argument]
+    gateway = config.load(settings.config_path)
+    await app.run(gateway, settings)
 
-    Python's default SIGTERM disposition kills the process outright, so
-    neither ``AsyncExitStack`` unwinding nor ``atexit`` hooks run. That
-    matters because every ``claude`` we spawn lives in its own session
-    (ptyprocess calls ``setsid``), which makes it immune to the signal
-    that took us down — a hard SIGTERM leaves one orphaned CLI per live
-    session, each holding hundreds of MB. Raising ``KeyboardInterrupt``
-    instead routes ``docker stop`` / ``systemctl stop`` through the same
-    shutdown path as Ctrl-C, which does reap them.
-
-    Only installed when we own the main thread's signal handlers; under
-    an embedding host that isn't ours to take.
-    """
 
+def _sigterm_as_interrupt() -> None:
     def _raise_interrupt(_signum: int, _frame: object) -> None:
         raise KeyboardInterrupt
 
     with contextlib.suppress(ValueError, OSError):
         signal.signal(signal.SIGTERM, _raise_interrupt)
-
-
-async def _async_main() -> None:
-    # Populate ``os.environ`` from ``.env`` before anything else so the
-    # user's ``config.py`` can read its own secrets via ``os.environ[...]``
-    # (Firefly PAT, third-party MCP creds, etc.). ``Settings`` already
-    # reads ``.env`` independently via pydantic-settings, but that path
-    # populates Settings fields, not the process environment.
-    # ``override=False``: real env vars (Docker, systemd) win over .env.
-    load_dotenv(override=False)
-
-    settings = Settings()  # ty: ignore[missing-argument]
-    gateway = config_loader.load(settings.config_path)
-
-    agents = AgentRegistry(gateway.agents)
-    mcps = McpRegistry(gateway.mcps)
-
-    # Phase 4.1 — open the async DB and run create_all once. Engine
-    # pool is process-wide; ``dispose()`` after the TaskGroup unwinds.
-    db = Database(settings.database_url)
-    await db.create_all()
-
-    # Phase 4.2 — TokenStore now reads from the DB (in-memory cache
-    # primed at start, TTL-refreshed, last_used_at flushed by a
-    # background task). BOOTSTRAP_TOKENS layers on top so first-run /
-    # examples still work without DB writes.
-    token_store = TokenStore(
-        db, bootstrap=TokenStore.parse_bootstrap(settings.bootstrap_tokens)
-    )
-
-    async with AsyncExitStack() as stack:
-        stack.push_async_callback(db.dispose)
-        await token_store.start()
-        stack.push_async_callback(token_store.stop)
-        # Internal MCP URLs must exist before we construct any
-        # ClaudeSdkBackend - adapters bake the URLs into their
-        # ``mcp_servers`` at construction time. The
-        # ``mcp_servers`` map is used by the Raycast backend, which
-        # needs in-process ``list_tools`` / ``call_tool`` access (the
-        # Raycast wire has no native MCP concept).
-        internal_app, internal_urls, mcp_servers = _build_internal_mcp(
-            gateway.mcps, settings=settings
-        )
-
-        # Prefetch tool catalogs for every MCP so RaycastAgent requests
-        # don't pay a per-turn list_tools roundtrip and so a broken MCP
-        # surfaces at startup instead of mid-conversation.
-        mcp_tools = await _prefetch_mcp_tools(mcp_servers)
-
-        pool = SessionPool()
-        bus = EventBus()
-        late = _LateConversations()
-        session_store = PostgresSessionStore(db)
-        backends: dict[str, Backend] = await _build_backends(
-            settings=settings,
-            agents=agents,
-            stack=stack,
-            db=db,
-            session_store=session_store,
-            mcp_internal_urls=internal_urls,
-            mcp_servers=mcp_servers,
-            mcp_tools=mcp_tools,
-            pool=pool,
-            late=late,
-        )
-        conversations = Conversations(
-            db=db,
-            agents=agents,
-            backends=backends,
-            bus=bus,
-            pool=pool,
-            store=session_store,
-            texts=gateway.texts,
-            frontends=gateway.frontends,
-        )
-        late.conversations = conversations
-
-        runtime = GatewayRuntime(
-            agents=agents,
-            mcps=mcps,
-            backends=backends,
-            token_store=token_store,
-            db=db,
-            mcp_internal_urls=internal_urls,
-            admin_user=settings.admin_user,
-            admin_pass=settings.admin_pass,
-            session_secret=settings.session_secret,
-            frontends=tuple(gateway.frontends),
-            conversations=conversations,
-            bus=bus,
-            pool=pool,
-        )
-
-        for fe in gateway.frontends:
-            fe.configure(runtime)
-
-        _log.info(
-            "beaver-gateway: loaded %d agents, %d mcps, %d frontends",
-            len(agents),
-            len(mcps),
-            len(gateway.frontends),
-        )
-
-        # Keep the Phase 0 DoD line on stdout for grep-friendly smoke
-        # tests, in addition to the structured log line above.
-        print(
-            f"beaver-gateway: loaded {len(agents)} agents, "
-            f"{len(mcps)} mcps, {len(gateway.frontends)} frontends"
-        )
-
-        if not gateway.frontends:
-            # No external listeners → nothing to serve. The internal
-            # MCP app has no consumer on its own, so we skip running
-            # it in this path and exit cleanly (Phase 0 DoD).
-            return
-
-        await conversations.start()
-        stack.push_async_callback(conversations.stop)
-        async with asyncio.TaskGroup() as tg:
-            tg.create_task(pool.reap_loop())
-            if internal_app is not None:
-                tg.create_task(_serve_internal_mcp(internal_app, settings=settings))
-            for fe in gateway.frontends:
-                tg.create_task(fe.serve())
-
-
-def _build_internal_mcp(
-    mcps: list[McpServerT], *, settings: Settings
-) -> tuple[Starlette | None, dict[str, str], dict[str, FastMCP]]:
-    """Build the aggregator app + URL map + server map, or empty equivalents.
-
-    The URL map is always handed out (frontends may still introspect
-    ``runtime.mcp_internal_urls`` even if nothing is configured); the
-    app is ``None`` when there are no MCPs to mount, so the caller
-    skips the uvicorn task entirely. The server map is the in-process
-    handle the Raycast backend needs to splice MCP tools into its
-    requests — empty when no MCPs are configured.
-    """
-    if not mcps:
-        return None, {}, {}
-    return build_internal_app(mcps, host="127.0.0.1", port=settings.internal_mcp_port)
-
-
-async def _prefetch_mcp_tools(
-    servers: dict[str, FastMCP],
-) -> dict[str, list[FastMCPTool]]:
-    """Eagerly enumerate tools per MCP so the Raycast loop has a static catalog.
-
-    Each underlying proxy is allowed to fail independently — a broken
-    MCP shouldn't take down the whole gateway. The result has one entry
-    per MCP that responded; agents that ``expose_mcps`` a missing entry
-    will simply expose no tools from it (logged once per request).
-    """
-    out: dict[str, list[FastMCPTool]] = {}
-    for name, server in servers.items():
-        try:
-            out[name] = list(await server.list_tools())
-        except Exception:  # noqa: BLE001 — proxy can raise any transport error; we degrade per-MCP rather than fail the whole gateway
-            _log.exception("failed to list tools for MCP %r — skipping", name)
-            out[name] = []
-    return out
-
-
-async def _serve_internal_mcp(app: Starlette, *, settings: Settings) -> None:
-    """Run the internal MCP aggregator on loopback.
-
-    Bound to ``127.0.0.1`` (never EXPOSE'd) — only the in-process
-    ClaudeCode subprocess reaches it. Logged at ``warning`` level so
-    we don't drown the gateway's own logs in per-request noise.
-    """
-    config = uvicorn.Config(
-        app,
-        host="127.0.0.1",
-        port=settings.internal_mcp_port,
-        log_level="warning",
-        loop="uvloop",
-    )
-    server = uvicorn.Server(config)
-    _log.info(
-        "internal MCP aggregator on http://127.0.0.1:%d/mcp/<name>",
-        settings.internal_mcp_port,
-    )
-    await server.serve()
-
-
-class _LateConversations:
-    """Backends need a tool-server factory before the service that backs it exists."""
-
-    conversations: Conversations | None = None
-
-    def server(
-        self, key: str, _kind: str, names: tuple[str, ...]
-    ) -> McpSdkServerConfig | None:
-        if self.conversations is None or not names:
-            return None
-        return build_tool_server(self.conversations, conversation_key=key, names=names)
-
-    async def ask(self, key: str, payload: dict[str, Any]) -> str:
-        if self.conversations is None:
-            msg = "conversations service is not up yet"
-            raise RuntimeError(msg)
-        answer = await self.conversations.ask(key, payload)
-        return self.conversations.answer_text(answer)
-
-
-async def _build_backends(
-    *,
-    settings: Settings,
-    agents: AgentRegistry,
-    stack: AsyncExitStack,
-    db: Database,
-    session_store: PostgresSessionStore,
-    mcp_internal_urls: dict[str, str],
-    mcp_servers: dict[str, FastMCP],
-    mcp_tools: dict[str, list[FastMCPTool]],
-    pool: SessionPool,
-    late: _LateConversations,
-) -> dict[str, Backend]:
-    """Construct one backend per agent name.
-
-    The Raycast ``Client`` is shared across every ``RaycastAgent``
-    (bearer + device-id are process-wide), so we open it lazily - only
-    when at least one ``RaycastAgent`` is present - and close it via
-    the caller's exit stack.
-
-    Each :class:`ClaudeAgent` gets its own :class:`ClaudeSdkBackend`
-    (own live-session pool, own prompt and MCP set); all of them share
-    the session store and the usage sink.
-    """
-    backends: dict[str, Backend] = {}
-
-    raycast_agents = [a for a in agents if isinstance(a, RaycastAgent)]
-    if raycast_agents:
-        client = await _try_open_raycast_client(settings, stack)
-        if client is not None:
-            raycast_backend = RaycastBackend(
-                client, mcp_servers=mcp_servers, mcp_tools=mcp_tools
-            )
-            for a in raycast_agents:
-                backends[a.name] = raycast_backend
-
-    runner = RunnerConfig(user=settings.claude_runner_user, home=settings.claude_home)
-    mcp_tool_names = {
-        name: [t.name for t in tools] for name, tools in mcp_tools.items()
-    }
-
-    async def record_usage(event: UsageEvent) -> None:
-        row = Usage(
-            agent_name=event.agent_name,
-            conversation_id=event.conversation_id,
-            session_id=event.session_id,
-            model=event.model,
-            effort=event.effort,
-            input_tokens=event.usage.input_tokens,
-            output_tokens=event.usage.output_tokens,
-            cache_read_tokens=event.usage.cache_read_tokens,
-            cache_creation_tokens=event.usage.cache_creation_tokens,
-            cost_usd=event.usage.cost_usd,
-            duration_ms=event.usage.duration_ms,
-            num_turns=event.usage.num_turns,
-            model_usage=event.usage.model_usage,
-        )
-        try:
-            async with db.session() as session:
-                await append_usage(session, row)
-        except Exception:  # noqa: BLE001
-            _log.exception("usage write failed for %s", event.agent_name)
-
-    for a in agents:
-        if isinstance(a, ClaudeAgent):
-            adapter = ClaudeSdkBackend(
-                agent=a,
-                mcp_internal_urls=mcp_internal_urls,
-                session_store=session_store,
-                mcp_tool_names=mcp_tool_names,
-                runner=runner,
-                usage_sink=record_usage,
-                pool=pool,
-                tool_server=functools.partial(late.server, names=a.gateway_tools),
-                asker=late.ask,
-            )
-            await stack.enter_async_context(adapter)
-            backends[a.name] = adapter
-
-    return backends
-
-
-async def _try_open_raycast_client(
-    settings: Settings, stack: AsyncExitStack
-) -> RaycastClient | None:
-    """Open a ``raycast_api.Client`` if creds are available, else warn + skip.
-
-    Skipping is gentler than failing startup: the user can bring up the
-    gateway, list their agents, and still hit a ``ClaudeAgent``; affected
-    ``RaycastAgent`` instances 503 with a specific message at request time.
-    Missing ``raycast.json`` falls into the same bucket — first-run
-    users won't have it yet.
-    """
-    if not settings.raycast_bearer:
-        _log.warning(
-            "RaycastAgent present but RAYCAST_BEARER is unset — those agents will 503"
-        )
-        return None
-    if not settings.raycast_device_id:
-        _log.warning(
-            "RaycastAgent present but RAYCAST_DEVICE_ID is unset — those agents "
-            "will 503 (generate once with `python -c 'import secrets; "
-            "print(secrets.token_hex(32))'`)"
-        )
-        return None
-    if not settings.raycast_config_path.exists():
-        _log.warning(
-            "RaycastAgent present but %s is missing — those agents will 503",
-            settings.raycast_config_path,
-        )
-        return None
-
-    config = RaycastConfig.load(settings.raycast_config_path)
-    client = RaycastClient(
-        config=config,
-        bearer_token=settings.raycast_bearer,
-        device_id=settings.raycast_device_id,
-        locale=settings.raycast_locale,
-    )
-    return await stack.enter_async_context(client)

src/beaver_gateway/config.py

@@ -0,0 +1,158 @@
+"""``Gateway`` - the one object a setup's ``config.py`` assembles - and its loader."""
+
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from croniter import croniter
+
+from beaver_gateway.agents.base import BaseAgent, ExposedMcp
+from beaver_gateway.agents.claude import ClaudeAgent
+from beaver_gateway.agents.raycast import RaycastAgent
+from beaver_gateway.conversations.texts import ConversationTexts
+from beaver_gateway.frontends.base import Frontend
+from beaver_gateway.jobs.scheduler import Job
+from beaver_gateway.mcp.types import HttpMcp, McpServer, PythonToolMcp, StdioMcp
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+    from pathlib import Path
+
+    from beaver_gateway.conversations.distill import Distiller
+    from beaver_gateway.conversations.envelope import RecallContext
+    from beaver_gateway.conversations.rotation import RotationPolicy
+    from beaver_gateway.conversations.texts import UserSaid
+    from beaver_gateway.jobs.scheduler import Budget
+    from beaver_gateway.mcp.types import McpServerT
+    from beaver_gateway.vault.watch import VaultWatch
+
+__all__ = ["ConfigError", "Gateway", "load"]
+
+_SCOPE = re.compile(r"[a-z][a-z0-9_-]*")
+
+
+@dataclass(slots=True)
+class Gateway:
+    agents: list[BaseAgent] = field(default_factory=list)
+    mcps: list[McpServerT] = field(default_factory=list)
+    frontends: list[Frontend] = field(default_factory=list)
+    texts: ConversationTexts | None = None
+    """Every string the gateway says to a model; ``None`` = the English defaults."""
+    jobs: list[Job] = field(default_factory=list)
+    """Cron, webhook and event jobs run by ``jobs.scheduler``."""
+    rotation: RotationPolicy | None = None
+    """When a master is replaced by a fresh one; ``None`` keeps the defaults."""
+    watch: VaultWatch | None = None
+    """Directory watcher feeding the envelope; ``None`` = no change block."""
+    recall: Callable[[RecallContext], str | None] | None = None
+    """Envelope lookup on the user's text: pointers the setup derives from its files."""
+    user_sink: Callable[[UserSaid], Awaitable[None] | None] | None = None
+    """Sees every user message entering a master or branch turn."""
+    budget: Budget | None = None
+    """Subscription utilisation past which non-critical jobs wait."""
+    distiller: Distiller | None = None
+    """Who closes deep chats and where digests and the index live."""
+    tz: str = "UTC"
+    """Zone for the envelope clock, cron expressions and the rotation hour."""
+    host: str = "0.0.0.0"  # noqa: S104
+    port: int = 8000
+    """The one listener; every HTTP frontend is mounted under its ``path``."""
+    public_url: str | None = None
+    """Origin the reverse proxy shows the world; ``None`` derives it per request."""
+
+
+class ConfigError(Exception):
+    pass
+
+
+_PUBLIC_NAMES: dict[str, Any] = {
+    "ClaudeAgent": ClaudeAgent,
+    "RaycastAgent": RaycastAgent,
+    "McpServer": McpServer,
+    "ExposedMcp": ExposedMcp,
+    "Gateway": Gateway,
+    "ConversationTexts": ConversationTexts,
+}
+
+_McpInstance = StdioMcp | HttpMcp | PythonToolMcp
+
+
+def load(path: Path) -> Gateway:
+    """Execute a setup's ``config.py`` and return its top-level ``gateway``."""
+    try:
+        source = path.read_text(encoding="utf-8")
+    except FileNotFoundError as exc:
+        msg = f"config file not found: {path}"
+        raise ConfigError(msg) from exc
+    except OSError as exc:
+        msg = f"could not read config file {path}: {exc}"
+        raise ConfigError(msg) from exc
+
+    code = compile(source, str(path), "exec")
+    parent = str(path.resolve().parent)
+    if parent not in sys.path:
+        sys.path.insert(0, parent)
+    namespace: dict[str, Any] = {"__file__": str(path), **_PUBLIC_NAMES}
+    exec(code, namespace)  # noqa: S102
+
+    try:
+        gw = namespace["gateway"]
+    except KeyError as exc:
+        msg = f"{path}: no top-level `gateway = Gateway(...)` found"
+        raise ConfigError(msg) from exc
+
+    if not isinstance(gw, Gateway):
+        msg = (
+            f"{path}: top-level `gateway` must be a Gateway instance, "
+            f"got {type(gw).__name__}"
+        )
+        raise ConfigError(msg)
+
+    _validate(gw, path)
+    return gw
+
+
+def _validate(gw: Gateway, path: Path) -> None:
+    for i, a in enumerate(gw.agents):
+        if not isinstance(a, BaseAgent):
+            msg = (
+                f"{path}: gateway.agents[{i}] must be a ClaudeAgent / "
+                f"RaycastAgent instance, got {type(a).__name__}"
+            )
+            raise ConfigError(msg)
+    for i, m in enumerate(gw.mcps):
+        if not isinstance(m, _McpInstance):
+            msg = (
+                f"{path}: gateway.mcps[{i}] must be built via "
+                f"McpServer.stdio/.http/.python_tool, "
+                f"got {type(m).__name__}"
+            )
+            raise ConfigError(msg)
+    for i, f in enumerate(gw.frontends):
+        if not isinstance(f, Frontend):
+            msg = (
+                f"{path}: gateway.frontends[{i}] must be a Frontend, "
+                f"got {type(f).__name__}"
+            )
+            raise ConfigError(msg)
+        if f.scope is not None and not _SCOPE.fullmatch(f.scope):
+            msg = (
+                f"{path}: gateway.frontends[{i}] has scope {f.scope!r}; "
+                f"a frontend scope is a lowercase name like 'voice', never '*'"
+            )
+            raise ConfigError(msg)
+    names: set[str] = set()
+    for i, j in enumerate(gw.jobs):
+        if not isinstance(j, Job):
+            msg = f"{path}: gateway.jobs[{i}] must be a Job, got {type(j).__name__}"
+            raise ConfigError(msg)
+        if j.name in names:
+            msg = f"{path}: duplicate job name {j.name!r}"
+            raise ConfigError(msg)
+        names.add(j.name)
+        if j.cron is not None and not croniter.is_valid(j.cron):
+            msg = f"{path}: job {j.name!r} has an invalid cron {j.cron!r}"
+            raise ConfigError(msg)

src/beaver_gateway/config_loader.py

@@ -1,101 +0,0 @@
-"""Load the user's ``/config/config.py``.
-
-The config file is regular Python. We ``exec`` it in a namespace seeded
-with the public surface the user is expected to use (``ClaudeAgent``,
-``RaycastAgent``, ``McpServer``, ``ExposedMcp``, ``Gateway``). The file
-must assign a top-level ``gateway = Gateway(...)``.
-
-Element-level validation already happens at construction time — agents
-and ``McpServer`` factories are pydantic models that reject garbage.
-What we *can't* validate at construction is the ``Gateway`` container
-itself (deliberately a plain dataclass per PRD), so we type-check its
-contents here before handing it back.
-"""
-
-from __future__ import annotations
-
-from typing import TYPE_CHECKING, Any
-
-from beaver_gateway.agents.base import BaseAgent, ExposedMcp
-from beaver_gateway.agents.claude import ClaudeAgent
-from beaver_gateway.agents.raycast import RaycastAgent
-from beaver_gateway.core.conversations import ConversationTexts
-from beaver_gateway.core.registry import Gateway
-from beaver_gateway.frontends.base import Frontend
-from beaver_gateway.mcp.types import HttpMcp, McpServer, PythonToolMcp, StdioMcp
-
-if TYPE_CHECKING:
-    from pathlib import Path
-
-
-class ConfigError(Exception):
-    """User config file is missing, unreadable, or structurally wrong."""
-
-
-_PUBLIC_NAMES: dict[str, Any] = {
-    "ClaudeAgent": ClaudeAgent,
-    "RaycastAgent": RaycastAgent,
-    "McpServer": McpServer,
-    "ExposedMcp": ExposedMcp,
-    "Gateway": Gateway,
-    "ConversationTexts": ConversationTexts,
-}
-
-_McpInstance = StdioMcp | HttpMcp | PythonToolMcp
-
-
-def load(path: Path) -> Gateway:
-    """Execute ``path`` and return its top-level ``gateway`` object."""
-    try:
-        source = path.read_text(encoding="utf-8")
-    except FileNotFoundError as exc:
-        msg = f"config file not found: {path}"
-        raise ConfigError(msg) from exc
-    except OSError as exc:
-        msg = f"could not read config file {path}: {exc}"
-        raise ConfigError(msg) from exc
-
-    code = compile(source, str(path), "exec")
-    namespace: dict[str, Any] = {"__file__": str(path), **_PUBLIC_NAMES}
-    exec(code, namespace)  # noqa: S102 - exec'ing user config is the feature
-
-    try:
-        gw = namespace["gateway"]
-    except KeyError as exc:
-        msg = f"{path}: no top-level `gateway = Gateway(...)` found"
-        raise ConfigError(msg) from exc
-
-    if not isinstance(gw, Gateway):
-        msg = (
-            f"{path}: top-level `gateway` must be a Gateway instance, "
-            f"got {type(gw).__name__}"
-        )
-        raise ConfigError(msg)
-
-    _validate(gw, path)
-    return gw
-
-
-def _validate(gw: Gateway, path: Path) -> None:
-    for i, a in enumerate(gw.agents):
-        if not isinstance(a, BaseAgent):
-            msg = (
-                f"{path}: gateway.agents[{i}] must be a ClaudeAgent / "
-                f"RaycastAgent instance, got {type(a).__name__}"
-            )
-            raise ConfigError(msg)
-    for i, m in enumerate(gw.mcps):
-        if not isinstance(m, _McpInstance):
-            msg = (
-                f"{path}: gateway.mcps[{i}] must be built via "
-                f"McpServer.stdio/.http/.python_tool, "
-                f"got {type(m).__name__}"
-            )
-            raise ConfigError(msg)
-    for i, f in enumerate(gw.frontends):
-        if not isinstance(f, Frontend):
-            msg = (
-                f"{path}: gateway.frontends[{i}] must be a Frontend, "
-                f"got {type(f).__name__}"
-            )
-            raise ConfigError(msg)

src/beaver_gateway/conversations/__init__.py

@@ -0,0 +1 @@
+"""Conversations: rows, queue, seeds, turns, questions, closing, rotation, envelope."""

src/beaver_gateway/conversations/closing.py

@@ -0,0 +1,322 @@
+"""Ending conversations: the distiller, the line cap, the master handover."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import inspect
+import logging
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING, Any, cast
+
+from beaver_gateway.conversations.distill import (
+    Digest,
+    DistillContext,
+    LineCap,
+    append_index,
+    check_digest,
+    find_digest,
+    index_line,
+    trim_summary,
+    written_paths,
+)
+from beaver_gateway.conversations.questions import Questions
+from beaver_gateway.conversations.state import aware
+from beaver_gateway.conversations.texts import NewDayContext
+
+if TYPE_CHECKING:
+    from beaver_gateway.conversations.rotation import HandoutContext
+    from beaver_gateway.storage.models import Conversation, InjectQueueItem
+
+__all__ = ["Closing", "DistillResult"]
+
+_log = logging.getLogger(__name__)
+
+CLOSE_WAIT = 0.25
+CLOSE_TRIES = 40
+CAP_TRIES = 3
+
+
+@dataclass(frozen=True, slots=True)
+class DistillResult:
+    conversation: Conversation
+    fork: Conversation
+    text: str
+    digest: Digest | None
+    error: str | None
+    trimmed: bool
+
+
+class Closing(Questions):
+    async def close(self, conv: Conversation) -> Conversation:
+        row = await self.set_status(conv, "closed")
+        with contextlib.suppress(LookupError):
+            await self._backend(conv.agent_name).close(conv.external_id)
+        return row
+
+    async def request_close(self, conv: Conversation) -> Conversation:
+        """``close_chat`` from inside a turn: the chat closes once the turn ends."""
+        if conv.kind != "deep":
+            msg = f"only deep chats close this way, {conv.external_id} is {conv.kind}"
+            raise ValueError(msg)
+        return await self.set_flags(conv, {"close_requested": True})
+
+    async def idle(
+        self,
+        *,
+        kind: str,
+        days: int,
+        since: datetime | None = None,
+        limit: int | None = None,
+    ) -> list[Conversation]:
+        """Open conversations of ``kind`` with a session, quiet for ``days``."""
+        now = datetime.now(UTC)
+        cutoff = now - timedelta(days=days)
+        out: list[tuple[datetime, Conversation]] = []
+        for conv in await self.find(status="open", kind=kind, limit=10_000):
+            if conv.session_id is None:
+                continue
+            last = aware(conv.last_activity_at or conv.created_at)
+            if last > cutoff or (since is not None and last < since):
+                continue
+            out.append((last, conv))
+        out.sort(key=lambda pair: pair[0])
+        rows = [conv for _, conv in out]
+        return rows[:limit] if limit is not None else rows
+
+    async def distill(
+        self, conv: Conversation, *, reason: str = "api"
+    ) -> DistillResult:
+        """Fork under the distiller: digest checked and indexed, merge to the master."""
+        if self._distiller is None:
+            msg = "no distiller configured (Gateway(distiller=...))"
+            raise RuntimeError(msg)
+        if conv.kind != "deep":
+            msg = f"only deep chats are distilled, {conv.external_id} is {conv.kind}"
+            raise ValueError(msg)
+        row = await self.get_row(cast("int", conv.id)) or conv
+        if row.status != "open":
+            msg = f"conversation {row.external_id} is {row.status}"
+            raise ValueError(msg)
+        if await self.busy(row):
+            msg = f"conversation {row.external_id} is busy"
+            raise RuntimeError(msg)
+        memory = bool(row.flags.get("memory", True))
+        chat_name = await self.chat_name(row)
+        ctx = DistillContext(
+            conversation=row,
+            title=await self.implied_title(row),
+            source=await self.window_of(row),
+            chat_name=chat_name,
+            memory=memory,
+            reason=reason,
+            day=datetime.now(UTC).astimezone().date(),
+        )
+        prompt = await self._distill_prompt(ctx)
+        started = datetime.now(UTC)
+        self._bus.publish(
+            "distill.start",
+            conversation_id=row.external_id,
+            reason=reason,
+            memory=memory,
+        )
+        result = await self.fork(
+            row,
+            prompt,
+            strip_tools=True,
+            agent=self._distiller.agent,
+            title=f"digest: {chat_name}",
+        )
+        text, trimmed = trim_summary(result.text)
+        digest: Digest | None = None
+        error: str | None = None
+        if memory:
+            written = written_paths(result.capture.synthesized_messages)
+            path = find_digest(self._distiller, since=started, written=written)
+            if path is None:
+                error = self._texts.digest_missing
+            else:
+                checked = check_digest(path, self._distiller)
+                if isinstance(checked, str):
+                    error = f"{path.name}: {checked}"
+                else:
+                    digest = checked
+                    append_index(self._distiller, index_line(digest, chat_name))
+        if error is not None:
+            _log.warning("distill of %s: %s", row.external_id, error)
+        master = await self.open_master()
+        if master is not None and text:
+            note = self._texts.closed.format(
+                chat=chat_name,
+                digest=(
+                    self._texts.closed_digest.format(digest=digest.path.stem)
+                    if digest
+                    else ""
+                ),
+                text=text,
+            )
+            await self.inject(master, note, urgency="normal", origin="digest")
+        await self.close(row)
+        row = await self.set_flags(
+            row,
+            {
+                "close_requested": None,
+                "closed_reason": reason,
+                "digest": str(digest.path) if digest else None,
+                "digest_error": error,
+            },
+        )
+        self._bus.publish(
+            "conversation.distilled",
+            conversation_id=row.external_id,
+            fork=result.conversation.external_id,
+            reason=reason,
+            memory=memory,
+            digest=str(digest.path) if digest else None,
+            error=error,
+            text=text,
+            trimmed=trimmed,
+            master=master.external_id if master is not None else None,
+        )
+        return DistillResult(
+            conversation=row,
+            fork=result.conversation,
+            text=text,
+            digest=digest,
+            error=error,
+            trimmed=trimmed,
+        )
+
+    async def _distill_prompt(self, ctx: DistillContext) -> str:
+        source = self._texts.distill
+        if source is None:
+            template = (
+                self._texts.distill_prompt
+                if ctx.memory
+                else self._texts.distill_prompt_no_memory
+            )
+            return template.format(
+                chat=ctx.chat_name, reason=ctx.reason, day=ctx.day.isoformat()
+            )
+        produced: Any = source(ctx)
+        return await produced if inspect.isawaitable(produced) else produced
+
+    async def _close_after_turn(self, conv: Conversation) -> None:
+        for _ in range(CLOSE_TRIES):
+            if await self.busy(conv):
+                await asyncio.sleep(CLOSE_WAIT)
+                continue
+            try:
+                await self.distill(conv, reason="close_chat")
+            except RuntimeError as exc:
+                _log.info("closing %s: %s, retrying", conv.external_id, exc)
+                await asyncio.sleep(CLOSE_WAIT)
+                continue
+            except Exception:  # noqa: BLE001
+                _log.exception("closing %s after its turn failed", conv.external_id)
+            return
+        _log.warning("closing %s: still busy, giving up", conv.external_id)
+
+    async def before_turn(self, conv: Conversation) -> str | None:
+        cap = LineCap.from_flags(conv.flags.get("line_cap"))
+        if cap is None:
+            return None
+        try:
+            return cap.path.read_text(encoding="utf-8") if cap.path.exists() else ""
+        except OSError:
+            _log.exception("line cap: cannot read %s", cap.path)
+            return None
+
+    async def after_turn(self, conv: Conversation, before: str | None) -> None:
+        row = await self.get_row(cast("int", conv.id))
+        if row is None:
+            return
+        if row.kind == "deep" and row.flags.get("close_requested"):
+            self._track(asyncio.create_task(self._close_after_turn(row)))
+        cap = LineCap.from_flags(row.flags.get("line_cap"))
+        if cap is not None and before is not None:
+            await self._enforce_cap(row, cap, before)
+
+    async def _enforce_cap(self, conv: Conversation, cap: LineCap, before: str) -> None:
+        if not cap.path.exists():
+            return
+        after = cap.path.read_text(encoding="utf-8")
+        lines = sum(1 for line in after.splitlines() if line.strip())
+        if lines <= cap.max_lines:
+            return
+        if before:
+            cap.path.write_text(before, encoding="utf-8")
+        else:
+            cap.path.unlink()
+        attempts = int(conv.flags.get("line_cap_attempts", 0) or 0) + 1
+        await self.set_flags(conv, {"line_cap_attempts": attempts})
+        self._bus.publish(
+            "line_cap.bounced",
+            conversation_id=conv.external_id,
+            path=str(cap.path),
+            lines=lines,
+            max_lines=cap.max_lines,
+            attempt=attempts,
+        )
+        _log.warning(
+            "line cap: %s came back with %d lines (cap %d), restored; attempt %d",
+            cap.path,
+            lines,
+            cap.max_lines,
+            attempts,
+        )
+        if attempts > CAP_TRIES:
+            return
+        await self.inject(
+            conv,
+            self._texts.too_long.format(
+                name=cap.path.name, lines=lines, max_lines=cap.max_lines
+            ),
+            urgency="urgent",
+            origin="cap",
+            interrupt=False,
+        )
+
+    async def handout(self, conv: Conversation, ctx: HandoutContext) -> str:
+        """The closing master's last turn."""
+        source = self._texts.handout
+        if isinstance(source, str):
+            prompt = source.format(day=ctx.day.isoformat(), reason=ctx.reason)
+        else:
+            produced: Any = source(ctx)
+            prompt = await produced if inspect.isawaitable(produced) else produced
+        self._bus.publish(
+            "handout.start", conversation_id=conv.external_id, day=ctx.day.isoformat()
+        )
+        try:
+            text, _ = await self.run_text_turn(conv, prompt, origin="handout")
+        except Exception:  # noqa: BLE001
+            _log.exception("handout turn on %s failed", conv.external_id)
+            text = ""
+        self._bus.publish(
+            "handout.end",
+            conversation_id=conv.external_id,
+            day=ctx.day.isoformat(),
+            text=text[:2000],
+        )
+        return text
+
+    async def new_day(
+        self, conv: Conversation, *, reason: str = "night", moved: int = 0
+    ) -> InjectQueueItem:
+        """The new master's first inject."""
+        ctx = NewDayContext(
+            day=datetime.now(UTC).astimezone().date(), reason=reason, moved=moved
+        )
+        source = self._texts.new_day
+        if isinstance(source, str):
+            text = source.format(day=ctx.day.isoformat(), reason=ctx.reason)
+        else:
+            produced: Any = source(ctx)
+            text = await produced if inspect.isawaitable(produced) else produced
+        if moved:
+            text += self._texts.moved_injects.format(moved=moved)
+        return await self.inject(
+            conv, text, urgency="urgent", origin="rotation", interrupt=False
+        )

src/beaver_gateway/conversations/context.py

@@ -0,0 +1,246 @@
+"""What a conversation's model holds: prompt granules, skills, tools, files touched."""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Mapping
+
+    from beaver_gateway.agents.claude import ClaudeAgent
+    from beaver_gateway.conversations.kinds import Kind
+
+__all__ = ["bash_paths", "compose", "files_touched", "granules", "skill_sets"]
+
+CHARS_PER_TOKEN = 3.2
+READ_TOOLS = frozenset({"Read", "NotebookRead"})
+WRITE_TOOLS = frozenset({"Write", "Edit", "MultiEdit", "NotebookEdit"})
+SEARCH_TOOLS = frozenset({"Glob", "Grep"})
+PATH_KEYS = ("file_path", "notebook_path", "path", "file", "filename")
+_FRONTMATTER = re.compile(r"^---\s*\n(.*?)\n---", re.DOTALL)
+# A shell command names files as quoted strings or bare words; only notes
+# and plain text files count, code and binaries are the agent's own business.
+_SHELL_TOKEN = re.compile(r'"([^"\n]+)"|\'([^\'\n]+)\'|([^\s"\'`;|&()<>]+)')
+_NOTE_SUFFIXES = (".md", ".canvas", ".txt", ".csv", ".json", ".yaml", ".yml")
+_SHELL_CD = re.compile(r'(?:^|&&|;|\|\|)\s*cd\s+("([^"]+)"|\'([^\']+)\'|(\S+))')
+_SHELL_WRITES = re.compile(
+    r"write_text|write_bytes|>>?\s*[\"\']?[^\s&|]|\btee\b|\bsed\s+-i|\bmv\b|\brm\b"
+    r"|\btouch\b|\bcp\b|open\([^)]*[\"\'][wa]"
+)
+
+
+def bash_paths(command: str, cwd: Path | None) -> tuple[list[str], Path | None, bool]:
+    """Files a shell command names, where it leaves the shell, whether it writes.
+
+    Relative names resolve against ``cwd``, or against the directory of a
+    leading ``cd`` in the same command. Absolute names stay as they are.
+    """
+    here = cwd
+    for match in _SHELL_CD.finditer(command):
+        target = match.group(2) or match.group(3) or match.group(4) or ""
+        target = target.strip()
+        if not target:
+            continue
+        here = Path(target) if target.startswith("/") else (here or Path()) / target
+    found: list[str] = []
+    for match in _SHELL_TOKEN.finditer(command):
+        raw = (match.group(1) or match.group(2) or match.group(3) or "").strip()
+        if not raw.lower().endswith(_NOTE_SUFFIXES) or "*" in raw:
+            continue
+        path = Path(raw) if raw.startswith("/") else (here or Path()) / raw
+        text = str(path)
+        if text not in found:
+            found.append(text)
+    return found, here, bool(_SHELL_WRITES.search(command))
+
+
+def _tokens(chars: int) -> int:
+    return round(chars / CHARS_PER_TOKEN)
+
+
+def _relative(path: str, cwd: Path | None) -> str:
+    if cwd is None:
+        return path
+    try:
+        return str(Path(path).relative_to(cwd))
+    except ValueError:
+        return path
+
+
+def _tool_uses(entries: Iterable[Mapping[str, Any]]) -> Iterable[tuple[str, Any, str]]:
+    for entry in entries:
+        message = entry.get("message")
+        if entry.get("type") != "assistant" or not isinstance(message, dict):
+            continue
+        content = message.get("content")
+        if not isinstance(content, list):
+            continue
+        stamp = str(entry.get("timestamp") or "")
+        for block in content:
+            if isinstance(block, dict) and block.get("type") == "tool_use":
+                yield str(block.get("name") or "?"), block.get("input"), stamp
+
+
+def files_touched(
+    entries: Iterable[Mapping[str, Any]], *, cwd: Path | None = None
+) -> tuple[list[dict[str, Any]], dict[str, int]]:
+    """Files named in tool inputs, with how they were touched, plus tool counts."""
+    files: dict[str, dict[str, Any]] = {}
+    counts: Counter[str] = Counter()
+    # The shell keeps its directory between calls; follow it.
+    shell_cwd = cwd
+
+    def touch(raw: str, how: str, stamp: str) -> None:
+        key = _relative(raw, cwd)
+        row = files.setdefault(
+            key, {"path": key, "reads": 0, "writes": 0, "other": 0, "last_at": stamp}
+        )
+        row[how] += 1
+        row["last_at"] = max(row["last_at"], stamp)
+
+    for name, tool_input, stamp in _tool_uses(entries):
+        counts[name] += 1
+        if not isinstance(tool_input, dict):
+            continue
+        if name == "Bash" and isinstance(tool_input.get("command"), str):
+            paths, shell_cwd, writes = bash_paths(tool_input["command"], shell_cwd)
+            for raw in paths:
+                touch(raw, "writes" if writes else "reads", stamp)
+            continue
+        raw = next(
+            (v for k in PATH_KEYS if isinstance(v := tool_input.get(k), str) and v),
+            None,
+        )
+        if raw is None or (name in SEARCH_TOOLS and "file_path" not in tool_input):
+            continue
+        if name in READ_TOOLS:
+            touch(raw, "reads", stamp)
+        elif name in WRITE_TOOLS:
+            touch(raw, "writes", stamp)
+        else:
+            touch(raw, "other", stamp)
+    ordered = sorted(files.values(), key=lambda r: r["last_at"], reverse=True)
+    return ordered, dict(counts)
+
+
+def granules(agent: ClaudeAgent, kind: Kind) -> dict[str, Any]:
+    """The system prompt as its sources: tag, path, size, token estimate."""
+    sources = agent.prompt_for(kind) if agent.serves(kind) else None
+    rows: list[dict[str, Any]] = []
+    if sources is None:
+        chars = len(agent.system_prompt)
+        if chars:
+            rows.append(
+                {
+                    "tag": None,
+                    "path": None,
+                    "bytes": chars,
+                    "tokens_est": _tokens(chars),
+                }
+            )
+    else:
+        for source in sources:
+            tag, raw = source if isinstance(source, tuple) else (None, source)
+            path = Path(raw)
+            try:
+                chars = len(path.read_text(encoding="utf-8"))
+            except OSError:
+                chars = 0
+            rows.append(
+                {
+                    "tag": tag,
+                    "path": _relative(str(path), agent.cwd),
+                    "bytes": chars,
+                    "tokens_est": _tokens(chars),
+                }
+            )
+    total = sum(r["bytes"] for r in rows)
+    return {"bytes": total, "tokens_est": _tokens(total), "granules": rows}
+
+
+def _skill_meta(skill_md: Path) -> dict[str, str]:
+    try:
+        text = skill_md.read_text(encoding="utf-8")
+    except OSError:
+        return {}
+    match = _FRONTMATTER.match(text)
+    meta: dict[str, str] = {}
+    if match:
+        for line in match.group(1).splitlines():
+            key, sep, value = line.partition(":")
+            if sep:
+                meta[key.strip()] = value.strip()
+    return meta
+
+
+def skill_sets(agent: ClaudeAgent, kind: Kind) -> list[dict[str, Any]]:
+    """Skill-set directories the kind loads, with each skill's name and description."""
+    out: list[dict[str, Any]] = []
+    for directory in agent.skills_for(kind):
+        skills = []
+        try:
+            children = sorted(p for p in directory.iterdir() if p.is_dir())
+        except OSError:
+            children = []
+        for child in children:
+            skill_md = child / "SKILL.md"
+            if skill_md.is_file():
+                meta = _skill_meta(skill_md)
+                skills.append(
+                    {
+                        "name": meta.get("name") or child.name,
+                        "description": meta.get("description", ""),
+                        "path": _relative(str(child), agent.cwd),
+                    }
+                )
+        out.append(
+            {
+                "set": directory.name,
+                "path": _relative(str(directory), agent.cwd),
+                "skills": skills,
+            }
+        )
+    return out
+
+
+def compose(
+    agent: ClaudeAgent,
+    kind: Kind,
+    entries: Iterable[Mapping[str, Any]],
+    *,
+    context_tokens: int,
+) -> dict[str, Any]:
+    files, counts = files_touched(entries, cwd=agent.cwd)
+    prompt = granules(agent, kind)
+    skills = skill_sets(agent, kind)
+    skills_chars = sum(
+        len(s["name"]) + len(s["description"])
+        for group in skills
+        for s in group["skills"]
+    )
+    return {
+        "agent": {
+            "name": agent.name,
+            "model": agent.model,
+            "effort": agent.options.effort,
+        },
+        "kind": kind,
+        "context_tokens": context_tokens,
+        "prompt": prompt,
+        "skills": skills,
+        "skills_tokens_est": _tokens(skills_chars),
+        "tools": {
+            "allowed": list(agent.options.tools) if agent.options.tools else None,
+            "disallowed": list(agent.options.disallowed_tools),
+            "gateway": list(agent.gateway_tools),
+            "mcps": [m.name for m in agent.expose_mcps],
+        },
+        "files": files,
+        "tool_counts": counts,
+        "history_tokens_est": max(
+            0, context_tokens - prompt["tokens_est"] - _tokens(skills_chars)
+        ),
+    }

src/beaver_gateway/conversations/distill.py

@@ -0,0 +1,192 @@
+"""Closing a deep chat: the digest, the index, the file line cap.
+
+``Distiller`` says where digests and the index live; the gateway checks the
+digest's frontmatter and caps the merge text. ``LineCap`` is the same idea
+for a file a job rewrites: too long, and it is bounced back unchanged.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import frontmatter
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Sequence
+
+    from beaver_gateway.storage.models import Conversation
+
+__all__ = [
+    "SUMMARY_LINES",
+    "Digest",
+    "DistillContext",
+    "Distiller",
+    "LineCap",
+    "append_index",
+    "check_digest",
+    "find_digest",
+    "index_line",
+    "trim_summary",
+    "written_paths",
+]
+
+SUMMARY_LINES = 5
+"""A merge into the master is at most this many lines."""
+
+
+@dataclass(frozen=True, slots=True)
+class Distiller:
+    """Who closes deep chats, where digests land, where the index lives."""
+
+    agent: str
+    dir: Path
+    index: Path
+    type: str = "digest"
+    """Value the ``type`` frontmatter key must carry."""
+
+    index_header: str = "# index\n\none line per digest: chat → its digest.\n"
+
+
+@dataclass(frozen=True, slots=True)
+class DistillContext:
+    """What the setup's distill prompt is built from."""
+
+    conversation: Conversation
+    title: str | None
+    source: str | None
+    """The window the chat lives in (a vault-relative path for markdown)."""
+
+    chat_name: str
+    """What a ``[[wikilink]]`` to the chat is called."""
+
+    memory: bool
+    reason: str
+    day: date
+
+
+@dataclass(frozen=True, slots=True)
+class Digest:
+    path: Path
+    source: str
+    date: date
+
+
+@dataclass(frozen=True, slots=True)
+class LineCap:
+    """A file a job rewrites may not exceed ``max_lines`` after its turn."""
+
+    path: Path
+    max_lines: int
+
+    def as_flags(self) -> dict[str, Any]:
+        return {"path": str(self.path), "max_lines": self.max_lines}
+
+    @classmethod
+    def from_flags(cls, value: Any) -> LineCap | None:
+        if not isinstance(value, dict):
+            return None
+        path, max_lines = value.get("path"), value.get("max_lines")
+        if not isinstance(path, str) or not isinstance(max_lines, int):
+            return None
+        return cls(path=Path(path), max_lines=max_lines)
+
+
+def written_paths(messages: Iterable[dict[str, Any]]) -> list[Path]:
+    """Paths the turn's ``Write``/``Edit`` calls targeted, in order."""
+    out: list[Path] = []
+    for message in messages:
+        content = message.get("content")
+        if not isinstance(content, list):
+            continue
+        for block in content:
+            if not isinstance(block, dict) or block.get("type") != "tool_use":
+                continue
+            if block.get("name") not in ("Write", "Edit", "MultiEdit"):
+                continue
+            target = (block.get("input") or {}).get("file_path")
+            if isinstance(target, str) and target:
+                out.append(Path(target))
+    return out
+
+
+def find_digest(
+    digests: Distiller, *, since: datetime, written: Sequence[Path] = ()
+) -> Path | None:
+    """The digest the fork turn produced.
+
+    A written path under ``dir`` first, otherwise the newest file there
+    modified since ``since``.
+    """
+    root = digests.dir.resolve()
+    for path in reversed(list(written)):
+        candidate = path if path.is_absolute() else digests.dir / path
+        try:
+            inside = candidate.resolve().relative_to(root)
+        except (OSError, ValueError):
+            continue
+        if (digests.dir / inside).is_file():
+            return digests.dir / inside
+    if not digests.dir.is_dir():
+        return None
+    stamp = since.timestamp() - 1
+    fresh = [
+        p
+        for p in digests.dir.glob("*.md")
+        if p.is_file() and p.stat().st_mtime >= stamp
+    ]
+    return max(fresh, key=lambda p: p.stat().st_mtime) if fresh else None
+
+
+def check_digest(path: Path, digests: Distiller) -> Digest | str:
+    """The digest's frontmatter parsed, or why it is not a digest."""
+    try:
+        post = frontmatter.load(str(path))
+    except (OSError, ValueError) as exc:
+        return f"unreadable: {exc}"
+    meta = post.metadata
+    if meta.get("type") != digests.type:
+        return f"`type` must be `{digests.type}`, not {meta.get('type')!r}"
+    source = meta.get("source")
+    if not isinstance(source, str) or not source.strip():
+        return "`source` is empty"
+    when = meta.get("date")
+    if isinstance(when, datetime):
+        when = when.date()
+    elif isinstance(when, str):
+        try:
+            when = date.fromisoformat(when.strip())
+        except ValueError:
+            return f"`date` is not a date: {when!r}"
+    if not isinstance(when, date):
+        return "`date` is missing"
+    if not post.content.strip():
+        return "empty body"
+    return Digest(path=path, source=source.strip(), date=when)
+
+
+def index_line(digest: Digest, chat_name: str) -> str:
+    return f"- {digest.date.isoformat()} [[{chat_name}]] → [[{digest.path.stem}]]"
+
+
+def append_index(digests: Distiller, line: str) -> None:
+    index = digests.index
+    text = index.read_text(encoding="utf-8") if index.exists() else ""
+    if line in text.splitlines():
+        return
+    if not text:
+        text = digests.index_header
+    if not text.endswith("\n"):
+        text += "\n"
+    index.parent.mkdir(parents=True, exist_ok=True)
+    index.write_text(text + line + "\n", encoding="utf-8")
+
+
+def trim_summary(text: str, limit: int = SUMMARY_LINES) -> tuple[str, bool]:
+    """The merge text cut to ``limit`` non-empty lines; ``True`` if it was."""
+    lines = [line.rstrip() for line in text.strip().splitlines() if line.strip()]
+    if len(lines) <= limit:
+        return "\n".join(lines), False
+    return "\n".join(lines[:limit]), True

src/beaver_gateway/conversations/envelope.py

@@ -0,0 +1,154 @@
+"""The envelope: a background block under the user's text - clock, changes, recall."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+from zoneinfo import ZoneInfo
+
+from beaver_gateway.conversations.texts import EnvelopeTexts
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Sequence
+
+    from beaver_gateway.vault.watch import Change, VaultWatch
+
+__all__ = ["Envelope", "RecallContext", "render"]
+
+_log = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True, slots=True)
+class RecallContext:
+    text: str
+    kind: str
+    now: datetime
+    agent: str = ""
+    """Agent whose turn it is; a setup with several tells them apart by it."""
+
+
+@dataclass(slots=True)
+class Envelope:
+    watch: VaultWatch | None = None
+    tz: str = "UTC"
+    max_lines: int = 120
+    per_file: int = 30
+    names_only_within: float = 600.0
+    last_at: datetime | None = None
+    recall: Callable[[RecallContext], str | None] | None = None
+    """Setup-side lookup on the user's text; its lines go under the change block."""
+    texts: EnvelopeTexts = field(default_factory=EnvelopeTexts)
+
+    def build(
+        self,
+        *,
+        now: datetime | None = None,
+        text: str = "",
+        kind: str = "master",
+        agent: str = "",
+    ) -> str:
+        now = now or datetime.now(UTC)
+        changes = self.watch.take() if self.watch is not None else []
+        names_only = (
+            self.last_at is not None
+            and (now - self.last_at).total_seconds() < self.names_only_within
+        )
+        out = render(
+            now=now,
+            tz=self.tz,
+            changes=changes,
+            since=self.last_at,
+            names_only=names_only,
+            max_lines=self.max_lines,
+            per_file=self.per_file,
+            texts=self.texts,
+        )
+        self.last_at = now
+        block = self.recall_block(text=text, kind=kind, now=now, agent=agent)
+        return f"{out}\n{block}" if block else out
+
+    def recall_only(
+        self, *, text: str, kind: str, now: datetime | None = None, agent: str = ""
+    ) -> str | None:
+        block = self.recall_block(
+            text=text, kind=kind, now=now or datetime.now(UTC), agent=agent
+        )
+        return f"{self.texts.header}\n{block}" if block else None
+
+    def recall_block(
+        self, *, text: str, kind: str, now: datetime, agent: str = ""
+    ) -> str | None:
+        if self.recall is None or not text.strip():
+            return None
+        try:
+            block = self.recall(
+                RecallContext(text=text, kind=kind, now=now, agent=agent)
+            )
+        except Exception:  # noqa: BLE001
+            _log.exception("recall hook failed")
+            return None
+        return block.strip() or None if block else None
+
+
+def render(
+    *,
+    now: datetime,
+    tz: str,
+    changes: Sequence[Change],
+    since: datetime | None,
+    names_only: bool,
+    max_lines: int = 120,
+    per_file: int = 30,
+    texts: EnvelopeTexts | None = None,
+) -> str:
+    texts = texts or EnvelopeTexts()
+    zone = ZoneInfo(tz)
+    stamp = now.astimezone(zone)
+    lines = [
+        texts.header,
+        texts.time.format(stamp=f"{stamp:%Y-%m-%d %H:%M}", zone=_zone_label(tz)),
+    ]
+    ordered = sorted(changes, key=lambda c: (not c.full, c.path))
+    since_label = (
+        texts.since.format(time=f"{since.astimezone(zone):%H:%M}")
+        if since is not None
+        else texts.since_start
+    )
+    if ordered:
+        names = ", ".join(f"{c.path} (+{c.added_count})" for c in ordered)
+        lines.append(texts.changed.format(since=since_label, names=names))
+    if not names_only:
+        _append_diffs(
+            lines, ordered, max_lines=max_lines, per_file=per_file, texts=texts
+        )
+    return "\n".join(lines[:max_lines])
+
+
+def _append_diffs(
+    lines: list[str],
+    changes: Sequence[Change],
+    *,
+    max_lines: int,
+    per_file: int,
+    texts: EnvelopeTexts,
+) -> None:
+    budget = max_lines - len(lines) - 1
+    for change in changes:
+        if not change.full or not change.added:
+            continue
+        if budget < 3:
+            lines.append(texts.truncated)
+            return
+        shown = change.added[: min(per_file, budget - 2)]
+        lines.append(texts.file_header.format(path=change.path))
+        lines.extend(f"+ {line}" for line in shown)
+        budget -= 1 + len(shown)
+        if len(change.added) > len(shown):
+            lines.append(texts.more_lines.format(count=len(change.added) - len(shown)))
+            budget -= 1
+
+
+def _zone_label(tz: str) -> str:
+    return tz.rsplit("/", 1)[-1].replace("_", " ")

src/beaver_gateway/conversations/injects.py

@@ -0,0 +1,219 @@
+"""Persisted per-conversation queue: ``urgent > user > wake > normal``.
+
+conversations/service.py runs one worker per conversation over these rows.
+A row still ``running`` when the gateway starts was cut by a restart and is
+flagged ``interrupted``, never re-run.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any, Literal, cast
+
+from sqlalchemy import func
+from sqlmodel import col, select
+
+from beaver_gateway.storage.models import InjectQueueItem
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Sequence
+
+    from beaver_gateway.storage.db import Database
+    from beaver_gateway.storage.models import Conversation
+
+__all__ = [
+    "PRIORITY_RANK",
+    "URGENCY",
+    "InjectContext",
+    "InjectQueue",
+    "Priority",
+    "inject_header",
+]
+
+Priority = Literal["urgent", "user", "wake", "normal"]
+PRIORITY_RANK: dict[str, int] = {"urgent": 0, "user": 1, "wake": 2, "normal": 3}
+URGENCY: tuple[Priority, ...] = ("normal", "wake", "urgent")
+"""What the API and the tools accept for ``urgency``: every priority but ``user``."""
+
+INTERRUPTED_TURN = (
+    "[this inject cut the previous turn: the «Request interrupted» above is "
+    "an interruption, not a refused tool call]"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class InjectContext:
+    """What a header renderer knows about one queued inject."""
+
+    origin: str
+    priority: str
+    interrupted_turn: bool
+
+
+def inject_header(ctx: InjectContext) -> str:
+    """Default framing; a setup overrides it via ``ConversationTexts.inject_header``."""
+    head = f"[inject: {ctx.origin} - not the user, no reply needed]"
+    return f"{head}\n{INTERRUPTED_TURN}" if ctx.interrupted_turn else head
+
+
+def context_of(item: InjectQueueItem) -> InjectContext:
+    return InjectContext(
+        origin=item.origin,
+        priority=item.priority,
+        interrupted_turn=bool(item.interrupted_turn),
+    )
+
+
+class InjectQueue:
+    def __init__(self, db: Database) -> None:
+        self._db = db
+
+    async def push(
+        self,
+        *,
+        conversation_id: int,
+        priority: Priority,
+        origin: str,
+        text: str,
+        attachments: list[dict[str, Any]] | None = None,
+    ) -> InjectQueueItem:
+        if priority not in PRIORITY_RANK:
+            msg = f"unknown priority {priority!r}"
+            raise ValueError(msg)
+        row = InjectQueueItem(
+            conversation_id=conversation_id,
+            priority=priority,
+            origin=origin,
+            text=text,
+            attachments=attachments or None,
+        )
+        async with self._db.session() as session:
+            session.add(row)
+            await session.commit()
+            await session.refresh(row)
+        return row
+
+    async def pending(self, conversation_id: int) -> list[InjectQueueItem]:
+        async with self._db.session() as session:
+            result = await session.exec(
+                select(InjectQueueItem)
+                .where(
+                    InjectQueueItem.conversation_id == conversation_id,
+                    InjectQueueItem.status == "queued",
+                )
+                .order_by(col(InjectQueueItem.created_at), col(InjectQueueItem.id))
+            )
+            rows = list(result.all())
+        rows.sort(key=lambda r: (PRIORITY_RANK.get(r.priority, 9), r.created_at))
+        return rows
+
+    async def conversations_with_pending(self) -> list[int]:
+        async with self._db.session() as session:
+            result = await session.exec(
+                select(InjectQueueItem.conversation_id)
+                .where(InjectQueueItem.status == "queued")
+                .distinct()
+            )
+            return list(result.all())
+
+    async def start(self, items: Iterable[InjectQueueItem], turn_id: str) -> None:
+        await self._mark(items, status="running", turn_id=turn_id, delivered=True)
+
+    async def finish(
+        self, items: Iterable[InjectQueueItem], status: str = "done"
+    ) -> None:
+        await self._mark(items, status=status)
+
+    async def mark_interrupting(self, item: InjectQueueItem) -> None:
+        item.interrupted_turn = True
+        async with self._db.session() as session:
+            row = await session.get(InjectQueueItem, item.id)
+            if row is not None:
+                row.interrupted_turn = True
+                session.add(row)
+                await session.commit()
+
+    async def interrupted(self) -> Sequence[InjectQueueItem]:
+        async with self._db.session() as session:
+            result = await session.exec(
+                select(InjectQueueItem).where(InjectQueueItem.status == "running")
+            )
+            rows = list(result.all())
+            for row in rows:
+                row.status = "interrupted"
+                session.add(row)
+            await session.commit()
+        return rows
+
+    async def move(
+        self, source: Conversation, target: Conversation, *, priority: Priority
+    ) -> int:
+        """Re-home queued items of one priority (rotation carries normal over)."""
+        async with self._db.session() as session:
+            result = await session.exec(
+                select(InjectQueueItem).where(
+                    InjectQueueItem.conversation_id == source.id,
+                    InjectQueueItem.status == "queued",
+                    InjectQueueItem.priority == priority,
+                )
+            )
+            rows = list(result.all())
+            for row in rows:
+                row.conversation_id = cast("int", target.id)
+                session.add(row)
+            await session.commit()
+        return len(rows)
+
+    async def recent(
+        self, conversation_id: int, *, limit: int = 50
+    ) -> list[InjectQueueItem]:
+        async with self._db.session() as session:
+            result = await session.exec(
+                select(InjectQueueItem)
+                .where(InjectQueueItem.conversation_id == conversation_id)
+                .order_by(col(InjectQueueItem.id).desc())
+                .limit(limit)
+            )
+            return list(result.all())
+
+    async def latest(
+        self, conversation_ids: Iterable[int]
+    ) -> dict[int, InjectQueueItem]:
+        ids = list(conversation_ids)
+        if not ids:
+            return {}
+        newest = (
+            select(func.max(InjectQueueItem.id))
+            .where(col(InjectQueueItem.conversation_id).in_(ids))
+            .group_by(col(InjectQueueItem.conversation_id))
+        )
+        async with self._db.session() as session:
+            result = await session.exec(
+                select(InjectQueueItem).where(col(InjectQueueItem.id).in_(newest))
+            )
+            return {row.conversation_id: row for row in result.all()}
+
+    async def _mark(
+        self,
+        items: Iterable[InjectQueueItem],
+        *,
+        status: str,
+        turn_id: str | None = None,
+        delivered: bool = False,
+    ) -> None:
+        ids = [i.id for i in items if i.id is not None]
+        if not ids:
+            return
+        async with self._db.session() as session:
+            result = await session.exec(
+                select(InjectQueueItem).where(col(InjectQueueItem.id).in_(ids))
+            )
+            for row in result.all():
+                row.status = status
+                if turn_id is not None:
+                    row.turn_id = turn_id
+                if delivered:
+                    row.delivered_at = datetime.now(UTC)
+                session.add(row)
+            await session.commit()

src/beaver_gateway/conversations/kinds.py

@@ -1,4 +1,4 @@
-"""Conversation kinds (§3.1) as one closed type for agents, frontends, service."""
+"""Conversation kinds as one closed type for agents, frontends, service."""
 
 from __future__ import annotations
 

src/beaver_gateway/conversations/messaging.py

@@ -0,0 +1,156 @@
+"""Putting words into a conversation: a message, an inject, ``say``, a file."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, cast
+
+from beaver_gateway.conversations.turns import Turns
+from beaver_gateway.frontends.files import SendFileError
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+    from beaver_gateway.conversations.injects import Priority
+    from beaver_gateway.storage.models import Conversation, InjectQueueItem
+
+__all__ = ["Messaging"]
+
+_log = logging.getLogger(__name__)
+
+
+class Messaging(Turns):
+    async def post(
+        self,
+        conv: Conversation,
+        text: str,
+        *,
+        origin: str = "user",
+        attachments: list[dict[str, Any]] | None = None,
+    ) -> InjectQueueItem:
+        item = await self._queue.push(
+            conversation_id=cast("int", conv.id),
+            priority="user",
+            origin=origin,
+            text=text,
+            attachments=attachments,
+        )
+        await self.touch_user(conv)
+        self._bus.publish(
+            "message.queued",
+            conversation_id=conv.external_id,
+            item=item.id,
+            origin=origin,
+        )
+        self._ensure_worker(cast("int", conv.id))
+        return item
+
+    async def inject(
+        self,
+        conv: Conversation,
+        text: str,
+        *,
+        urgency: Priority = "normal",
+        origin: str = "system",
+        interrupt: bool = True,
+    ) -> InjectQueueItem:
+        if conv.kind == "master" and conv.status != "open":
+            live = await self.open_master()
+            if live is None:
+                _log.error(
+                    "inject (%s) for closed master %s: no open master, it stays there",
+                    origin,
+                    conv.external_id,
+                )
+            else:
+                _log.info(
+                    "inject (%s) for closed master %s goes to %s",
+                    origin,
+                    conv.external_id,
+                    live.external_id,
+                )
+                conv = live
+        item = await self._queue.push(
+            conversation_id=cast("int", conv.id),
+            priority=urgency,
+            origin=origin,
+            text=text,
+        )
+        self._bus.publish(
+            "inject.queued",
+            conversation_id=conv.external_id,
+            item=item.id,
+            priority=urgency,
+            origin=origin,
+        )
+        if urgency == "urgent" and interrupt:
+            backend = self._backend(conv.agent_name)
+            if await backend.interrupt(conv.external_id):
+                _log.info(
+                    "conversation %s: interrupted for urgent inject", conv.external_id
+                )
+                await self._queue.mark_interrupting(item)
+        self._ensure_worker(cast("int", conv.id))
+        return item
+
+    async def interrupt(self, conv: Conversation) -> bool:
+        """Cut the running turn; the reply so far still lands."""
+        try:
+            backend = self._backend(conv.agent_name)
+        except LookupError:
+            return False
+        return await backend.interrupt(conv.external_id)
+
+    async def say(self, conv: Conversation, text: str) -> dict[str, Any]:
+        runner = self._runners.get(cast("int", conv.id))
+        _log.info("say[%s]: %s", conv.external_id, text[:200])
+        return self._bus.publish(
+            "say",
+            conversation_id=conv.external_id,
+            text=text,
+            turn_id=runner.turn_id if runner is not None else None,
+        )
+
+    async def send_file(
+        self, conv: Conversation, path: str, *, caption: str = "", method: str = "auto"
+    ) -> str:
+        """Hand a file to the human: this conversation's window, else the master's."""
+        for target in (conv, await self.open_master()):
+            if target is None:
+                continue
+            for fe in self._frontends:
+                if target.kind in fe.kinds and fe.sends_files:
+                    note = await fe.send_file(
+                        target, path, caption=caption, method=method
+                    )
+                    _log.info("send_file[%s]: %s", target.external_id, note)
+                    return note
+        msg = (
+            "nowhere to send: no frontend that sends files shows this "
+            "conversation, and there is no open master"
+        )
+        raise SendFileError(msg)
+
+    def file_note(self) -> str:
+        """What the ``send_file`` tool tells the model about roots and size."""
+        sender = next((f for f in self._frontends if f.sends_files), None)
+        return sender.file_note() if sender else "no frontend here sends files"
+
+    async def schedule(
+        self,
+        conv: Conversation,
+        at: str,
+        text: str,
+        *,
+        urgency: Priority = "wake",
+        dedupe_key: str | None = None,
+    ) -> tuple[int | None, datetime]:
+        if self.scheduler is None:
+            msg = "no scheduler; `schedule` is unavailable"
+            raise RuntimeError(msg)
+        return await self.scheduler.schedule(
+            conv, at, text, urgency=urgency, dedupe_key=dedupe_key
+        )
+
+    async def schedules(self, conv: Conversation | None = None) -> list[dict[str, Any]]:
+        return await self.scheduler.scheduled(conv) if self.scheduler else []

src/beaver_gateway/conversations/questions.py

@@ -0,0 +1,85 @@
+"""``AskUserQuestion`` from inside a turn: answered or timed out."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from typing import TYPE_CHECKING, Any, cast
+from uuid import uuid4
+
+from beaver_gateway.conversations.spawning import Spawning
+from beaver_gateway.conversations.state import Question
+
+if TYPE_CHECKING:
+    from beaver_gateway.storage.models import Conversation
+
+__all__ = ["Questions"]
+
+
+class Questions(Spawning):
+    async def ask(self, key: str, payload: dict[str, Any]) -> str | None:
+        """Show the question and wait; ``None`` when nobody answered in time."""
+        conv = await self.get(key)
+        if conv is None:
+            return None
+        runner = self._runners.get(cast("int", conv.id))
+        question_id = f"q_{uuid4().hex[:10]}"
+        pending = Question(
+            conversation_id=key,
+            turn_id=runner.turn_id if runner is not None else None,
+            questions=list(payload.get("questions") or []),
+            answer=asyncio.get_running_loop().create_future(),
+        )
+        self._questions[question_id] = pending
+        await self._set_pending_question(conv, value=True)
+        self._bus.publish(
+            "question",
+            conversation_id=key,
+            turn_id=pending.turn_id,
+            question_id=question_id,
+            questions=pending.questions,
+            timeout=self._question_timeout,
+        )
+        try:
+            async with asyncio.timeout(self._question_timeout):
+                answer = await pending.answer
+        except TimeoutError:
+            self._bus.publish(
+                "question.timeout",
+                conversation_id=key,
+                turn_id=pending.turn_id,
+                question_id=question_id,
+            )
+            return None
+        finally:
+            self._questions.pop(question_id, None)
+            await self._set_pending_question(conv, value=False)
+        self._bus.publish(
+            "question.answered",
+            conversation_id=key,
+            turn_id=pending.turn_id,
+            question_id=question_id,
+            answer=answer,
+        )
+        return answer
+
+    def answer(self, question_id: str, answer: str) -> bool:
+        pending = self._questions.get(question_id)
+        if pending is None or pending.answer.done():
+            return False
+        pending.answer.set_result(answer)
+        return True
+
+    def answer_text(self, answer: str | None) -> str:
+        if answer is None:
+            return self._texts.unanswered.format(
+                minutes=round(self._question_timeout / 60)
+            )
+        return self._texts.answered.format(answer=answer)
+
+    async def _set_pending_question(self, conv: Conversation, *, value: bool) -> None:
+        async def apply(row: Conversation) -> None:
+            row.pending_question = value
+
+        with contextlib.suppress(LookupError):
+            await self._update(conv, apply)

src/beaver_gateway/conversations/rotation.py

@@ -0,0 +1,127 @@
+"""Master rotation: one logical master thread, many physical sessions.
+
+When the policy says so, a new master takes over the window; the old one
+hands out, closes, and its branches and queued normal injects move over.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from datetime import UTC, date, datetime, timedelta
+from typing import TYPE_CHECKING
+from zoneinfo import ZoneInfo
+
+if TYPE_CHECKING:
+    from beaver_gateway.conversations.service import Conversations
+    from beaver_gateway.storage.models import Conversation
+
+__all__ = ["HandoutContext", "Rotation", "RotationPolicy"]
+
+_log = logging.getLogger("beaver_gateway.conversations.rotation")
+
+
+@dataclass(frozen=True, slots=True)
+class RotationPolicy:
+    tz: str = "UTC"
+    hour: int = 4
+    night_silence: timedelta = timedelta(hours=3)
+    max_age: timedelta = timedelta(hours=36)
+    short_silence: timedelta = timedelta(minutes=30)
+    max_context_tokens: int = 80_000
+
+    def reason(
+        self, master: Conversation, *, now: datetime, context_tokens: int
+    ) -> str | None:
+        zone = ZoneInfo(self.tz)
+        created = _aware(master.created_at)
+        silence = now - _aware(master.last_user_activity_at or master.created_at)
+        boundary = now.astimezone(zone).replace(
+            hour=self.hour, minute=0, second=0, microsecond=0
+        )
+        if now.astimezone(zone) < boundary:
+            boundary -= timedelta(days=1)
+        if created < boundary and silence > self.night_silence:
+            return "night"
+        if now - created > self.max_age and silence > self.short_silence:
+            return "age"
+        if context_tokens > self.max_context_tokens and silence > self.short_silence:
+            return "context"
+        return None
+
+    def day_of(self, master: Conversation) -> date:
+        return _aware(master.created_at).astimezone(ZoneInfo(self.tz)).date()
+
+
+@dataclass(frozen=True, slots=True)
+class HandoutContext:
+    day: date
+    master: Conversation
+    reason: str
+
+
+class Rotation:
+    def __init__(
+        self, conversations: Conversations, policy: RotationPolicy | None = None
+    ) -> None:
+        self._conversations = conversations
+        self.policy = policy or RotationPolicy()
+
+    async def due(self, now: datetime | None = None) -> list[tuple[Conversation, str]]:
+        now = now or datetime.now(UTC)
+        out: list[tuple[Conversation, str]] = []
+        for master in await self._conversations.find(kind="master", status="open"):
+            tokens = await self._conversations.context_tokens(master)
+            reason = self.policy.reason(master, now=now, context_tokens=tokens)
+            if reason is not None:
+                out.append((master, reason))
+        return out
+
+    async def tick(self, now: datetime | None = None) -> list[Conversation]:
+        rotated: list[Conversation] = []
+        for master, reason in await self.due(now):
+            new = await self.rotate(master, reason)
+            if new is not None:
+                rotated.append(new)
+        return rotated
+
+    async def rotate(self, old: Conversation, reason: str) -> Conversation | None:
+        conversations = self._conversations
+        if await conversations.busy(old):
+            _log.info("rotation of %s skipped: busy", old.external_id)
+            return None
+        new = await conversations.spawn(
+            kind="master", agent=old.agent_name, seed="morning", origin="rotation"
+        )
+        day = self.policy.day_of(old)
+        _log.info(
+            "rotation (%s): %s -> %s, handout for %s",
+            reason,
+            old.external_id,
+            new.external_id,
+            day,
+        )
+        await conversations.handout(
+            old, HandoutContext(day=day, master=old, reason=reason)
+        )
+        await conversations.close(old)
+        for branch in await conversations.find(parent=old, limit=1000):
+            if branch.status == "open":
+                await conversations.reparent(branch, new)
+            elif not branch.running_turn:
+                await conversations.mark_closed(branch)
+        moved = await conversations.queue.move(old, new, priority="normal")
+        await conversations.new_day(new, reason=reason, moved=moved)
+        conversations.bus.publish(
+            "conversation.rotated",
+            conversation_id=new.external_id,
+            closed=old.external_id,
+            reason=reason,
+            handout_day=day.isoformat(),
+            moved=moved,
+        )
+        return new
+
+
+def _aware(value: datetime) -> datetime:
+    return value if value.tzinfo is not None else value.replace(tzinfo=UTC)

src/beaver_gateway/conversations/rows.py

@@ -0,0 +1,563 @@
+"""The conversation rows: create, find, bind to windows, flags, status, history."""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any, cast
+from uuid import uuid4
+
+from sqlalchemy import String, func
+from sqlalchemy import cast as sa_cast
+from sqlmodel import col, select
+
+from beaver_gateway.backends.transcript import (
+    messages_from_entries,
+    render_messages,
+    text_of,
+)
+from beaver_gateway.conversations.kinds import KINDS, Kind
+from beaver_gateway.conversations.state import State, iso
+from beaver_gateway.frontends.markdown.history import load_messages
+from beaver_gateway.storage.models import (
+    Conversation,
+    ConversationBinding,
+    ConversationMessage,
+    RateLimit,
+    TranscriptEntry,
+    Usage,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable, Iterable
+
+    from beaver_gateway.frontends.base import Frontend
+
+__all__ = [
+    "MASTER_ALIAS",
+    "PARENT_ALIAS",
+    "STATUSES",
+    "TITLE_MAX",
+    "Rows",
+    "context_of",
+    "implied_title",
+]
+
+_log = logging.getLogger(__name__)
+
+MASTER_ALIAS = "master"
+PARENT_ALIAS = "parent"
+STATUSES = ("open", "merged", "closed", "archived")
+TITLE_MAX = 80
+
+
+class Rows(State):
+    async def create(
+        self,
+        *,
+        kind: Kind,
+        agent: str,
+        parent: Conversation | None = None,
+        title: str | None = None,
+        origin: str = "api",
+        session_id: str | None = None,
+        flags: dict[str, Any] | None = None,
+    ) -> Conversation:
+        if kind not in KINDS:
+            msg = f"unknown conversation kind {kind!r}"
+            raise ValueError(msg)
+        if not self._claude_agent(agent).serves(kind):
+            msg = f"agent {agent!r} does not serve kind {kind!r}"
+            raise ValueError(msg)
+        now = datetime.now(UTC)
+        row = Conversation(
+            frontend=origin,
+            external_id=str(uuid4()),
+            agent_name=agent,
+            kind=kind,
+            parent_id=parent.id if parent is not None else None,
+            title=title,
+            session_id=session_id,
+            flags=dict(flags or {}),
+            last_activity_at=now,
+        )
+        async with self._db.session() as session:
+            session.add(row)
+            await session.commit()
+            await session.refresh(row)
+        self._bus.publish("conversation.created", **self.public(row))
+        return row
+
+    async def get(self, public_id: str) -> Conversation | None:
+        async with self._db.session() as session:
+            result = await session.exec(
+                select(Conversation).where(Conversation.external_id == public_id)
+            )
+            return result.first()
+
+    async def get_row(self, row_id: int) -> Conversation | None:
+        async with self._db.session() as session:
+            return await session.get(Conversation, row_id)
+
+    async def resolve(
+        self, key: str, *, origin: Conversation | None = None
+    ) -> Conversation | None:
+        """By public id, or ``master`` / ``parent`` relative to ``origin``."""
+        key = key.strip()
+        if key == MASTER_ALIAS:
+            return await self.open_master()
+        if key == PARENT_ALIAS:
+            if origin is None or origin.parent_id is None:
+                return None
+            return await self.get_row(origin.parent_id)
+        return await self.get(key)
+
+    async def open_master(self) -> Conversation | None:
+        masters = await self.find(kind="master", status="open", limit=1)
+        return masters[0] if masters else None
+
+    async def find(
+        self,
+        *,
+        status: str | None = None,
+        kind: str | None = None,
+        parent: Conversation | None = None,
+        limit: int = 200,
+    ) -> list[Conversation]:
+        stmt = select(Conversation).order_by(col(Conversation.id).desc()).limit(limit)
+        if status is not None:
+            stmt = stmt.where(Conversation.status == status)
+        if kind is not None:
+            stmt = stmt.where(Conversation.kind == kind)
+        if parent is not None:
+            stmt = stmt.where(Conversation.parent_id == parent.id)
+        async with self._db.session() as session:
+            return list((await session.exec(stmt)).all())
+
+    async def search(self, query: str, *, limit: int = 20) -> list[Conversation]:
+        needle = f"%{query}%"
+        by_title = select(Conversation.id).where(col(Conversation.title).ilike(needle))
+        by_first = select(ConversationMessage.conversation_id).where(
+            ConversationMessage.seq == 0,
+            col(ConversationMessage.content_json).ilike(needle),
+        )
+        by_entry = (
+            select(Conversation.id)
+            .join(
+                TranscriptEntry,
+                col(TranscriptEntry.session_id) == col(Conversation.session_id),
+            )
+            .where(sa_cast(col(TranscriptEntry.entry), String).ilike(needle))
+        )
+        stmt = (
+            select(Conversation)
+            .where(col(Conversation.id).in_(by_title.union(by_first, by_entry)))
+            .order_by(col(Conversation.id).desc())
+            .limit(limit)
+        )
+        async with self._db.session() as session:
+            return list((await session.exec(stmt)).all())
+
+    async def bindings(self, conv: Conversation) -> list[ConversationBinding]:
+        async with self._db.session() as session:
+            result = await session.exec(
+                select(ConversationBinding)
+                .where(ConversationBinding.conversation_id == conv.id)
+                .order_by(col(ConversationBinding.id))
+            )
+            return list(result.all())
+
+    async def bind(
+        self,
+        conv: Conversation,
+        *,
+        frontend: str,
+        external_id: str,
+        visible: bool = True,
+    ) -> ConversationBinding:
+        if conv.kind not in self.frontend(frontend).kinds:
+            msg = f"frontend {frontend!r} does not show kind {conv.kind!r}"
+            raise ValueError(msg)
+        async with self._db.session() as session:
+            existing = list(
+                (
+                    await session.exec(
+                        select(ConversationBinding).where(
+                            ConversationBinding.conversation_id == conv.id,
+                            ConversationBinding.frontend == frontend,
+                        )
+                    )
+                ).all()
+            )
+            row = next((b for b in existing if b.external_id == external_id), None)
+            if visible:
+                for other in existing:
+                    if other is not row and other.visible:
+                        other.visible = False
+                        session.add(other)
+                same_window = await session.exec(
+                    select(ConversationBinding).where(
+                        ConversationBinding.frontend == frontend,
+                        ConversationBinding.external_id == external_id,
+                        ConversationBinding.conversation_id != conv.id,
+                        col(ConversationBinding.visible).is_(True),
+                    )
+                )
+                for other in same_window.all():
+                    other.visible = False
+                    session.add(other)
+            if row is None:
+                row = ConversationBinding(
+                    conversation_id=cast("int", conv.id),
+                    frontend=frontend,
+                    external_id=external_id,
+                    visible=visible,
+                )
+            else:
+                row.visible = visible
+            session.add(row)
+            await session.commit()
+            await session.refresh(row)
+        self._bus.publish(
+            "conversation.bound",
+            conversation_id=conv.external_id,
+            frontend=frontend,
+            external_id=external_id,
+            visible=visible,
+        )
+        return row
+
+    async def find_bound(
+        self, *, frontend: str, external_id: str
+    ) -> Conversation | None:
+        async with self._db.session() as session:
+            result = await session.exec(
+                select(Conversation)
+                .join(
+                    ConversationBinding,
+                    col(ConversationBinding.conversation_id) == col(Conversation.id),
+                )
+                .where(
+                    ConversationBinding.frontend == frontend,
+                    ConversationBinding.external_id == external_id,
+                    col(ConversationBinding.visible).is_(True),
+                )
+                .order_by(col(Conversation.id).desc())
+            )
+            return result.first()
+
+    async def last_binding(
+        self, *, frontend: str, kind: str
+    ) -> ConversationBinding | None:
+        """The window ``frontend`` last used for ``kind``; outlives a rotation."""
+        async with self._db.session() as session:
+            result = await session.exec(
+                select(ConversationBinding)
+                .join(
+                    Conversation,
+                    col(Conversation.id) == col(ConversationBinding.conversation_id),
+                )
+                .where(
+                    ConversationBinding.frontend == frontend, Conversation.kind == kind
+                )
+                .order_by(col(ConversationBinding.id).desc())
+            )
+            return result.first()
+
+    async def window_of(self, conv: Conversation) -> str | None:
+        for binding in await self.bindings(conv):
+            if binding.visible:
+                return binding.external_id
+        return None
+
+    async def set_flags(
+        self, conv: Conversation, flags: dict[str, Any]
+    ) -> Conversation:
+        async def apply(row: Conversation) -> None:
+            row.flags = {**row.flags, **flags}
+
+        return await self._update(conv, apply)
+
+    async def set_status(self, conv: Conversation, status: str) -> Conversation:
+        if status not in STATUSES:
+            msg = f"unknown status {status!r}"
+            raise ValueError(msg)
+
+        async def apply(row: Conversation) -> None:
+            row.status = status
+
+        return await self._update(conv, apply)
+
+    async def set_title(self, conv: Conversation, title: str) -> Conversation:
+        async def apply(row: Conversation) -> None:
+            row.title = title
+
+        return await self._update(conv, apply)
+
+    async def touch_user(self, conv: Conversation) -> Conversation:
+        async def apply(row: Conversation) -> None:
+            row.last_user_activity_at = datetime.now(UTC)
+
+        return await self._update(conv, apply)
+
+    async def reparent(self, conv: Conversation, parent: Conversation) -> Conversation:
+        async def apply(row: Conversation) -> None:
+            row.parent_id = parent.id
+
+        return await self._update(conv, apply)
+
+    async def _update(
+        self, conv: Conversation, apply: Callable[[Conversation], Awaitable[None]]
+    ) -> Conversation:
+        async with self._db.session() as session:
+            row = await session.get(Conversation, conv.id)
+            if row is None:
+                msg = f"conversation {conv.external_id} vanished"
+                raise LookupError(msg)
+            await apply(row)
+            row.updated_at = datetime.now(UTC)
+            session.add(row)
+            await session.commit()
+            await session.refresh(row)
+        self._bus.publish("conversation.updated", **self.public(row))
+        return row
+
+    def public(self, conv: Conversation) -> dict[str, Any]:
+        return {
+            "id": conv.external_id,
+            "kind": conv.kind,
+            "agent": conv.agent_name,
+            "title": conv.title,
+            "status": conv.status,
+            "parent_row": conv.parent_id,
+            "session_id": conv.session_id,
+            "running_turn": conv.running_turn,
+            "pending_question": conv.pending_question,
+            "flags": conv.flags,
+            "origin": conv.frontend,
+            "created_at": iso(conv.created_at),
+            "last_user_activity_at": iso(conv.last_user_activity_at),
+            "last_activity_at": iso(conv.last_activity_at),
+        }
+
+    async def describe(self, conv: Conversation) -> dict[str, Any]:
+        out = self.public(conv)
+        out["title"] = await self.implied_title(conv)
+        out["context_tokens"] = await self.context_tokens(conv)
+        parent = await self.get_row(conv.parent_id) if conv.parent_id else None
+        out["parent"] = parent.external_id if parent is not None else None
+        out["bindings"] = [
+            {"frontend": b.frontend, "external_id": b.external_id, "visible": b.visible}
+            for b in await self.bindings(conv)
+        ]
+        live = self._pool.get(conv.external_id)
+        out["live"] = live is not None
+        out["busy"] = live.busy if live is not None else False
+        runner = self._runners.get(cast("int", conv.id))
+        out["turn"] = runner.snapshot() if runner is not None else None
+        pending = self.pending_question(conv.external_id)
+        out["question"] = (
+            {"id": pending[0], "questions": pending[1]} if pending else None
+        )
+        return out
+
+    def pending_question(self, key: str) -> tuple[str, list[dict[str, Any]]] | None:
+        for question_id, pending in self._questions.items():
+            if pending.conversation_id == key and not pending.answer.done():
+                return question_id, pending.questions
+        return None
+
+    async def rate_limits(self, *, limit: int = 100) -> list[RateLimit]:
+        async with self._db.session() as session:
+            result = await session.exec(
+                select(RateLimit).order_by(col(RateLimit.id).desc()).limit(limit)
+            )
+            return list(result.all())
+
+    async def context_tokens(self, conv: Conversation) -> int:
+        async with self._db.session() as session:
+            row = (
+                await session.exec(
+                    select(Usage)
+                    .where(Usage.conversation_id == conv.external_id)
+                    .order_by(col(Usage.id).desc())
+                    .limit(1)
+                )
+            ).first()
+        return context_of(row)
+
+    async def context_tokens_by_id(self, ids: Iterable[str]) -> dict[str, int]:
+        wanted = list(ids)
+        if not wanted:
+            return {}
+        latest = (
+            select(func.max(Usage.id))
+            .where(col(Usage.conversation_id).in_(wanted))
+            .group_by(Usage.conversation_id)
+        )
+        async with self._db.session() as session:
+            rows = (
+                await session.exec(select(Usage).where(col(Usage.id).in_(latest)))
+            ).all()
+        return {
+            cast("str", row.conversation_id): context_of(row)
+            for row in rows
+            if row.conversation_id
+        }
+
+    async def usage_tokens(self, since: datetime) -> int:
+        async with self._db.session() as session:
+            rows = (
+                await session.exec(
+                    select(Usage).where(
+                        col(Usage.ts) >= since.astimezone(UTC).replace(tzinfo=None)
+                    )
+                )
+            ).all()
+        return sum(
+            r.input_tokens + r.output_tokens + r.cache_creation_tokens for r in rows
+        )
+
+    async def busy(self, conv: Conversation) -> bool:
+        row = await self.get_row(cast("int", conv.id)) or conv
+        if row.running_turn or row.pending_question:
+            return True
+        live = self._pool.get(row.external_id)
+        if live is not None and live.busy:
+            return True
+        pending = await self._queue.pending(cast("int", row.id))
+        return any(i.priority in ("user", "urgent", "wake") for i in pending)
+
+    @property
+    def frontends(self) -> list[Frontend]:
+        return list(self._frontends)
+
+    def frontend(self, name: str) -> Frontend:
+        for fe in self._frontends:
+            if fe.name == name:
+                return fe
+        msg = f"unknown frontend {name!r}"
+        raise ValueError(msg)
+
+    def default_agent(self, kind: Kind) -> str | None:
+        for fe in self._frontends:
+            if kind in fe.kinds and (agent := fe.agent_for(kind)):
+                return agent
+        return None
+
+    async def materialize(self, conv: Conversation) -> ConversationBinding | None:
+        for fe in self._frontends:
+            if conv.kind not in fe.kinds:
+                continue
+            binding = await fe.materialize(conv)
+            if binding is not None:
+                return binding
+        return None
+
+    async def mark_closed(self, conv: Conversation) -> bool:
+        marked = False
+        for fe in self._frontends:
+            if conv.kind in fe.kinds:
+                try:
+                    marked = await fe.mark_closed(conv) or marked
+                except Exception:  # noqa: BLE001
+                    _log.exception("%s could not mark %s", fe.name, conv.external_id)
+        return marked
+
+    async def read(self, conv: Conversation, *, window: int | None = None) -> str:
+        return render_messages(await self.history(conv), window=window)
+
+    async def history(self, conv: Conversation) -> list[dict[str, Any]]:
+        if conv.session_id is None:
+            async with self._db.session() as session:
+                return await load_messages(
+                    session, conversation_id=cast("int", conv.id)
+                )
+        return messages_from_entries(
+            cast("Any", await self.entries(conv)), with_ts=True
+        )
+
+    async def entries(self, conv: Conversation, *, subpath: str = "") -> list[Any]:
+        if conv.session_id is None:
+            return []
+        key = {**self._store_key(conv), "subpath": subpath}
+        return list(await self._store.load(cast("Any", key)) or [])
+
+    async def subpaths(self, conv: Conversation) -> list[str]:
+        if conv.session_id is None:
+            return []
+        return list(await self._store.list_subkeys(cast("Any", self._store_key(conv))))
+
+    async def first_user_texts(self, ids: Iterable[int]) -> dict[int, str]:
+        wanted = list(ids)
+        if not wanted:
+            return {}
+        async with self._db.session() as session:
+            rows = (
+                await session.exec(
+                    select(ConversationMessage).where(
+                        col(ConversationMessage.conversation_id).in_(wanted),
+                        ConversationMessage.seq == 0,
+                        ConversationMessage.role == "user",
+                    )
+                )
+            ).all()
+        return {
+            r.conversation_id: text_of(json.loads(r.content_json)).strip() for r in rows
+        }
+
+    async def implied_title(self, conv: Conversation) -> str | None:
+        if conv.title:
+            return conv.title
+        text = (await self.first_user_texts([cast("int", conv.id)])).get(
+            cast("int", conv.id)
+        )
+        return implied_title(text)
+
+    async def chat_name(self, conv: Conversation) -> str:
+        """What a ``[[wikilink]]`` to the chat says: the file's stem when it has one."""
+        window = await self.window_of(conv)
+        if window and window.endswith(".md"):
+            return window.rsplit("/", 1)[-1][: -len(".md")]
+        return await self.implied_title(conv) or conv.external_id
+
+    async def adopt(self, *, kind: Kind, first_user_text: str) -> Conversation | None:
+        """The one unbound, session-less conversation whose history starts here."""
+        text = first_user_text.strip()
+        if not text:
+            return None
+        bound = select(ConversationBinding.conversation_id).where(
+            col(ConversationBinding.visible).is_(True)
+        )
+        async with self._db.session() as session:
+            rows = (
+                await session.exec(
+                    select(Conversation).where(
+                        Conversation.kind == kind,
+                        Conversation.status == "open",
+                        col(Conversation.session_id).is_(None),
+                        col(Conversation.id).not_in(bound),
+                    )
+                )
+            ).all()
+        firsts = await self.first_user_texts(cast("int", r.id) for r in rows)
+        hits = [r for r in rows if firsts.get(cast("int", r.id)) == text]
+        return hits[0] if len(hits) == 1 else None
+
+
+def implied_title(text: str | None) -> str | None:
+    if not text:
+        return None
+    line = text.strip().splitlines()[0].strip()
+    return line if len(line) <= TITLE_MAX else line[: TITLE_MAX - 1] + "…"
+
+
+def context_of(row: Usage | None) -> int:
+    """The last API call's input, or the per-call average for older rows."""
+    if row is None:
+        return 0
+    if row.context_tokens:
+        return row.context_tokens
+    total = row.input_tokens + row.cache_read_tokens + row.cache_creation_tokens
+    return round(total / max(row.num_turns or 1, 1))

src/beaver_gateway/conversations/seeds.py

@@ -0,0 +1,71 @@
+"""How a new conversation starts: the seed rendered into its first prompt."""
+
+from __future__ import annotations
+
+import inspect
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any, cast
+
+from beaver_gateway.conversations.kinds import as_kind
+from beaver_gateway.conversations.rows import Rows
+from beaver_gateway.conversations.texts import SeedContext
+
+if TYPE_CHECKING:
+    from beaver_gateway.storage.models import Conversation
+
+__all__ = ["SEEDS", "Seeds"]
+
+SEEDS = ("clean", "morning", "copy", "brief")
+
+
+class Seeds(Rows):
+    async def pending_seed(self, conv: Conversation) -> str | None:
+        """A seed nobody has spoken after yet: rendered now, spent once."""
+        seed = conv.flags.get("seed")
+        if not seed:
+            return None
+        parent = await self.get_row(conv.parent_id) if conv.parent_id else None
+        ctx = SeedContext(
+            kind=as_kind(conv.kind),
+            seed=str(seed),
+            agent=conv.agent_name,
+            parent=parent,
+            text=None,
+            title=conv.title,
+        )
+        window = conv.flags.get("seed_window")
+        text = await self.seed_text(
+            ctx, window=window if isinstance(window, int) else None
+        )
+        await self.set_flags(conv, {"seed": None, "seed_window": None})
+        return text
+
+    async def seed_text(self, ctx: SeedContext, *, window: int | None) -> str:
+        texts = self._texts
+        stamp = datetime.now(UTC).astimezone().strftime("%Y-%m-%d %H:%M")
+        head = texts.seed_head.format(
+            seed=ctx.seed,
+            kind=ctx.kind,
+            title=f" «{ctx.title}»" if ctx.title else "",
+            stamp=stamp,
+        )
+        body: str | None = None
+        if texts.seed is not None:
+            produced: Any = texts.seed(ctx)
+            if inspect.isawaitable(produced):
+                produced = await produced
+            body = cast("str | None", produced)
+        if body is None:
+            if ctx.seed == "brief":
+                body = ctx.text
+            elif ctx.seed == "copy":
+                scope = (
+                    texts.seed_copy_window.format(window=window)
+                    if window
+                    else texts.seed_copy_all
+                )
+                body = texts.seed_copy.format(scope=scope)
+            elif ctx.seed == "morning":
+                body = texts.seed_morning_missing
+        parts = [head, body, ctx.text if ctx.seed != "brief" else None]
+        return "\n\n".join(p for p in parts if p)

src/beaver_gateway/conversations/service.py

@@ -0,0 +1,158 @@
+"""``Conversations`` - the service every frontend, job and gateway tool talks to.
+
+Built as layers, one file each: rows → seeds → turns → messaging →
+spawning → questions → closing; this file adds start, stop and restart
+recovery. A turn started by a user message streams back to whoever asked;
+a turn started by an inject streams nowhere and can only speak via ``say``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import re
+from datetime import UTC, datetime, timedelta, tzinfo
+
+from sqlmodel import col, select
+
+from beaver_gateway.conversations.closing import Closing, DistillResult
+from beaver_gateway.conversations.kinds import KINDS
+from beaver_gateway.conversations.rows import context_of, implied_title
+from beaver_gateway.conversations.seeds import SEEDS
+from beaver_gateway.conversations.spawning import ForkResult
+from beaver_gateway.conversations.state import aware
+from beaver_gateway.conversations.texts import (
+    ConversationTexts,
+    NewDayContext,
+    SeedContext,
+    UserSaid,
+)
+from beaver_gateway.storage.models import Conversation
+
+__all__ = [
+    "KINDS",
+    "SEEDS",
+    "ConversationTexts",
+    "Conversations",
+    "DistillResult",
+    "ForkResult",
+    "NewDayContext",
+    "SeedContext",
+    "UserSaid",
+    "context_of",
+    "implied_title",
+    "parse_at",
+]
+
+_log = logging.getLogger(__name__)
+
+_RELATIVE = re.compile(r"^\+(\d+)\s*([smhd])$")
+_UNITS = {"s": 1, "m": 60, "h": 3600, "d": 86400}
+
+
+class Conversations(Closing):
+    async def start(self) -> None:
+        await self.recover()
+        for row_id in await self._queue.conversations_with_pending():
+            self._ensure_worker(row_id)
+        self._idle_task = asyncio.create_task(self._idle_loop())
+
+    async def stop(self) -> None:
+        tasks = list(self._tasks)
+        if self._idle_task is not None:
+            tasks.append(self._idle_task)
+        for task in tasks:
+            task.cancel()
+        for task in tasks:
+            with contextlib.suppress(BaseException):
+                await task
+        self._tasks.clear()
+        self._idle_task = None
+
+    async def recover(self) -> list[Conversation]:
+        """Repair the transcripts of turns a restart cut and tell each conversation."""
+        async with self._db.session() as session:
+            result = await session.exec(
+                select(Conversation).where(col(Conversation.running_turn).is_not(None))
+            )
+            cut = list(result.all())
+        for conv in cut:
+            fixed = 0
+            if conv.session_id is not None:
+                backend = self._backend(conv.agent_name)
+                try:
+                    fixed = await backend.repair_session(
+                        conv.session_id, text=self._texts.interrupted
+                    )
+                except Exception:  # noqa: BLE001
+                    _log.exception("repair of %s failed", conv.session_id)
+            turn_id = conv.running_turn
+
+            async def clear(row: Conversation) -> None:
+                row.running_turn = None
+                row.pending_question = False
+
+            await self._update(conv, clear)
+            note = self._texts.cut_by_restart.format(turn_id=turn_id)
+            if fixed:
+                note += self._texts.repaired_tools.format(
+                    fixed=fixed, interrupted=self._texts.interrupted
+                )
+            await self.inject(conv, note, urgency="normal", origin="system")
+            _log.warning("conversation %s: %s", conv.external_id, note)
+        for item in await self._queue.interrupted():
+            _log.warning(
+                "queue item #%s (%s) was running at restart; marked interrupted",
+                item.id,
+                item.priority,
+            )
+        return cut
+
+    async def _idle_loop(self) -> None:
+        while True:
+            try:
+                await self._emit_idle()
+            except Exception:  # noqa: BLE001
+                _log.exception("idle watcher failed")
+            await asyncio.sleep(self._idle_interval)
+
+    async def _emit_idle(self) -> None:
+        if not self._idle_days:
+            return
+        now = datetime.now(UTC)
+        for conv in await self.find(status="open", limit=10_000):
+            last = aware(conv.last_activity_at or conv.created_at)
+            days = int((now - last).total_seconds() // 86400)
+            due = [d for d in self._idle_days if days >= d]
+            if not due:
+                continue
+            notified = int(conv.flags.get("idle_notified", 0) or 0)
+            if due[-1] <= notified:
+                continue
+            await self.set_flags(conv, {"idle_notified": due[-1]})
+            bindings = await self.bindings(conv)
+            self._bus.publish(
+                "conversation.idle",
+                conversation_id=conv.external_id,
+                kind=conv.kind,
+                agent=conv.agent_name,
+                days=due[-1],
+                bindings=[
+                    {"frontend": b.frontend, "external_id": b.external_id}
+                    for b in bindings
+                    if b.visible
+                ],
+            )
+
+
+def parse_at(at: str, tz: tzinfo = UTC) -> datetime:
+    raw = at.strip()
+    match = _RELATIVE.match(raw.replace(" ", ""))
+    if match:
+        amount, unit = match.groups()
+        return datetime.now(UTC) + timedelta(seconds=int(amount) * _UNITS[unit])
+    parsed = datetime.fromisoformat(raw)
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=tz)
+    return parsed.astimezone(UTC)

src/beaver_gateway/conversations/spawning.py

@@ -0,0 +1,203 @@
+"""New conversations from old ones: spawn with a seed, fork a copy, merge back."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, cast
+
+from claude_agent_sdk import fork_session_via_store, project_key_for_directory
+
+from beaver_gateway.backends.transcript import strip_tool_entries, window_entries
+from beaver_gateway.conversations.messaging import Messaging
+from beaver_gateway.conversations.seeds import SEEDS
+from beaver_gateway.conversations.texts import SeedContext
+
+if TYPE_CHECKING:
+    from beaver_gateway.backends.capture import TurnCapture
+    from beaver_gateway.conversations.kinds import Kind
+    from beaver_gateway.storage.models import Conversation
+
+__all__ = ["ForkResult", "Spawning"]
+
+_log = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True, slots=True)
+class ForkResult:
+    conversation: Conversation
+    text: str
+    capture: TurnCapture
+
+
+class Spawning(Messaging):
+    async def spawn(
+        self,
+        *,
+        kind: Kind,
+        agent: str | None = None,
+        seed: str = "clean",
+        parent: Conversation | None = None,
+        text: str | None = None,
+        title: str | None = None,
+        window: int | None = None,
+        origin: str = "api",
+        binding: tuple[str, str] | None = None,
+        flags: dict[str, Any] | None = None,
+        attachments: list[dict[str, Any]] | None = None,
+    ) -> Conversation:
+        """Create a conversation in a window and queue its seed.
+
+        ``binding`` reuses a window that already exists instead of asking the
+        home frontend for one. Without ``text`` the seed waits in ``flags``
+        and opens the first turn, so a fresh window costs nothing until
+        someone speaks.
+        """
+        if seed not in SEEDS:
+            msg = f"unknown seed {seed!r}"
+            raise ValueError(msg)
+        if seed == "brief" and not text:
+            msg = "seed=brief needs text"
+            raise ValueError(msg)
+        if agent is None and kind == "branch" and parent is not None:
+            agent = parent.agent_name
+        agent = agent or self.default_agent(kind)
+        if agent is None:
+            msg = f"no default agent for kind {kind!r}; pass `agent`"
+            raise ValueError(msg)
+        session_id: str | None = None
+        if seed == "copy":
+            if parent is None or parent.session_id is None:
+                msg = "seed=copy needs a parent with a session"
+                raise ValueError(msg)
+            session_id = await self._copy_session(
+                parent, window=window, strip_tools=False
+            )
+        conv = await self.create(
+            kind=kind,
+            agent=agent,
+            parent=parent,
+            title=title,
+            origin=origin,
+            session_id=session_id,
+            flags=flags,
+        )
+        if binding is not None:
+            await self.bind(conv, frontend=binding[0], external_id=binding[1])
+        else:
+            await self.materialize(conv)
+        ctx = SeedContext(
+            kind=kind, seed=seed, agent=agent, parent=parent, text=text, title=title
+        )
+        if text is None:
+            return await self.set_flags(conv, {"seed": seed, "seed_window": window})
+        await self._queue.push(
+            conversation_id=cast("int", conv.id),
+            priority="user",
+            origin=f"seed:{seed}" if seed == "brief" else origin,
+            text=await self.seed_text(ctx, window=window),
+            attachments=attachments,
+        )
+        self._ensure_worker(cast("int", conv.id))
+        return conv
+
+    async def fork(
+        self,
+        conv: Conversation,
+        prompt: str,
+        *,
+        window: int | None = None,
+        strip_tools: bool = False,
+        title: str | None = None,
+        agent: str | None = None,
+    ) -> ForkResult:
+        """Copy the history into a one-off session, run ``prompt`` on it, close it."""
+        agent = agent or conv.agent_name
+        session_id = await self._copy_session(
+            conv, window=window, strip_tools=strip_tools, agent=agent
+        )
+        child = await self.create(
+            kind="fork",
+            agent=agent,
+            parent=conv,
+            title=title or f"fork: {conv.title or conv.external_id}",
+            origin="system",
+            session_id=session_id,
+        )
+        try:
+            text, capture = await self.run_text_turn(
+                child, prompt, origin="fork", tools=False
+            )
+        finally:
+            await self._backend(agent).close(child.external_id)
+        child = await self.set_status(child, "closed")
+        return ForkResult(conversation=child, text=text, capture=capture)
+
+    async def merge(self, conv: Conversation) -> ForkResult:
+        if conv.parent_id is None:
+            msg = "merge needs a parent conversation"
+            raise ValueError(msg)
+        parent = await self.get_row(conv.parent_id)
+        if parent is None:
+            msg = "parent conversation vanished"
+            raise LookupError(msg)
+        result = await self.fork(
+            conv,
+            self._texts.merge_prompt,
+            title=f"merge: {conv.title or conv.external_id}",
+        )
+        if result.text.strip():
+            await self.inject(parent, result.text, urgency="normal", origin="merge")
+        await self.set_status(conv, "merged")
+        await self.mark_closed(conv)
+        self._bus.publish(
+            "conversation.merged",
+            conversation_id=conv.external_id,
+            parent=parent.external_id,
+            fork=result.conversation.external_id,
+        )
+        return result
+
+    async def _copy_session(
+        self,
+        conv: Conversation,
+        *,
+        window: int | None,
+        strip_tools: bool,
+        agent: str | None = None,
+    ) -> str:
+        if conv.session_id is None:
+            msg = f"conversation {conv.external_id} has no session to copy"
+            raise ValueError(msg)
+        live = self._pool.get(conv.external_id)
+        if live is not None and live.dirty:
+            msg = f"conversation {conv.external_id} has a mirror gap; not forking"
+            raise RuntimeError(msg)
+        source = self._claude_agent(conv.agent_name)
+        target = self._claude_agent(agent) if agent else source
+        forked = await fork_session_via_store(
+            self._store, conv.session_id, directory=str(source.cwd)
+        )
+        source_key = {
+            "project_key": project_key_for_directory(str(source.cwd)),
+            "session_id": forked.session_id,
+        }
+        target_key = {
+            "project_key": project_key_for_directory(str(target.cwd)),
+            "session_id": forked.session_id,
+        }
+        if window is not None or strip_tools or target_key != source_key:
+            entries = await self._store.load(cast("Any", source_key)) or []
+            trimmed = window_entries(cast("Any", entries), window=window)
+            if strip_tools:
+                trimmed = strip_tool_entries(trimmed)
+            await self._store.delete(cast("Any", source_key))
+            await self._store.append(cast("Any", target_key), cast("Any", trimmed))
+        _log.info(
+            "forked session %s -> %s (window=%s, strip_tools=%s)",
+            conv.session_id,
+            forked.session_id,
+            window,
+            strip_tools,
+        )
+        return forked.session_id

src/beaver_gateway/conversations/state.py

@@ -0,0 +1,191 @@
+"""What every layer of the conversations service shares: wiring and lookups."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any, cast
+
+from claude_agent_sdk import project_key_for_directory
+
+from beaver_gateway.conversations.injects import InjectQueue
+from beaver_gateway.conversations.texts import ConversationTexts
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable, Sequence
+
+    from claude_agent_sdk import SessionStore
+
+    from beaver_gateway.agents.claude import ClaudeAgent
+    from beaver_gateway.app import AgentRegistry
+    from beaver_gateway.backends.claude_sdk import ClaudeSdkBackend
+    from beaver_gateway.backends.sessions import SessionPool
+    from beaver_gateway.conversations.distill import Distiller
+    from beaver_gateway.conversations.envelope import Envelope
+    from beaver_gateway.conversations.texts import UserSaid
+    from beaver_gateway.events.bus import EventBus
+    from beaver_gateway.frontends.base import Frontend
+    from beaver_gateway.jobs.scheduler import Scheduler
+    from beaver_gateway.storage.db import Database
+    from beaver_gateway.storage.models import Conversation
+
+__all__ = ["Question", "Runner", "State", "aware", "iso"]
+
+
+@dataclass
+class Runner:
+    lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+    wake: asyncio.Event = field(default_factory=asyncio.Event)
+    task: asyncio.Task[None] | None = None
+    turn_id: str | None = None
+    origin: str | None = None
+    text: str | None = None
+    started_at: datetime | None = None
+    tools: dict[str, dict[str, Any]] = field(default_factory=dict)
+
+    def snapshot(self) -> dict[str, Any] | None:
+        if self.turn_id is None:
+            return None
+        return {
+            "id": self.turn_id,
+            "origin": self.origin,
+            "text": self.text,
+            "started_at": iso(self.started_at),
+            "tools": list(self.tools.values()),
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class Question:
+    conversation_id: str
+    turn_id: str | None
+    questions: list[dict[str, Any]]
+    answer: asyncio.Future[str]
+
+
+class State:
+    _db: Database
+    _agents: AgentRegistry
+    _backends: dict[str, Any]
+    _bus: EventBus
+    _pool: SessionPool
+    _store: SessionStore
+    _texts: ConversationTexts
+    _frontends: list[Frontend]
+    _normal_window: float
+    _idle_days: tuple[int, ...]
+    _idle_interval: float
+    _question_timeout: float
+    _envelope: Envelope | None
+    _distiller: Distiller | None
+    _user_sink: Callable[[UserSaid], Awaitable[None] | None] | None
+    _queue: InjectQueue
+    _runners: dict[int, Runner]
+    _questions: dict[str, Question]
+    _tasks: set[asyncio.Task[None]]
+    _idle_task: asyncio.Task[None] | None
+    scheduler: Scheduler | None
+
+    def __init__(
+        self,
+        *,
+        db: Database,
+        agents: AgentRegistry,
+        backends: dict[str, Any],
+        bus: EventBus,
+        pool: SessionPool,
+        store: SessionStore,
+        texts: ConversationTexts | None = None,
+        frontends: Sequence[Frontend] = (),
+        normal_window: float = 3600.0,
+        idle_days: Sequence[int] = (2,),
+        idle_interval: float = 3600.0,
+        question_timeout: float = 600.0,
+        envelope: Envelope | None = None,
+        distiller: Distiller | None = None,
+        user_sink: Callable[[UserSaid], Awaitable[None] | None] | None = None,
+    ) -> None:
+        self._db = db
+        self._agents = agents
+        self._backends = backends
+        self._bus = bus
+        self._pool = pool
+        self._store = store
+        self._texts = texts or ConversationTexts()
+        self._frontends = [f for f in frontends if f.name]
+        self._normal_window = normal_window
+        self._idle_days = tuple(sorted(idle_days))
+        self._idle_interval = idle_interval
+        self._question_timeout = question_timeout
+        self._envelope = envelope
+        self._distiller = distiller
+        self._user_sink = user_sink
+        self._queue = InjectQueue(db)
+        self._runners = {}
+        self._questions = {}
+        self._tasks = set()
+        self._idle_task = None
+        self.scheduler = None
+        for backend in backends.values():
+            if hasattr(backend, "waker"):
+                backend.waker = self._woken
+
+    async def _woken(self, key: str, note: str) -> None:
+        raise NotImplementedError
+
+    @property
+    def db(self) -> Database:
+        return self._db
+
+    @property
+    def queue(self) -> InjectQueue:
+        return self._queue
+
+    @property
+    def bus(self) -> EventBus:
+        return self._bus
+
+    @property
+    def pool(self) -> SessionPool:
+        return self._pool
+
+    def _backend(self, agent: str) -> ClaudeSdkBackend:
+        backend = self._backends.get(agent)
+        if backend is None or not hasattr(backend, "repair_session"):
+            msg = f"agent {agent!r} has no Claude SDK backend"
+            raise LookupError(msg)
+        return cast("ClaudeSdkBackend", backend)
+
+    def _claude_agent(self, name: str) -> ClaudeAgent:
+        agent = self._agents.get(name)
+        if agent is None or not hasattr(agent, "cwd"):
+            msg = f"unknown Claude agent {name!r}"
+            raise LookupError(msg)
+        return cast("ClaudeAgent", agent)
+
+    def _store_key(self, conv: Conversation) -> dict[str, str]:
+        agent = self._claude_agent(conv.agent_name)
+        return {
+            "project_key": project_key_for_directory(str(agent.cwd)),
+            "session_id": cast("str", conv.session_id),
+        }
+
+    def _runner(self, row_id: int) -> Runner:
+        runner = self._runners.get(row_id)
+        if runner is None:
+            runner = Runner()
+            self._runners[row_id] = runner
+        return runner
+
+    def _track(self, task: asyncio.Task[None]) -> None:
+        self._tasks.add(task)
+        task.add_done_callback(self._tasks.discard)
+
+
+def aware(value: datetime) -> datetime:
+    return value if value.tzinfo is not None else value.replace(tzinfo=UTC)
+
+
+def iso(value: datetime | None) -> str | None:
+    return aware(value).isoformat(timespec="seconds") if value is not None else None

src/beaver_gateway/conversations/texts.py

@@ -0,0 +1,129 @@
+"""Every string the gateway puts in front of a model; English defaults, overridable."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from beaver_gateway.conversations import injects
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+    from datetime import date, datetime
+
+    from beaver_gateway.conversations.distill import DistillContext
+    from beaver_gateway.conversations.kinds import Kind
+    from beaver_gateway.conversations.rotation import HandoutContext
+    from beaver_gateway.storage.models import Conversation
+
+__all__ = [
+    "ConversationTexts",
+    "EnvelopeTexts",
+    "NewDayContext",
+    "SeedContext",
+    "UserSaid",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class SeedContext:
+    kind: Kind
+    seed: str
+    agent: str
+    parent: Conversation | None
+    text: str | None
+    title: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class NewDayContext:
+    """``reason`` is ``night``, ``age`` or ``context``; only ``night`` is a new day."""
+
+    day: date
+    reason: str
+    moved: int
+
+
+@dataclass(frozen=True, slots=True)
+class UserSaid:
+    conversation_id: str
+    kind: str
+    title: str | None
+    text: str
+    at: datetime
+    agent: str = ""
+    """Agent whose turn it is; a setup with several tells them apart by it."""
+
+
+@dataclass(frozen=True, slots=True)
+class EnvelopeTexts:
+    header: str = (
+        "[envelope - background signal, not a message; react only if it bears "
+        "on the question]"
+    )
+    time: str = "time: {stamp} ({zone})"
+    changed: str = "vault, changed {since}: {names}"
+    since: str = "since {time}"
+    since_start: str = "since start"
+    truncated: str = "… (envelope cap)"
+    file_header: str = "--- {path}, added lines only ---"
+    more_lines: str = "+ … {count} more"
+
+
+@dataclass(frozen=True, slots=True)
+class ConversationTexts:
+    merge_prompt: str = (
+        "This branch is closing. Write a merge note for the master: what was "
+        "decided, what was done, what was not and why, open questions. "
+        "Identifiers and links verbatim. Brief, past tense."
+    )
+    inject_header: Callable[[injects.InjectContext], str] = injects.inject_header
+    bundle_header: str = "[injects accumulated since {since}; not the user]"
+    task_prompt: str = "[subagent reported back: {note}]"
+    """Stands in for the user's words in mirrors of a turn a subagent started."""
+    interrupted: str = "interrupted"
+    answered: str = "The user answered: {answer}"
+    unanswered: str = (
+        "The user did not answer within {minutes} min. The question was shown "
+        "to them as text; finish the turn now, the answer comes as the next "
+        "message."
+    )
+    seed: Callable[[SeedContext], Awaitable[str | None] | str | None] | None = None
+    """Body of a seed by mode; ``None`` from it falls back to the defaults below."""
+    seed_head: str = "[seed: {seed}] {kind}{title}, {stamp}."
+    seed_copy: str = "The parent's history is copied ({scope}); continue in it."
+    seed_copy_window: str = "last {window} turns"
+    seed_copy_all: str = "whole history"
+    seed_morning_missing: str = "No handout arrived."
+    handout: Callable[[HandoutContext], Awaitable[str] | str] | str = (
+        "This master is closing ({reason}). Write the handout for {day}: a "
+        "briefing for the morning, not a task list - past tense, no imperatives."
+    )
+    new_day: Callable[[NewDayContext], Awaitable[str] | str] | str = (
+        "The master was replaced ({reason}); the handout for {day} is written."
+    )
+    moved_injects: str = " {moved} queued injects moved over from the old master."
+    distill: Callable[[DistillContext], Awaitable[str] | str] | None = None
+    """The distiller fork's first message; ``None`` uses the two templates below."""
+    distill_prompt: str = (
+        "Deep chat «{chat}» is closed ({reason}), today is {day}. Write the "
+        "digest as a file and the merge as your reply: up to 5 lines, third "
+        "person."
+    )
+    distill_prompt_no_memory: str = (
+        "Deep chat «{chat}» is closed ({reason}), today is {day}. Memory is off "
+        "for it: write no file, only the merge as your reply - up to 5 lines, "
+        "third person."
+    )
+    closed: str = "Deep chat [[{chat}]] closed{digest}.\n{text}"
+    closed_digest: str = ", digest [[{digest}]]"
+    digest_missing: str = "the digest file did not appear"
+    too_long: str = (
+        "`{name}`: {lines} lines against a cap of {max_lines}. The write was "
+        "rejected and the file restored. Shorten and rewrite."
+    )
+    cut_by_restart: str = "turn {turn_id} was cut by a gateway restart"
+    repaired_tools: str = (
+        "; {fixed} open tool calls received tool_result «{interrupted}»"
+    )
+    envelope: EnvelopeTexts = field(default_factory=EnvelopeTexts)

src/beaver_gateway/conversations/tools.py

@@ -0,0 +1,303 @@
+"""In-process MCP server with the gateway's own tools.
+
+One server per live session so every tool knows which conversation is
+calling. Which names a session gets comes from ``ClaudeAgent.gateway_tools``.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import replace
+from typing import TYPE_CHECKING, Any, cast
+
+from claude_agent_sdk import create_sdk_mcp_server, tool
+
+from beaver_gateway.conversations.injects import URGENCY
+from beaver_gateway.conversations.kinds import as_kind
+from beaver_gateway.frontends.files import AUTO, METHODS, SendFileError
+from beaver_gateway.security.redact import redact_data
+
+URGENCY_HELP = (
+    "normal waits for the hourly batch or rides with the next turn, wake "
+    "starts a turn as soon as the target is idle, urgent cuts a running turn"
+)
+TARGET_HELP = (
+    "conversation id, or `master` for the open master, `parent` for the "
+    "parent of this conversation"
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from claude_agent_sdk import McpSdkServerConfig, SdkMcpTool
+
+    from beaver_gateway.conversations.service import Conversations
+
+__all__ = ["SERVER_NAME", "TOOL_NAMES", "build_tool_server"]
+
+_log = logging.getLogger("beaver_gateway.conversations.tools")
+
+SERVER_NAME = "gateway"
+SAY_IN_USER_TURN = (
+    "not delivered: this turn was started by the human's message, so your "
+    "reply text reaches them by itself - put what you wanted to say into the "
+    "reply instead of repeating it here"
+)
+TOOL_NAMES = (
+    "read_conversation",
+    "spawn",
+    "say",
+    "schedule",
+    "inject",
+    "close_chat",
+    "send_file",
+)
+SEND_FILE_HELP = (
+    "Send a file from disk to the human, into this conversation's window (the "
+    "master's if it has none): {note}. `method` is how Telegram renders it; "
+    "`auto` reads the extension - image is a photo, mp3/flac/m4a audio, ogg "
+    "voice, mp4/mov video, anything else a document. Photo and video are "
+    "recompressed, so pass `document` when the bytes must arrive untouched. "
+    "`caption` takes the same markdown as your replies."
+)
+
+
+def build_tool_server(
+    conversations: Conversations, *, conversation_key: str, names: Iterable[str]
+) -> McpSdkServerConfig | None:
+    wanted = set(names)
+    unknown = wanted - set(TOOL_NAMES)
+    if unknown:
+        msg = f"unknown gateway tools: {sorted(unknown)}"
+        raise ValueError(msg)
+    tools = [
+        _redacting(t)
+        for t in _tools(conversations, conversation_key)
+        if t.name in wanted
+    ]
+    if not tools:
+        return None
+    server = create_sdk_mcp_server(SERVER_NAME, tools=tools)
+    return cast("McpSdkServerConfig", {**server, "alwaysLoad": True})
+
+
+def _redacting(spec: SdkMcpTool[Any]) -> SdkMcpTool[Any]:
+    """Put a tool's result through the same mask as every other MCP.
+
+    These tools are mounted in-process, bypassing the ``FastMCP`` middleware
+    in :mod:`beaver_gateway.mcp.redacting`, so the filter is attached here
+    instead. ``read_conversation`` earns it: a replayed transcript can still
+    hold a credential written before redaction existed.
+    """
+    inner = spec.handler
+
+    async def handler(args: Any) -> dict[str, Any]:
+        return cast("dict[str, Any]", redact_data(await inner(args)))
+
+    return replace(spec, handler=handler)
+
+
+def _tools(conversations: Conversations, key: str) -> list[SdkMcpTool[Any]]:
+    async def current() -> Any:
+        conv = await conversations.get(key)
+        if conv is None:
+            msg = f"conversation {key} not found"
+            raise LookupError(msg)
+        return conv
+
+    async def target(raw: Any) -> Any:
+        conv = await conversations.resolve(str(raw), origin=await current())
+        if conv is None:
+            _log.warning("gateway tool in %s: conversation %r not found", key, raw)
+        return conv
+
+    @tool(
+        "read_conversation",
+        "Read another conversation (a branch, the master, a deep chat) as plain "
+        "text. `window` limits it to the last N user turns.",
+        {
+            "type": "object",
+            "properties": {
+                "id": {"type": "string", "description": TARGET_HELP},
+                "window": {"type": "integer", "minimum": 1},
+            },
+            "required": ["id"],
+        },
+    )
+    async def read_conversation(args: dict[str, Any]) -> dict[str, Any]:
+        conv = await target(args["id"])
+        if conv is None:
+            return _error(f"conversation {args['id']} not found ({TARGET_HELP})")
+        text = await conversations.read(conv, window=args.get("window"))
+        return _text(text or "(empty)")
+
+    @tool(
+        "spawn",
+        "Open a new conversation of the given kind (branch = your own thread, "
+        "deep = a long research chat, job = a headless task). `seed` is how it "
+        "starts: clean (nothing), morning (handout), copy (copy of this "
+        "conversation, last `window` turns), brief (your `text`). A branch "
+        "keeps your agent, other kinds get their frontend's default unless "
+        "`agent` says otherwise. Returns the id.",
+        {
+            "type": "object",
+            "properties": {
+                "kind": {"type": "string", "enum": ["branch", "deep", "job"]},
+                "agent": {"type": "string", "description": "agent name"},
+                "seed": {
+                    "type": "string",
+                    "enum": ["clean", "morning", "copy", "brief"],
+                    "default": "clean",
+                },
+                "text": {"type": "string", "description": "brief for seed=brief"},
+                "title": {"type": "string"},
+                "window": {"type": "integer", "minimum": 1},
+            },
+            "required": ["kind"],
+        },
+    )
+    async def spawn(args: dict[str, Any]) -> dict[str, Any]:
+        parent = await current()
+        try:
+            child = await conversations.spawn(
+                kind=as_kind(str(args["kind"])),
+                agent=args.get("agent"),
+                seed=str(args.get("seed") or "clean"),
+                parent=parent,
+                text=args.get("text"),
+                title=args.get("title"),
+                window=args.get("window"),
+                origin="mcp",
+            )
+        except (ValueError, LookupError) as exc:
+            return _error(str(exc))
+        return _text(f"spawned {child.kind} {child.external_id}")
+
+    @tool(
+        "say",
+        "Say something to the human in the frontend this conversation is bound "
+        "to. The only way an inject-started turn can speak; silence is simply "
+        "not calling it. Refused in a turn started by the human's own message: "
+        "there your reply text reaches them by itself, so just write the reply.",
+        {"text": str},
+    )
+    async def say(args: dict[str, Any]) -> dict[str, Any]:
+        conv = await current()
+        if conversations.turn_origin(conv) == "user":
+            return _error(SAY_IN_USER_TURN)
+        await conversations.say(conv, str(args["text"]))
+        return _text("ok")
+
+    @tool(
+        "schedule",
+        "Promise yourself an inject later: `at` is `+15m`, `+2h`, `+1d` or an "
+        "ISO datetime; `text` arrives in this conversation at that time and "
+        "starts a turn (urgency wake). " + URGENCY_HELP + ".",
+        {
+            "type": "object",
+            "properties": {
+                "at": {"type": "string"},
+                "text": {"type": "string"},
+                "urgency": {"type": "string", "enum": list(URGENCY), "default": "wake"},
+            },
+            "required": ["at", "text"],
+        },
+    )
+    async def schedule(args: dict[str, Any]) -> dict[str, Any]:
+        conv = await current()
+        try:
+            job_id, when = await conversations.schedule(
+                conv,
+                str(args["at"]),
+                str(args["text"]),
+                urgency=cast("Any", args.get("urgency") or "wake"),
+            )
+        except (RuntimeError, ValueError) as exc:
+            return _error(str(exc))
+        return _text(f"scheduled #{job_id} at {when.isoformat(timespec='minutes')}")
+
+    @tool(
+        "inject",
+        "Put a system-origin message into another conversation's queue. "
+        + URGENCY_HELP
+        + ". An error here means nothing was delivered.",
+        {
+            "type": "object",
+            "properties": {
+                "conversation": {"type": "string", "description": TARGET_HELP},
+                "text": {"type": "string"},
+                "urgency": {
+                    "type": "string",
+                    "enum": list(URGENCY),
+                    "default": "normal",
+                },
+            },
+            "required": ["conversation", "text"],
+        },
+    )
+    async def inject(args: dict[str, Any]) -> dict[str, Any]:
+        conv = await target(args["conversation"])
+        if conv is None:
+            return _error(
+                f"conversation {args['conversation']} not found ({TARGET_HELP})"
+            )
+        item = await conversations.inject(
+            conv,
+            str(args["text"]),
+            urgency=cast("Any", args.get("urgency") or "normal"),
+            origin="agent",
+        )
+        return _text(f"queued #{item.id}")
+
+    @tool(
+        "send_file",
+        SEND_FILE_HELP.format(note=conversations.file_note()),
+        {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "absolute path on disk"},
+                "caption": {"type": "string"},
+                "method": {"type": "string", "enum": [AUTO, *METHODS], "default": AUTO},
+            },
+            "required": ["path"],
+        },
+    )
+    async def send_file(args: dict[str, Any]) -> dict[str, Any]:
+        conv = await current()
+        try:
+            return _text(
+                await conversations.send_file(
+                    conv,
+                    str(args["path"]),
+                    caption=str(args.get("caption") or ""),
+                    method=str(args.get("method") or AUTO),
+                )
+            )
+        except SendFileError as exc:
+            return _error(str(exc))
+
+    @tool(
+        "close_chat",
+        "Close this deep chat once the current reply is finished: the "
+        "distiller forks it, writes the digest and hands a short merge to the "
+        "master. Call it when the human says the discussion is over; the chat "
+        "file stays as it is.",
+        {"type": "object", "properties": {}},
+    )
+    async def close_chat(_args: dict[str, Any]) -> dict[str, Any]:
+        conv = await current()
+        try:
+            await conversations.request_close(conv)
+        except ValueError as exc:
+            return _error(str(exc))
+        return _text("ok: the chat closes after this reply")
+
+    return [read_conversation, spawn, say, schedule, inject, send_file, close_chat]
+
+
+def _text(text: str) -> dict[str, Any]:
+    return {"content": [{"type": "text", "text": text}]}
+
+
+def _error(text: str) -> dict[str, Any]:
+    return {"content": [{"type": "text", "text": text}], "is_error": True}

src/beaver_gateway/conversations/turns.py

@@ -0,0 +1,555 @@
+"""Running turns: one worker per conversation over its queue, the backend call."""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import contextlib
+import inspect
+import logging
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, cast
+from uuid import uuid4
+
+from claude_agent_sdk import (
+    AssistantMessage,
+    RateLimitEvent,
+    ResultMessage,
+    StreamEvent,
+    ToolResultBlock,
+    ToolUseBlock,
+    UserMessage,
+)
+
+from beaver_gateway.backends.capture import TurnCapture
+from beaver_gateway.backends.transcript import text_of
+from beaver_gateway.conversations import injects
+from beaver_gateway.conversations.seeds import Seeds
+from beaver_gateway.conversations.state import Runner, aware, iso
+from beaver_gateway.conversations.texts import UserSaid
+from beaver_gateway.frontends.accumulate import StreamAccumulator
+from beaver_gateway.storage.models import Conversation, InjectQueueItem, RateLimit
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Callable, Sequence
+
+    from beaver_gateway.events.stream import MessageStreamEvent
+
+__all__ = ["Turns", "content_of", "image_block"]
+
+_log = logging.getLogger(__name__)
+
+
+class Turns(Seeds):
+    async def turn(
+        self,
+        conv: Conversation,
+        *,
+        messages: Sequence[Any],
+        origin: str,
+        capture: TurnCapture | None = None,
+        session_id: str | None = None,
+        use_session: bool = True,
+        tools: bool = True,
+        turn_id: str | None = None,
+        item_origin: str | None = None,
+        shown: str | None = None,
+        attach: bool = False,
+    ) -> AsyncIterator[MessageStreamEvent]:
+        """Run one turn under the conversation's lock; the only path to the backend.
+
+        ``shown`` is what frontends display as the turn's prompt (the user's
+        words, not the envelope). ``attach`` sends nothing: the turn is one
+        the live session started by itself, a subagent reporting back.
+        """
+        row_id = cast("int", conv.id)
+        runner = self._runner(row_id)
+        backend = self._backend(conv.agent_name)
+        turn_id = turn_id or f"turn_{uuid4().hex[:12]}"
+        capture = capture or TurnCapture()
+        resume = session_id if session_id is not None else conv.session_id
+        async with runner.lock:
+            runner.turn_id = turn_id
+            runner.origin = origin
+            runner.text = shown if shown is not None else _prompt_preview(messages)
+            runner.started_at = datetime.now(UTC)
+            runner.tools = {}
+            await self._mark_running(conv, turn_id)
+            before = await self.before_turn(conv)
+            self._bus.publish(
+                "turn.start",
+                conversation_id=conv.external_id,
+                turn_id=turn_id,
+                origin=origin,
+                item_origin=item_origin,
+                text=runner.text,
+            )
+            stop = "error"
+            cut = False
+            try:
+                observer = self._observer(conv, runner, turn_id, origin)
+                events = (
+                    backend.attach(
+                        key=conv.external_id,
+                        capture=capture,
+                        observer=observer,
+                        turn_id=turn_id,
+                    )
+                    if attach
+                    else backend.complete(
+                        agent=self._claude_agent(conv.agent_name),
+                        messages=messages,
+                        conversation_id=conv.external_id,
+                        session_id=resume if use_session else None,
+                        reseed=not use_session,
+                        capture=capture,
+                        kind=conv.kind,
+                        pinned=conv.kind == "master",
+                        tools=tools,
+                        observer=observer,
+                        turn_id=turn_id,
+                    )
+                )
+                async for event in events:
+                    yield event
+                stop = "interrupted" if capture.interrupted else "end_turn"
+            except asyncio.CancelledError:
+                cut = True
+                raise
+            finally:
+                runner.turn_id = None
+                await self._mark_done(conv, capture, cut=cut)
+                if stop != "error":
+                    try:
+                        await self.after_turn(conv, before)
+                    except Exception:  # noqa: BLE001
+                        _log.exception("after-turn hook on %s failed", conv.external_id)
+                self._bus.publish(
+                    "turn.end",
+                    conversation_id=conv.external_id,
+                    turn_id=turn_id,
+                    origin=origin,
+                    item_origin=item_origin,
+                    stop=stop,
+                    usage=_usage_dict(capture),
+                )
+
+    async def run_text_turn(
+        self,
+        conv: Conversation,
+        text: str,
+        *,
+        origin: str,
+        tools: bool = True,
+        turn_id: str | None = None,
+        item_origin: str | None = None,
+        attachments: Sequence[dict[str, Any]] | None = None,
+        shown: str | None = None,
+        attach: bool = False,
+    ) -> tuple[str, TurnCapture]:
+        capture = TurnCapture()
+        acc = StreamAccumulator()
+        agent = self._claude_agent(conv.agent_name)
+        async for event in self.turn(
+            conv,
+            messages=[{"role": "user", "content": content_of(text, attachments)}],
+            origin=origin,
+            capture=capture,
+            tools=tools,
+            turn_id=turn_id,
+            item_origin=item_origin,
+            shown=shown,
+            attach=attach,
+        ):
+            acc.feed(event)
+        message = acc.finalize(model=agent.model)
+        reply = "\n\n".join(
+            getattr(b, "text", "")
+            for b in message.content
+            if getattr(b, "type", "") == "text"
+        ).strip()
+        return reply, capture
+
+    async def before_turn(self, conv: Conversation) -> str | None:  # noqa: ARG002
+        return None
+
+    async def after_turn(self, conv: Conversation, before: str | None) -> None:  # noqa: ARG002
+        return
+
+    def turn_origin(self, conv: Conversation) -> str | None:
+        runner = self._runners.get(cast("int", conv.id))
+        return runner.origin if runner is not None and runner.turn_id else None
+
+    async def _woken(self, key: str, note: str) -> None:
+        """The live session of ``key`` started a turn by itself; run it next."""
+        conv = await self.get(key)
+        if conv is None:
+            _log.warning("self-started turn on unknown conversation %s: %s", key, note)
+            return
+        _log.info("conversation %s woke by itself: %s", key, note)
+        self._ensure_worker(cast("int", conv.id))
+
+    async def _run_pending(self, conv: Conversation) -> None:
+        turn_id = f"turn_{uuid4().hex[:12]}"
+        note = self._backend(conv.agent_name).pending_note(conv.external_id) or ""
+        try:
+            text, _ = await self.run_text_turn(
+                conv,
+                note,
+                origin="task",
+                turn_id=turn_id,
+                item_origin="task",
+                shown=note,
+                attach=True,
+            )
+        except Exception:  # noqa: BLE001
+            _log.exception(
+                "self-started turn %s on %s failed", turn_id, conv.external_id
+            )
+            return
+        if not text.strip():
+            return
+        self._bus.publish(
+            "reply",
+            conversation_id=conv.external_id,
+            turn_id=turn_id,
+            item=None,
+            item_origin="task",
+            source="task",
+            prompt=self._texts.task_prompt.format(note=note),
+            user_text=None,
+            text=text,
+        )
+
+    def _ensure_worker(self, row_id: int) -> None:
+        runner = self._runner(row_id)
+        runner.wake.set()
+        if runner.task is None or runner.task.done():
+            runner.task = asyncio.create_task(self._worker(row_id))
+            self._track(runner.task)
+
+    async def _worker(self, row_id: int) -> None:
+        runner = self._runner(row_id)
+        while True:
+            conv = await self.get_row(row_id)
+            if conv is not None and self._has_pending(conv):
+                await self._run_pending(conv)
+                continue
+            items = await self._queue.pending(row_id)
+            batch, wait = self._pick(items)
+            if batch is None:
+                runner.wake.clear()
+                if wait is None:
+                    return
+                with contextlib.suppress(TimeoutError):
+                    await asyncio.wait_for(runner.wake.wait(), timeout=wait)
+                continue
+            conv = await self.get_row(row_id)
+            if conv is None:
+                await self._queue.finish(batch, status="failed")
+                return
+            await self._run_batch(conv, batch)
+
+    def _pick(
+        self, items: list[InjectQueueItem]
+    ) -> tuple[list[InjectQueueItem] | None, float | None]:
+        if not items:
+            return None, None
+        head = items[0]
+        if head.priority == "urgent":
+            return [head], None
+        tail = [i for i in items if i is not head and i.priority in ("wake", "normal")]
+        if head.priority in ("user", "wake"):
+            return [head, *tail], None
+        age = (datetime.now(UTC) - aware(head.created_at)).total_seconds()
+        if age >= self._normal_window:
+            return [head, *tail], None
+        return None, max(self._normal_window - age, 1.0)
+
+    async def _run_batch(
+        self, conv: Conversation, batch: list[InjectQueueItem]
+    ) -> None:
+        head = batch[0]
+        turn_id = f"turn_{uuid4().hex[:12]}"
+        await self._queue.start(batch, turn_id)
+        if head.priority == "user":
+            origin = "user"
+            prompt = head.text
+            await self._note_user(conv, head.text)
+            envelope = self._envelope_for(conv, head.text)
+            if envelope:
+                prompt += "\n\n" + envelope
+            if len(batch) > 1:
+                prompt += "\n\n" + self._bundle(batch[1:])
+        else:
+            origin = "inject"
+            prompt = "\n\n".join(
+                f"{self._texts.inject_header(injects.context_of(i))}\n{i.text}"
+                for i in batch
+            )
+        seed = await self.pending_seed(conv)
+        if seed:
+            prompt = f"{seed}\n\n{prompt}"
+        try:
+            text, capture = await self.run_text_turn(
+                conv,
+                prompt,
+                origin=origin,
+                turn_id=turn_id,
+                item_origin=head.origin,
+                attachments=head.attachments if origin == "user" else None,
+                shown=head.text if origin == "user" else None,
+            )
+        except Exception:  # noqa: BLE001
+            _log.exception("turn %s on %s failed", turn_id, conv.external_id)
+            await self._queue.finish(batch, status="failed")
+            return
+        await self._queue.finish(
+            batch, status="interrupted" if capture.interrupted else "done"
+        )
+        if origin == "user":
+            self._bus.publish(
+                "reply",
+                conversation_id=conv.external_id,
+                turn_id=turn_id,
+                item=head.id,
+                item_origin=head.origin,
+                source="queue",
+                prompt=prompt,
+                user_text=head.text,
+                text=text,
+            )
+
+    def _has_pending(self, conv: Conversation) -> bool:
+        try:
+            return self._backend(conv.agent_name).has_pending(conv.external_id)
+        except LookupError:
+            return False
+
+    def _bundle(self, items: Sequence[InjectQueueItem]) -> str:
+        lines = [self._texts.bundle_header.format(since=iso(items[0].created_at))]
+        lines.extend(f"- [{i.origin}] {i.text}" for i in items)
+        return "\n".join(lines)
+
+    def _envelope_for(self, conv: Conversation, text: str = "") -> str | None:
+        if self._envelope is None:
+            return None
+        if conv.kind == "master":
+            return self._envelope.build(text=text, kind="master", agent=conv.agent_name)
+        if conv.kind == "branch":
+            return self._envelope.recall_only(
+                text=text, kind="branch", agent=conv.agent_name
+            )
+        return None
+
+    async def _note_user(self, conv: Conversation, text: str) -> None:
+        if self._user_sink is None:
+            return
+        message = UserSaid(
+            conversation_id=conv.external_id,
+            kind=conv.kind,
+            title=conv.title,
+            text=text,
+            at=datetime.now(UTC),
+            agent=conv.agent_name,
+        )
+        try:
+            result = self._user_sink(message)
+            if inspect.isawaitable(result):
+                await result
+        except Exception:  # noqa: BLE001
+            _log.exception("user sink failed for %s", conv.external_id)
+
+    def _observer(
+        self, conv: Conversation, runner: Runner, turn_id: str, origin: str
+    ) -> Callable[[Any], None]:
+        conversation_id = conv.external_id
+
+        def observe(message: Any) -> None:
+            parent = getattr(message, "parent_tool_use_id", None)
+            if isinstance(message, RateLimitEvent):
+                self._observe_rate_limit(conv, message)
+            elif isinstance(message, StreamEvent):
+                self._bus.publish(
+                    "stream",
+                    conversation_id=conversation_id,
+                    turn_id=turn_id,
+                    origin=origin,
+                    parent_tool_use_id=parent,
+                    event=message.event,
+                )
+            elif isinstance(message, AssistantMessage):
+                for block in message.content:
+                    if isinstance(block, ToolUseBlock):
+                        event = self._bus.publish(
+                            "tool",
+                            conversation_id=conversation_id,
+                            turn_id=turn_id,
+                            origin=origin,
+                            parent_tool_use_id=parent,
+                            tool_use_id=block.id,
+                            name=block.name,
+                            input=block.input,
+                        )
+                        runner.tools[block.id] = {
+                            "tool_use_id": block.id,
+                            "name": block.name,
+                            "input": block.input,
+                            "parent_tool_use_id": parent,
+                            "started_at": event["ts"],
+                            "ended_at": None,
+                            "is_error": None,
+                            "content": None,
+                        }
+            elif isinstance(message, UserMessage):
+                blocks = message.content if isinstance(message.content, list) else ()
+                for block in blocks:
+                    if isinstance(block, ToolResultBlock):
+                        event = self._bus.publish(
+                            "tool.result",
+                            conversation_id=conversation_id,
+                            turn_id=turn_id,
+                            origin=origin,
+                            parent_tool_use_id=parent,
+                            tool_use_id=block.tool_use_id,
+                            is_error=bool(block.is_error),
+                            content=_result_preview(block.content),
+                        )
+                        node = runner.tools.get(block.tool_use_id)
+                        if node is not None:
+                            node["ended_at"] = event["ts"]
+                            node["is_error"] = event["is_error"]
+                            node["content"] = event["content"]
+            elif isinstance(message, ResultMessage) and parent is None:
+                self._bus.publish(
+                    "result",
+                    conversation_id=conversation_id,
+                    turn_id=turn_id,
+                    origin=origin,
+                    subtype=message.subtype,
+                    is_error=message.is_error,
+                    num_turns=message.num_turns,
+                )
+
+        return observe
+
+    def _observe_rate_limit(self, conv: Conversation, message: RateLimitEvent) -> None:
+        info = message.rate_limit_info
+        row = RateLimit(
+            window=info.rate_limit_type or "unknown",
+            status=info.status,
+            utilization=info.utilization,
+            resets_at=_from_unix(info.resets_at),
+            overage_status=info.overage_status,
+            overage_resets_at=_from_unix(info.overage_resets_at),
+            agent_name=conv.agent_name,
+            session_id=message.session_id,
+            raw=dict(info.raw),
+        )
+        self._bus.publish(
+            "rate_limit",
+            conversation_id=conv.external_id,
+            window=row.window,
+            status=row.status,
+            utilization=row.utilization,
+            resets_at=iso(row.resets_at),
+            overage_status=row.overage_status,
+        )
+        self._track(asyncio.create_task(self._record_rate_limit(row)))
+
+    async def _record_rate_limit(self, row: RateLimit) -> None:
+        try:
+            async with self._db.session() as session:
+                session.add(row)
+                await session.commit()
+        except Exception:  # noqa: BLE001
+            _log.exception("rate limit write failed")
+
+    async def _mark_running(self, conv: Conversation, turn_id: str) -> None:
+        async def apply(row: Conversation) -> None:
+            row.running_turn = turn_id
+            row.last_activity_at = datetime.now(UTC)
+
+        await self._update(conv, apply)
+
+    async def _mark_done(
+        self, conv: Conversation, capture: TurnCapture, *, cut: bool = False
+    ) -> None:
+        async def apply(row: Conversation) -> None:
+            if not cut:
+                row.running_turn = None
+            row.last_activity_at = datetime.now(UTC)
+            if capture.session_id is not None:
+                row.session_id = capture.session_id
+
+        await self._update(conv, apply)
+
+
+IMAGE_MAX_BYTES = 5 * 1024 * 1024
+
+
+def content_of(
+    text: str, attachments: Sequence[dict[str, Any]] | None
+) -> str | list[dict[str, Any]]:
+    """Plain text, or text plus the images that ride with it."""
+    blocks = [b for a in attachments or () if (b := image_block(a)) is not None]
+    if not blocks:
+        return text
+    return [{"type": "text", "text": text}, *blocks]
+
+
+def image_block(attachment: dict[str, Any]) -> dict[str, Any] | None:
+    media_type = str(attachment.get("media_type") or "")
+    path = Path(str(attachment.get("path") or ""))
+    if not media_type.startswith("image/") or not path.is_file():
+        return None
+    if path.stat().st_size > IMAGE_MAX_BYTES:
+        return None
+    data = base64.b64encode(path.read_bytes()).decode("ascii")
+    return {
+        "type": "image",
+        "source": {"type": "base64", "media_type": media_type, "data": data},
+    }
+
+
+def _prompt_preview(messages: Sequence[Any], limit: int = 400) -> str | None:
+    if not messages:
+        return None
+    text = text_of(messages[-1].get("content"))
+    return text[:limit] if text else None
+
+
+def _from_unix(value: int | None) -> datetime | None:
+    return datetime.fromtimestamp(value, tz=UTC) if value is not None else None
+
+
+def _result_preview(
+    content: str | list[dict[str, Any]] | None, limit: int = 400
+) -> str:
+    if content is None:
+        return ""
+    text = (
+        content
+        if isinstance(content, str)
+        else "\n".join(
+            str(part.get("text", ""))
+            for part in content
+            if isinstance(part, dict) and part.get("type") == "text"
+        )
+    )
+    return text if len(text) <= limit else text[:limit] + "…"
+
+
+def _usage_dict(capture: TurnCapture) -> dict[str, Any] | None:
+    usage = capture.usage
+    if usage is None:
+        return None
+    return {
+        "input": usage.input_tokens,
+        "output": usage.output_tokens,
+        "cache_read": usage.cache_read_tokens,
+        "cache_creation": usage.cache_creation_tokens,
+        "cost_usd": usage.cost_usd,
+        "duration_ms": usage.duration_ms,
+    }

src/beaver_gateway/core/__init__.py

@@ -1,7 +0,0 @@
-"""Cross-cutting machinery: registries, event protocol, auth, sessions."""
-
-from __future__ import annotations
-
-from beaver_gateway.core.registry import AgentRegistry, Gateway, McpRegistry
-
-__all__ = ["AgentRegistry", "Gateway", "McpRegistry"]

src/beaver_gateway/core/audit.py

@@ -1,93 +0,0 @@
-"""Single entry point for writing :class:`AuditLog` rows.
-
-Every frontend ends up needing the same three-line pattern — open a DB
-session, append a row, swallow failures so the user-visible request
-still succeeds. Phase 4.3 inlined that pattern in the admin frontend
-under a private ``_audit()`` helper; Phase 4.4 lifts it here so the
-Messages and MCP frontends can call the same function and so the
-swallow-and-log policy lives in one place.
-
-The contract:
-
-* ``log(runtime, actor=..., kind=...)`` is fire-and-forget. It awaits
-  the DB write (so callers can ``await`` it before responding and get
-  ordering), but never raises — if the audit insert fails, the function
-  emits an ``exception`` log line and returns.
-* ``actor`` is a free-form string. By convention: ``"token:<name>"``
-  for bearer-authenticated traffic, ``"admin:<user>"`` for admin-UI
-  actions, ``"anon"`` for failed-auth paths we still want to record.
-* ``kind`` is a short tag — see :data:`KNOWN_KINDS` for the set the
-  current frontends emit; new tags don't need a code change here, the
-  column is free-form.
-* ``**detail`` is JSON-serialised by :func:`append_audit`. Keep it
-  small: paths, methods, status codes — not request bodies. Anything
-  passed here lands in ``AuditLog.detail_json`` verbatim.
-
-Why a thin wrapper rather than ``append_audit`` directly: callers want
-"write if you can, otherwise carry on", and pulling the try/except into
-every frontend was already starting to drift (admin had it, bearer
-frontends would have copy-pasted). One module, one policy.
-"""
-
-from __future__ import annotations
-
-import logging
-from typing import TYPE_CHECKING, Any
-
-from beaver_gateway.storage import append_audit
-
-if TYPE_CHECKING:
-    from beaver_gateway.frontends.base import GatewayRuntime
-
-
-_log = logging.getLogger("beaver_gateway.audit")
-
-
-# Tags currently emitted by the gateway. The set is informational —
-# ``AuditLog.kind`` is free-form so new code can introduce new tags
-# without touching this list — but listing them here gives the admin UI
-# and any downstream log consumers one canonical reference.
-KNOWN_KINDS: frozenset[str] = frozenset(
-    {
-        "messages",  # POST /v1/messages accepted
-        "mcp_call",  # /mcp/<ns>/... proxied
-        "login_ok",
-        "login_failed",
-        "logout",
-        "token_create",
-        "token_revoke",
-    }
-)
-
-
-async def log(
-    runtime: GatewayRuntime,
-    *,
-    actor: str,
-    kind: str,
-    agent_name: str | None = None,
-    **detail: Any,
-) -> None:
-    """Best-effort audit insert. Never raises.
-
-    Opens its own short-lived :class:`AsyncSession` so callers don't
-    have to thread one through. If the DB hiccups (table missing,
-    disk full, connection drop), we log and move on — the audit trail
-    is observability, not a hard precondition for serving the request.
-    """
-    try:
-        async with runtime.db.session() as session:
-            await append_audit(
-                session,
-                actor=actor,
-                kind=kind,
-                agent_name=agent_name,
-                detail=detail or None,
-            )
-    except Exception:  # noqa: BLE001
-        _log.exception(
-            "audit write failed: actor=%s kind=%s agent=%s", actor, kind, agent_name
-        )
-
-
-__all__ = ["KNOWN_KINDS", "log"]

src/beaver_gateway/core/gateway_tools.py

@@ -1,177 +0,0 @@
-"""In-process MCP server with the gateway's own tools (§3.1, §3.2).
-
-One server per live session so every tool knows which conversation is
-calling; ``alwaysLoad`` keeps the tools out of tool search. Which names a
-session gets comes from ``ClaudeAgent.gateway_tools``.
-"""
-
-from __future__ import annotations
-
-import logging
-from typing import TYPE_CHECKING, Any, cast
-
-from claude_agent_sdk import create_sdk_mcp_server, tool
-
-from beaver_gateway.core.kinds import as_kind
-
-if TYPE_CHECKING:
-    from collections.abc import Iterable
-
-    from claude_agent_sdk import McpSdkServerConfig, SdkMcpTool
-
-    from beaver_gateway.core.conversations import Conversations
-
-__all__ = ["SERVER_NAME", "TOOL_NAMES", "build_tool_server"]
-
-_log = logging.getLogger("beaver_gateway.core.gateway_tools")
-
-SERVER_NAME = "gateway"
-TOOL_NAMES = ("read_conversation", "spawn", "say", "schedule", "inject")
-
-
-def build_tool_server(
-    conversations: Conversations, *, conversation_key: str, names: Iterable[str]
-) -> McpSdkServerConfig | None:
-    wanted = set(names)
-    unknown = wanted - set(TOOL_NAMES)
-    if unknown:
-        msg = f"unknown gateway tools: {sorted(unknown)}"
-        raise ValueError(msg)
-    tools = [t for t in _tools(conversations, conversation_key) if t.name in wanted]
-    if not tools:
-        return None
-    server = create_sdk_mcp_server(SERVER_NAME, tools=tools)
-    return cast("McpSdkServerConfig", {**server, "alwaysLoad": True})
-
-
-def _tools(conversations: Conversations, key: str) -> list[SdkMcpTool[Any]]:
-    async def current() -> Any:
-        conv = await conversations.get(key)
-        if conv is None:
-            msg = f"conversation {key} not found"
-            raise LookupError(msg)
-        return conv
-
-    @tool(
-        "read_conversation",
-        "Read another conversation (a branch, the master, a deep chat) as plain "
-        "text. `window` limits it to the last N user turns.",
-        {
-            "type": "object",
-            "properties": {
-                "id": {"type": "string", "description": "conversation id"},
-                "window": {"type": "integer", "minimum": 1},
-            },
-            "required": ["id"],
-        },
-    )
-    async def read_conversation(args: dict[str, Any]) -> dict[str, Any]:
-        conv = await conversations.get(str(args["id"]))
-        if conv is None:
-            return _error(f"conversation {args['id']} not found")
-        text = await conversations.read(conv, window=args.get("window"))
-        return _text(text or "(empty)")
-
-    @tool(
-        "spawn",
-        "Open a new conversation of the given kind (branch = your own thread, "
-        "deep = a long research chat, job = a headless task). `seed` is how it "
-        "starts: clean (nothing), morning (handout), copy (copy of this "
-        "conversation, last `window` turns), brief (your `text`). A branch "
-        "keeps your agent, other kinds get their frontend's default unless "
-        "`agent` says otherwise. Returns the id.",
-        {
-            "type": "object",
-            "properties": {
-                "kind": {"type": "string", "enum": ["branch", "deep", "job"]},
-                "agent": {"type": "string", "description": "agent name"},
-                "seed": {
-                    "type": "string",
-                    "enum": ["clean", "morning", "copy", "brief"],
-                    "default": "clean",
-                },
-                "text": {"type": "string", "description": "brief for seed=brief"},
-                "title": {"type": "string"},
-                "window": {"type": "integer", "minimum": 1},
-            },
-            "required": ["kind"],
-        },
-    )
-    async def spawn(args: dict[str, Any]) -> dict[str, Any]:
-        parent = await current()
-        try:
-            child = await conversations.spawn(
-                kind=as_kind(str(args["kind"])),
-                agent=args.get("agent"),
-                seed=str(args.get("seed") or "clean"),
-                parent=parent,
-                text=args.get("text"),
-                title=args.get("title"),
-                window=args.get("window"),
-                origin="mcp",
-            )
-        except (ValueError, LookupError) as exc:
-            return _error(str(exc))
-        return _text(f"spawned {child.kind} {child.external_id}")
-
-    @tool(
-        "say",
-        "Say something to the human in the frontend this conversation is bound "
-        "to. The only way an inject-started turn can speak; silence is simply "
-        "not calling it.",
-        {"text": str},
-    )
-    async def say(args: dict[str, Any]) -> dict[str, Any]:
-        conv = await current()
-        await conversations.say(conv, str(args["text"]))
-        return _text("ok")
-
-    @tool(
-        "schedule",
-        "Promise yourself an inject later: `at` is `+15m`, `+2h`, `+1d` or an "
-        "ISO datetime; `text` arrives in this conversation at that time.",
-        {"at": str, "text": str},
-    )
-    async def schedule(args: dict[str, Any]) -> dict[str, Any]:
-        conv = await current()
-        row = await conversations.schedule(conv, str(args["at"]), str(args["text"]))
-        return _text(f"scheduled #{row.id} at {row.execute_at.isoformat()}")
-
-    @tool(
-        "inject",
-        "Put a system-origin message into another conversation's queue.",
-        {
-            "type": "object",
-            "properties": {
-                "conversation": {"type": "string"},
-                "text": {"type": "string"},
-                "urgency": {
-                    "type": "string",
-                    "enum": ["normal", "urgent"],
-                    "default": "normal",
-                },
-            },
-            "required": ["conversation", "text"],
-        },
-    )
-    async def inject(args: dict[str, Any]) -> dict[str, Any]:
-        target = await conversations.get(str(args["conversation"]))
-        if target is None:
-            return _error(f"conversation {args['conversation']} not found")
-        item = await conversations.inject(
-            target,
-            str(args["text"]),
-            urgency=cast("Any", args.get("urgency") or "normal"),
-            origin="агент",
-        )
-        return _text(f"queued #{item.id}")
-
-    return [read_conversation, spawn, say, schedule, inject]
-
-
-def _text(text: str) -> dict[str, Any]:
-    return {"content": [{"type": "text", "text": text}]}
-
-
-def _error(text: str) -> dict[str, Any]:
-    return {"content": [{"type": "text", "text": text}], "is_error": True}

src/beaver_gateway/core/injects.py

@@ -1,130 +0,0 @@
-"""Persisted per-conversation queue with priorities ``urgent > user > normal`` (§3.4).
-
-One ``ClaudeSDKClient`` runs one turn at a time, so ordering has to happen
-before the client: the rows here are the queue, ``core/conversations``
-runs one worker per conversation over them. A row that is still
-``running`` when the gateway starts was cut by a restart; it is flagged
-``interrupted`` and never re-run.
-"""
-
-from __future__ import annotations
-
-from datetime import UTC, datetime
-from typing import TYPE_CHECKING, Literal
-
-from sqlmodel import col, select
-
-from beaver_gateway.storage.models import InjectQueueItem
-
-if TYPE_CHECKING:
-    from collections.abc import Iterable, Sequence
-
-    from beaver_gateway.storage.db import Database
-
-__all__ = ["PRIORITY_RANK", "InjectQueue", "Priority", "inject_header"]
-
-Priority = Literal["urgent", "user", "normal"]
-PRIORITY_RANK: dict[str, int] = {"urgent": 0, "user": 1, "normal": 2}
-
-
-def inject_header(origin: str) -> str:
-    return f"[инжект: {origin} - это не Бобёр, отвечать не нужно, голос не обязателен]"
-
-
-class InjectQueue:
-    def __init__(self, db: Database) -> None:
-        self._db = db
-
-    async def push(
-        self, *, conversation_id: int, priority: Priority, origin: str, text: str
-    ) -> InjectQueueItem:
-        if priority not in PRIORITY_RANK:
-            msg = f"unknown priority {priority!r}"
-            raise ValueError(msg)
-        row = InjectQueueItem(
-            conversation_id=conversation_id, priority=priority, origin=origin, text=text
-        )
-        async with self._db.session() as session:
-            session.add(row)
-            await session.commit()
-            await session.refresh(row)
-        return row
-
-    async def pending(self, conversation_id: int) -> list[InjectQueueItem]:
-        async with self._db.session() as session:
-            result = await session.exec(
-                select(InjectQueueItem)
-                .where(
-                    InjectQueueItem.conversation_id == conversation_id,
-                    InjectQueueItem.status == "queued",
-                )
-                .order_by(col(InjectQueueItem.created_at), col(InjectQueueItem.id))
-            )
-            rows = list(result.all())
-        rows.sort(key=lambda r: (PRIORITY_RANK.get(r.priority, 9), r.created_at))
-        return rows
-
-    async def conversations_with_pending(self) -> list[int]:
-        async with self._db.session() as session:
-            result = await session.exec(
-                select(InjectQueueItem.conversation_id)
-                .where(InjectQueueItem.status == "queued")
-                .distinct()
-            )
-            return list(result.all())
-
-    async def start(self, items: Iterable[InjectQueueItem], turn_id: str) -> None:
-        await self._mark(items, status="running", turn_id=turn_id, delivered=True)
-
-    async def finish(
-        self, items: Iterable[InjectQueueItem], status: str = "done"
-    ) -> None:
-        await self._mark(items, status=status)
-
-    async def interrupted(self) -> Sequence[InjectQueueItem]:
-        async with self._db.session() as session:
-            result = await session.exec(
-                select(InjectQueueItem).where(InjectQueueItem.status == "running")
-            )
-            rows = list(result.all())
-            for row in rows:
-                row.status = "interrupted"
-                session.add(row)
-            await session.commit()
-        return rows
-
-    async def recent(
-        self, conversation_id: int, *, limit: int = 50
-    ) -> list[InjectQueueItem]:
-        async with self._db.session() as session:
-            result = await session.exec(
-                select(InjectQueueItem)
-                .where(InjectQueueItem.conversation_id == conversation_id)
-                .order_by(col(InjectQueueItem.id).desc())
-                .limit(limit)
-            )
-            return list(result.all())
-
-    async def _mark(
-        self,
-        items: Iterable[InjectQueueItem],
-        *,
-        status: str,
-        turn_id: str | None = None,
-        delivered: bool = False,
-    ) -> None:
-        ids = [i.id for i in items if i.id is not None]
-        if not ids:
-            return
-        async with self._db.session() as session:
-            result = await session.exec(
-                select(InjectQueueItem).where(col(InjectQueueItem.id).in_(ids))
-            )
-            for row in result.all():
-                row.status = status
-                if turn_id is not None:
-                    row.turn_id = turn_id
-                if delivered:
-                    row.delivered_at = datetime.now(UTC)
-                session.add(row)
-            await session.commit()

src/beaver_gateway/core/registry.py

@@ -1,86 +0,0 @@
-"""Agent / MCP registries + the user-facing ``Gateway`` collector.
-
-The user's ``/config/config.py`` ends with::
-
-    gateway = Gateway(agents=[...], mcps=[...], frontends=[...])
-
-``cli.main`` picks that object up and builds the registries.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from collections.abc import Iterable, Iterator
-
-    from beaver_gateway.agents.base import BaseAgent
-    from beaver_gateway.core.conversations import ConversationTexts
-    from beaver_gateway.frontends.base import Frontend
-    from beaver_gateway.mcp.types import McpServerT
-
-
-class AgentRegistry:
-    """Name → agent lookup with duplicate detection."""
-
-    def __init__(self, agents: Iterable[BaseAgent]) -> None:
-        self._agents: dict[str, BaseAgent] = {}
-        for a in agents:
-            if a.name in self._agents:
-                msg = f"duplicate agent name: {a.name!r}"
-                raise ValueError(msg)
-            self._agents[a.name] = a
-
-    def __getitem__(self, name: str) -> BaseAgent:
-        return self._agents[name]
-
-    def get(self, name: str) -> BaseAgent | None:
-        return self._agents.get(name)
-
-    def __iter__(self) -> Iterator[BaseAgent]:
-        return iter(self._agents.values())
-
-    def __len__(self) -> int:
-        return len(self._agents)
-
-    def __contains__(self, name: object) -> bool:
-        return name in self._agents
-
-
-class McpRegistry:
-    """Name → MCP server lookup with duplicate detection."""
-
-    def __init__(self, mcps: Iterable[McpServerT]) -> None:
-        self._mcps: dict[str, McpServerT] = {}
-        for m in mcps:
-            if m.name in self._mcps:
-                msg = f"duplicate mcp name: {m.name!r}"
-                raise ValueError(msg)
-            self._mcps[m.name] = m
-
-    def __getitem__(self, name: str) -> McpServerT:
-        return self._mcps[name]
-
-    def get(self, name: str) -> McpServerT | None:
-        return self._mcps.get(name)
-
-    def __iter__(self) -> Iterator[McpServerT]:
-        return iter(self._mcps.values())
-
-    def __len__(self) -> int:
-        return len(self._mcps)
-
-    def __contains__(self, name: object) -> bool:
-        return name in self._mcps
-
-
-@dataclass(slots=True)
-class Gateway:
-    """Top-level object the user assembles in ``/config/config.py``."""
-
-    agents: list[BaseAgent] = field(default_factory=list)
-    mcps: list[McpServerT] = field(default_factory=list)
-    frontends: list[Frontend] = field(default_factory=list)
-    texts: ConversationTexts | None = None
-    """Merge prompt and seed bodies for ``core/conversations`` (§8.2-8.3)."""

src/beaver_gateway/core/turn_record.py

@@ -1,133 +0,0 @@
-"""Cross-frontend turn record.
-
-Frontends that finish a turn (the Anthropic Messages frontend, the
-markdown frontend) emit a :class:`TurnRecord` to every handler in
-``GatewayRuntime.turn_log_handlers``. The markdown frontend uses this
-to persist chats from other frontends into the Obsidian vault — see
-``frontends/markdown/crossfront.py``.
-
-Kept tiny on purpose: it carries the structured-enough payload a logger
-needs (which agent ran, input history, the assembled assistant reply)
-and nothing else. The full event stream is gone by the time handlers
-run — if a future consumer needs deltas it would subscribe at a lower
-level, not here.
-"""
-
-from __future__ import annotations
-
-import re
-from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any
-
-if TYPE_CHECKING:
-    from anthropic.types import Message, MessageParam
-
-
-__all__ = ["TurnRecord", "slugify"]
-
-
-# Filesystem-safe slug: collapse anything that isn't a word char or
-# space/hyphen to a hyphen, then squash runs of separators. Aimed at
-# letting users build filenames from ``record.first_user_text`` without
-# hand-rolling sanitization in every config.
-_SLUG_BAD_RE = re.compile(r"[^\w\s\-]+", flags=re.UNICODE)
-_SLUG_SEP_RE = re.compile(r"[\s\-]+", flags=re.UNICODE)
-
-
-def slugify(text: str, *, maxlen: int = 40) -> str:
-    """Sanitize ``text`` for use as a filename fragment.
-
-    Strips punctuation, collapses whitespace/hyphens into single ``-``,
-    and truncates to ``maxlen``. Returns ``"untitled"`` for empty input.
-    Unicode letters are preserved (Obsidian handles them fine; macOS
-    and modern Linux fs's too).
-    """
-    cleaned = _SLUG_BAD_RE.sub(" ", text).strip()
-    cleaned = _SLUG_SEP_RE.sub("-", cleaned).strip("-")
-    if not cleaned:
-        return "untitled"
-    if len(cleaned) > maxlen:
-        cleaned = cleaned[:maxlen].rstrip("-")
-    return cleaned or "untitled"
-
-
-@dataclass(frozen=True, slots=True)
-class TurnRecord:
-    """One completed turn, as seen by a frontend.
-
-    ``input_messages`` is the conversation history sent to the backend
-    (everything *before* the assistant reply). ``output_message`` is the
-    finalized assistant ``Message`` (post-accumulation, with all content
-    blocks attached). ``system`` is the per-request system prompt if any
-    — agents own their own ``system_prompt``, this is the override the
-    caller passed; most handlers can ignore it.
-
-    ``source`` names the frontend that produced the record so the
-    cross-frontend logger can avoid logging its own turns (markdown
-    frontend writing the file would otherwise also receive its own
-    broadcast and double-write).
-    """
-
-    agent_name: str
-    input_messages: list[MessageParam]
-    output_message: Message
-    system: str | None = None
-    source: str = "anthropic"
-
-    @property
-    def first_user_text(self) -> str:
-        """Plain text of the *earliest* user turn in this conversation.
-
-        Useful for naming new files by topic. Empty string if the input
-        history somehow has no user turn (shouldn't happen — turns are
-        broadcast only after a user → assistant cycle).
-        """
-        for msg in self.input_messages:
-            if msg.get("role") == "user":
-                return _text_of(msg.get("content", ""))
-        return ""
-
-    @property
-    def last_user_text(self) -> str:
-        """Plain text of the most recent user turn (the trigger)."""
-        for msg in reversed(self.input_messages):
-            if msg.get("role") == "user":
-                return _text_of(msg.get("content", ""))
-        return ""
-
-    @property
-    def assistant_text(self) -> str:
-        """Plain text of the assistant reply, with thinking/tool blocks dropped."""
-        chunks = [
-            getattr(block, "text", "") or ""
-            for block in getattr(self.output_message, "content", ())
-            if getattr(block, "type", None) == "text"
-        ]
-        return "\n\n".join(c for c in chunks if c)
-
-
-def _text_of(content: object) -> str:
-    """Flatten an Anthropic ``MessageParam.content`` field to a plain string.
-
-    Handles both shapes the SDK accepts: raw string, or a list of block
-    dicts (we pull ``text`` blocks only). Anything we don't recognize is
-    silently skipped — these helpers exist for naming files, not for
-    faithful content reconstruction.
-    """
-    if isinstance(content, str):
-        return content
-    if isinstance(content, list):
-        parts: list[str] = []
-        for blk in content:
-            if not isinstance(blk, dict):
-                continue
-            # ``MessageParam.content`` is typed as a union of typed-dicts
-            # per Anthropic SDK; we only care about plain ``text`` blocks
-            # and look them up via ``Any`` to dodge the keyed-typed-dict
-            # variance gymnastics (``ty`` won't let an open dict alias a
-            # closed-keyed one).
-            d: Any = blk
-            if d.get("type") == "text":
-                parts.append(str(d.get("text", "")))
-        return "\n\n".join(p for p in parts if p)
-    return ""

src/beaver_gateway/events/__init__.py

@@ -0,0 +1 @@
+"""The in-process event bus and the stream event protocol backends emit."""

src/beaver_gateway/events/bus.py

@@ -1,10 +1,7 @@
 """In-process event bus: what the gateway does, as a stream frontends can tap.
 
-Events are plain dicts ``{"type", "seq", "ts", ...}``. Publishers never
+Events are plain dicts. Publishers never block; a subscriber that falls
-block; a subscriber that falls behind loses its oldest events rather than
+behind loses its oldest events rather than stalling the publisher.
-stalling the turn that produced them. ``/api/events`` serialises the
-stream as SSE, the panel builds its subagent tree from ``stream`` events
-carrying ``parent_tool_use_id``.
 """
 
 from __future__ import annotations

src/beaver_gateway/events/stream.py

@@ -1,11 +1,7 @@
-"""Unified streaming-event protocol shared by every backend adapter.
+"""Streaming-event protocol shared by every backend adapter.
 
-We piggyback on :mod:`anthropic.types` rather than reinvent the wire format:
+Aliases over :mod:`anthropic.types` plus ``build_*`` helpers that keep
-``AnthropicMessagesFrontend`` ultimately serializes whatever a backend yields
+verbose constructors out of adapters.
-straight to SSE via :py:meth:`pydantic.BaseModel.model_dump_json`, so events
-must be valid Anthropic ``message_stream`` records. The aliases below give
-the rest of the codebase one import path; the ``build_*`` helpers keep the
-verbose constructors out of every adapter.
 """
 
 from __future__ import annotations

src/beaver_gateway/frontends/accumulate.py

@@ -1,11 +1,7 @@
 """Collapse an Anthropic event stream into one ``Message``.
 
-Extracted from ``AnthropicMessagesFrontend`` so the markdown frontend
+Mirrors the Anthropic SDK's own accumulator: folds content-block deltas
-can run the same accumulation logic when it wants the finalized turn
+into finalized blocks, indexed by their ``content_block`` index.
-rather than raw SSE chunks. Mirrors the Anthropic SDK's own accumulator:
-walks events, builds block dicts indexed by their ``content_block``
-index, folds text / thinking deltas in, buffers ``input_json_delta``
-chunks until the block closes (then JSON-parses them once).
 """
 
 from __future__ import annotations
@@ -33,7 +29,7 @@ from anthropic.types import (
 if TYPE_CHECKING:
     from collections.abc import AsyncIterator
 
-    from beaver_gateway.core.events import MessageStreamEvent, StopReason
+    from beaver_gateway.events.stream import MessageStreamEvent, StopReason
 
 
 __all__ = ["StreamAccumulator", "accumulate"]
@@ -42,9 +38,7 @@ __all__ = ["StreamAccumulator", "accumulate"]
 class StreamAccumulator:
     """Folds a stream of events into one ``Message``, incrementally.
 
-    Use when you need to *both* forward events somewhere (SSE) *and*
+    Call :meth:`feed` for each event, then :meth:`finalize` once.
-    keep a finalized ``Message`` for post-stream work (audit, logging
-    to disk). Call :meth:`feed` for each event, :meth:`finalize` once.
     """
 
     __slots__ = (
@@ -67,10 +61,11 @@ class StreamAccumulator:
         self._stop_sequence: str | None = None
 
     def feed(self, ev: MessageStreamEvent) -> None:
-        # isinstance, not ``ev.type == "..."``: ty narrows on the
+        """Fold one stream event into the in-progress message state.
-        # discriminator only via the class, and the raw event union
+
-        # carries its own discriminators (``Raw*Event``) the SDK
+        Uses ``isinstance`` rather than ``ev.type == ...`` so ty narrows
-        # already promises.
+        the event type from the class, not a string comparison.
+        """
         if isinstance(ev, RawMessageStartEvent):
             self._message_id = ev.message.id
             self._role = ev.message.role
@@ -109,6 +104,11 @@ class StreamAccumulator:
                 )
 
     def finalize(self, *, model: str) -> Message:
+        """Build the finalized ``Message`` from accumulated block state.
+
+        ``role`` is always ``"assistant"`` at the wire level; the cast
+        avoids a runtime check ty would otherwise require.
+        """
         content: list[Any] = []
         for idx in sorted(self._blocks):
             bd = self._blocks[idx]
@@ -120,10 +120,6 @@ class StreamAccumulator:
             elif btype == "thinking":
                 content.append(ThinkingBlock.model_validate(bd))
 
-        # ``role`` is always ``"assistant"`` at the wire level — we
-        # initialised the field to that and only overwrite from a
-        # ``RawMessageStartEvent`` which itself carries the same literal.
-        # The cast keeps both type-checkers happy without a runtime check.
         return Message(
             id=self._message_id or "msg_unknown",
             type="message",

src/beaver_gateway/frontends/admin/frontend.py

@@ -1,15 +1,7 @@
 """Admin console: serves the ``ui/`` SPA and signs the operator in.
 
-Everything the console shows comes from ``/api/*`` (``ApiFrontend``)
+Login/logout/session live under ``/admin/auth``; a process-lifetime
-with a bearer. The admin port only owns three JSON routes under
+admin bearer (scope ``*``) is minted at startup and rotates on restart.
-``/admin/auth`` - login (``ADMIN_USER`` / ``ADMIN_PASS`` from env,
-session cookie signed with ``SESSION_SECRET``, 8 h), logout, and
-``session``, which hands a signed-in browser the process-lifetime admin
-bearer plus the API origin - and the static build under ``/admin/``.
-
-The bearer is minted at startup, registered in the token store with
-scope ``*`` and never persisted; a gateway restart rotates it, and the
-SPA refetches ``session`` on a 401.
 """
 
 from __future__ import annotations
@@ -25,10 +17,10 @@ from typing import TYPE_CHECKING, Any
 
 import itsdangerous
 from fastapi import FastAPI, HTTPException, Request, status
-from fastapi.responses import FileResponse, JSONResponse, RedirectResponse, Response
+from fastapi.responses import FileResponse, JSONResponse, Response
 
-from beaver_gateway.core import audit
 from beaver_gateway.frontends.base import Frontend
+from beaver_gateway.security import audit
 
 if TYPE_CHECKING:
     from beaver_gateway.frontends.base import GatewayRuntime
@@ -49,17 +41,10 @@ __all__ = ["AdminFrontend"]
 
 
 class AdminFrontend(Frontend):
-    def __init__(
+    path = BASE
-        self,
+    landing = True
-        *,
+
-        host: str = "0.0.0.0",  # noqa: S104
+    def __init__(self, *, ui_dir: Path | None = None) -> None:
-        port: int = 8002,
-        public_base_url: str | None = None,
-        ui_dir: Path | None = None,
-    ) -> None:
-        self.host = host
-        self.port = port
-        self.public_base_url = public_base_url.rstrip("/") if public_base_url else None
         self.ui_dir = (ui_dir or DEFAULT_UI_DIR).resolve()
         self._app: FastAPI | None = None
 
@@ -78,16 +63,8 @@ class AdminFrontend(Frontend):
                 "admin UI build missing at %s (run `make ui-build`)", self.ui_dir
             )
 
-    async def serve(self) -> None:
+    def app(self) -> FastAPI | None:
-        import uvicorn
+        return self._app
-
-        if self._app is None:
-            msg = "configure() must be called before serve()"
-            raise RuntimeError(msg)
-        config = uvicorn.Config(
-            self._app, host=self.host, port=self.port, log_level="info"
-        )
-        await uvicorn.Server(config).serve()
 
 
 def build_app(runtime: GatewayRuntime, *, token: str, ui_dir: Path) -> FastAPI:
@@ -100,13 +77,7 @@ def build_app(runtime: GatewayRuntime, *, token: str, ui_dir: Path) -> FastAPI:
     )
     index = ui_dir / "index.html"
 
-    @app.get("/")
+    @app.post("/auth/login")
-    async def root() -> Response:
-        return RedirectResponse(
-            f"{BASE}/", status_code=status.HTTP_307_TEMPORARY_REDIRECT
-        )
-
-    @app.post(f"{BASE}/auth/login")
     async def login(request: Request) -> Response:
         try:
             data = await request.json()
@@ -157,7 +128,7 @@ def build_app(runtime: GatewayRuntime, *, token: str, ui_dir: Path) -> FastAPI:
         await audit.log(runtime, actor=f"admin:{username}", kind="login_ok", ip=ip)
         return response
 
-    @app.post(f"{BASE}/auth/logout", status_code=status.HTTP_204_NO_CONTENT)
+    @app.post("/auth/logout", status_code=status.HTTP_204_NO_CONTENT)
     async def logout(request: Request) -> Response:
         user = _current_user(request, signer)
         response = Response(status_code=status.HTTP_204_NO_CONTENT)
@@ -166,15 +137,15 @@ def build_app(runtime: GatewayRuntime, *, token: str, ui_dir: Path) -> FastAPI:
             await audit.log(runtime, actor=f"admin:{user}", kind="logout")
         return response
 
-    @app.get(f"{BASE}/auth/session")
+    @app.get("/auth/session")
     async def session(request: Request) -> dict[str, Any]:
         user = _current_user(request, signer)
         if user is None:
             raise HTTPException(status.HTTP_401_UNAUTHORIZED, "not signed in")
-        return {"user": user, "token": token, "api_base": _api_base(request, runtime)}
+        return {"user": user, "token": token}
 
-    @app.get(BASE)
+    @app.get("/")
-    @app.get(f"{BASE}/{{path:path}}")
+    @app.get("/{path:path}")
     async def spa(path: str = "") -> Response:
         if path:
             target = (ui_dir / path).resolve()
@@ -204,21 +175,6 @@ def build_app(runtime: GatewayRuntime, *, token: str, ui_dir: Path) -> FastAPI:
     return app
 
 
-def _api_base(request: Request, runtime: GatewayRuntime) -> str | None:
-    for fe in runtime.frontends:
-        if fe.name != "api":
-            continue
-        public = getattr(fe, "public_base_url", None)
-        if public:
-            return public.removesuffix("/api")
-        port = getattr(fe, "port", None)
-        if port is None:
-            return None
-        scheme = request.headers.get("x-forwarded-proto") or request.url.scheme
-        return f"{scheme}://{request.url.hostname}:{port}"
-    return None
-
-
 def _current_user(
     request: Request, signer: itsdangerous.URLSafeTimedSerializer
 ) -> str | None:

src/beaver_gateway/frontends/anthropic.py

@@ -1,17 +1,8 @@
 """``POST /v1/messages`` frontend.
 
 Exposes the gateway as an Anthropic-compatible Messages endpoint, so any
-client that already speaks Anthropic (Cursor, Cline, the official SDK,
+client that already speaks Anthropic can reach a configured agent by
-``curl``) can hit a configured agent by passing its name as ``model``.
+passing its name as ``model``.
-
-A Claude agent behind this endpoint is a ``deep`` conversation: the client
-knows nothing about our ids, so the text fingerprint of the history it
-sends is the ``(anthropic, fingerprint)`` binding of the conversation,
-rebound after every turn to the fingerprint the next request will carry.
-A history nobody has seen becomes a new conversation, materialized by the
-home frontend of ``deep`` (the vault file), and every reply is published
-on the bus so that file follows the chat. Other agents (Raycast) stay
-stateless and are only archived through ``turn_log_handlers``.
 """
 
 from __future__ import annotations
@@ -25,21 +16,21 @@ from fastapi import FastAPI, HTTPException, Request, status
 from fastapi.responses import JSONResponse, StreamingResponse
 
 from beaver_gateway.agents.claude import ClaudeAgent
-from beaver_gateway.core import audit
+from beaver_gateway.backends.capture import TurnCapture
-from beaver_gateway.core.transcript import fingerprint, text_of
+from beaver_gateway.backends.transcript import fingerprint, text_of
-from beaver_gateway.core.turn_capture import TurnCapture
+from beaver_gateway.frontends.accumulate import StreamAccumulator
-from beaver_gateway.core.turn_record import TurnRecord
-from beaver_gateway.frontends._accumulate import StreamAccumulator
-from beaver_gateway.frontends._auth import require_token
 from beaver_gateway.frontends.base import Frontend
+from beaver_gateway.frontends.bearer import require_token
+from beaver_gateway.frontends.turn_record import TurnRecord
+from beaver_gateway.security import audit
 
 if TYPE_CHECKING:
     from collections.abc import AsyncIterator, Awaitable, Callable
 
     from anthropic.types import Message, MessageParam
 
-    from beaver_gateway.core.conversations import Conversations
+    from beaver_gateway.conversations.service import Conversations
-    from beaver_gateway.core.events import MessageStreamEvent
+    from beaver_gateway.events.stream import MessageStreamEvent
     from beaver_gateway.frontends.base import GatewayRuntime
     from beaver_gateway.storage.models import Conversation
 
@@ -58,17 +49,9 @@ class AnthropicMessagesFrontend(Frontend):
 
     name = FRONTEND
     kinds = ("deep",)
+    path = "/anthropic"
 
-    def __init__(
+    def __init__(self) -> None:
-        self,
-        *,
-        host: str = "0.0.0.0",  # noqa: S104
-        port: int = 8000,
-        public_base_url: str | None = None,
-    ) -> None:
-        self.host = host
-        self.port = port
-        self.public_base_url = public_base_url.rstrip("/") if public_base_url else None
         self._runtime: GatewayRuntime | None = None
         self._app: FastAPI | None = None
 
@@ -76,18 +59,8 @@ class AnthropicMessagesFrontend(Frontend):
         self._runtime = runtime
         self._app = self._build_app(runtime)
 
-    async def serve(self) -> None:
+    def app(self) -> FastAPI | None:
-        import uvicorn
+        return self._app
-
-        if self._app is None:
-            msg = "configure() must be called before serve()"
-            raise RuntimeError(msg)
-
-        config = uvicorn.Config(
-            self._app, host=self.host, port=self.port, log_level="info"
-        )
-        server = uvicorn.Server(config)
-        await server.serve()
 
     def _build_app(self, runtime: GatewayRuntime) -> FastAPI:
         app = FastAPI(title="beaver-gateway / Anthropic Messages")
@@ -293,10 +266,8 @@ async def _sse(
 ) -> AsyncIterator[bytes]:
     r"""Serialize an event stream to SSE, then hand the assembled ``Message`` on.
 
-    Each event becomes ``event: <type>\ndata: <json>\n\n`` - the shape
+    Wire format is ``event: <type>\ndata: <json>\n\n``; mid-stream errors
-    the Anthropic SDK's SSE decoder expects. Errors mid-stream are
+    become a synthetic ``error`` event instead of a hung connection.
-    swallowed into a synthetic ``error`` event so the client sees the
-    failure rather than a hung connection.
     """
     acc = StreamAccumulator()
     try:

src/beaver_gateway/frontends/api/__init__.py

@@ -1,4 +1,4 @@
-"""``ApiFrontend`` - the conversations API and event stream (§3.9)."""
+"""``ApiFrontend`` - the conversations API and event stream."""
 
 from beaver_gateway.frontends.api.frontend import ApiFrontend
 

src/beaver_gateway/frontends/api/frontend.py

@@ -1,17 +1,7 @@
-"""``ApiFrontend`` - ``/api/*``: conversations, SSE, sessions, usage, limits (§3.9).
+"""``ApiFrontend`` - ``/api/*``: conversations, SSE, sessions, usage, limits.
 
 Bearer scope ``api``; token and audit management need ``admin``. Every
-write goes through ``core/conversations``; the frontend only shapes JSON.
+write goes through conversations/service.py; the frontend only shapes JSON.
-``/api/events`` and ``/api/conversations/{id}/events`` replay the gateway
-bus as SSE with the same keepalive the markdown frontend uses, so a proxy
-never sees a silent socket.
-
-Usage figures come from the ``usage`` table (one row per turn, API-price
-``cost_usd`` and per-model ``model_usage`` from the SDK's
-``ResultMessage``); subscription quotas come from ``rate_limits``
-(``RateLimitEvent``). The quota covers the whole subscription, so
-``/api/limits`` puts the gateway's own spend for the window next to it
-for calibration by eye.
 """
 
 from __future__ import annotations
@@ -28,32 +18,46 @@ from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import JSONResponse, StreamingResponse
 from sqlmodel import col, select
 
-from beaver_gateway.core import audit
+from beaver_gateway.agents.claude import ClaudeAgent
-from beaver_gateway.core.auth import VALID_SCOPES, hash_token
+from beaver_gateway.agents.prompts import assemble
-from beaver_gateway.core.conversations import SEEDS
+from beaver_gateway.backends.transcript import prompt_count
-from beaver_gateway.core.kinds import Kind, as_kind
+from beaver_gateway.conversations.context import compose
-from beaver_gateway.frontends._auth import require_token
+from beaver_gateway.conversations.injects import URGENCY
-from beaver_gateway.frontends._sse import (
+from beaver_gateway.conversations.kinds import Kind, as_kind
+from beaver_gateway.conversations.service import SEEDS, implied_title
+from beaver_gateway.frontends.base import Frontend
+from beaver_gateway.frontends.bearer import require_token
+from beaver_gateway.frontends.sse import (
     KEEPALIVE,
     SSE_HEADERS,
     events_with_heartbeat,
     sse_pack,
 )
-from beaver_gateway.frontends.base import Frontend
+from beaver_gateway.frontends.urls import frontend_url
+from beaver_gateway.security import audit
+from beaver_gateway.security.auth import hash_token
 from beaver_gateway.storage import (
     create_token,
     list_audit_records,
     list_tokens,
     revoke_token,
 )
-from beaver_gateway.storage.models import Conversation, RateLimit, Token, Usage
+from beaver_gateway.storage.models import (
+    Conversation,
+    InjectQueueItem,
+    RateLimit,
+    Token,
+    Usage,
+)
+from beaver_gateway.vault.links import LinkIndex
 
 if TYPE_CHECKING:
     from collections.abc import AsyncIterator, Iterable, Sequence
     from pathlib import Path
 
-    from beaver_gateway.core.conversations import Conversations
+    from beaver_gateway.conversations.service import Conversations
     from beaver_gateway.frontends.base import GatewayRuntime
+    from beaver_gateway.jobs.scheduler import Job, Scheduler
 
 _log = logging.getLogger("beaver_gateway.frontends.api")
 
@@ -71,32 +75,33 @@ WINDOWS: dict[str, timedelta] = {
 MEMORY_MAX_DEPTH = 12
 MEMORY_MAX_FILE = 2_000_000
 MEMORY_MAX_ENTRIES = 5000
+SEARCH_MIN = 2
+GRAPH_LIMIT = 120
+SEARCH_LIMIT = 20
+SNIPPET_MAX = 160
 
 
 class ApiFrontend(Frontend):
     name = "api"
     kinds = ("master", "branch", "deep", "job")
+    path = "/api"
 
     def __init__(
         self,
         *,
-        host: str = "0.0.0.0",  # noqa: S104
-        port: int = 8004,
-        public_base_url: str | None = None,
         master_agent: str | None = None,
         branch_agent: str | None = None,
         deep_agent: str | None = None,
         job_agent: str | None = None,
         memory_root: Path | None = None,
+        vault_root: Path | None = None,
     ) -> None:
-        self.host = host
-        self.port = port
-        self.public_base_url = public_base_url.rstrip("/") if public_base_url else None
         self.master_agent = master_agent
         self.branch_agent = branch_agent
         self.deep_agent = deep_agent
         self.job_agent = job_agent
         self.memory_root = memory_root.resolve() if memory_root is not None else None
+        self.vault_root = vault_root.resolve() if vault_root is not None else None
         self._app: FastAPI | None = None
 
     def agent_for(self, kind: Kind) -> str | None:
@@ -111,22 +116,22 @@ class ApiFrontend(Frontend):
         if runtime.conversations is None or runtime.bus is None:
             msg = "ApiFrontend needs runtime.conversations and runtime.bus"
             raise RuntimeError(msg)
-        self._app = build_app(runtime, memory_root=self.memory_root)
+        self._app = build_app(
-
+            runtime, memory_root=self.memory_root, vault_root=self.vault_root
-    async def serve(self) -> None:
-        import uvicorn
-
-        if self._app is None:
-            msg = "configure() must be called before serve()"
-            raise RuntimeError(msg)
-        server = uvicorn.Server(
-            uvicorn.Config(self._app, host=self.host, port=self.port, log_level="info")
         )
-        await server.serve()
+
+    def app(self) -> FastAPI | None:
+        return self._app
 
 
-def build_app(runtime: GatewayRuntime, *, memory_root: Path | None = None) -> FastAPI:  # noqa: PLR0915
+def build_app(  # noqa: PLR0915
+    runtime: GatewayRuntime,
+    *,
+    memory_root: Path | None = None,
+    vault_root: Path | None = None,
+) -> FastAPI:
     app = FastAPI(title="beaver-gateway / API")
+    links = LinkIndex(vault_root) if vault_root is not None else None
     app.add_middleware(
         CORSMiddleware,
         allow_origins=["*"],
@@ -150,7 +155,7 @@ def build_app(runtime: GatewayRuntime, *, memory_root: Path | None = None) -> Fa
         return data
 
     async def conv_of(public_id: str) -> Conversation:
-        conv = await conversations.get(public_id)
+        conv = await conversations.resolve(public_id)
         if conv is None:
             raise HTTPException(
                 status.HTTP_404_NOT_FOUND, f"unknown conversation {public_id}"
@@ -163,6 +168,14 @@ def build_app(runtime: GatewayRuntime, *, memory_root: Path | None = None) -> Fa
             raise HTTPException(status.HTTP_400_BAD_REQUEST, f"missing `{key}`")
         return text
 
+    def urgency_of(data: dict[str, Any], default: str) -> Any:
+        urgency = str(data.get("urgency") or default)
+        if urgency not in URGENCY:
+            raise HTTPException(
+                status.HTTP_400_BAD_REQUEST, f"urgency must be one of {URGENCY}"
+            )
+        return urgency
+
     def int_or_none(data: dict[str, Any], key: str) -> int | None:
         value = data.get(key)
         if value is None:
@@ -181,7 +194,7 @@ def build_app(runtime: GatewayRuntime, *, memory_root: Path | None = None) -> Fa
     async def healthz() -> dict[str, str]:
         return {"status": "ok"}
 
-    @app.get("/api/agents")
+    @app.get("/agents")
     async def list_agents(request: Request) -> dict[str, Any]:
         await require_token(request, runtime, scope=SCOPE)
         return {
@@ -203,15 +216,16 @@ def build_app(runtime: GatewayRuntime, *, memory_root: Path | None = None) -> Fa
                     "default_agents": {
                         k: fe.agent_for(k) for k in fe.kinds if fe.agent_for(k)
                     },
-                    "port": getattr(fe, "port", None),
+                    "path": fe.path,
-                    "public_base_url": getattr(fe, "public_base_url", None),
+                    "scope": fe.scope,
+                    "url": frontend_url(request, runtime, fe),
                 }
                 for fe in runtime.frontends
             ],
             "mcps": [{"name": m.name, "kind": m.kind} for m in runtime.mcps],
         }
 
-    @app.get("/api/conversations")
+    @app.get("/conversations")
     async def list_conversations(request: Request) -> dict[str, Any]:
         await require_token(request, runtime, scope=SCOPE)
         q = request.query_params
@@ -220,9 +234,54 @@ def build_app(runtime: GatewayRuntime, *, memory_root: Path | None = None) -> Fa
             kind=q.get("kind"),
             limit=query_int(request, "limit", 200),
         )
-        return {"conversations": [conversations.public(r) for r in rows]}
+        latest = await conversations.queue.latest(cast("int", r.id) for r in rows)
+        firsts = await conversations.first_user_texts(
+            cast("int", r.id) for r in rows if not r.title
+        )
+        contexts = await conversations.context_tokens_by_id(r.external_id for r in rows)
+        public_ids = {r.id: r.external_id for r in rows}
+        return {
+            "conversations": [
+                {
+                    **conversations.public(r),
+                    "title": r.title or implied_title(firsts.get(cast("int", r.id))),
+                    "last_item": _queue_item(latest.get(cast("int", r.id))),
+                    "context_tokens": contexts.get(r.external_id, 0),
+                    "parent": public_ids.get(r.parent_id) if r.parent_id else None,
+                }
+                for r in rows
+            ]
+        }
 
-    @app.post("/api/conversations", status_code=status.HTTP_201_CREATED)
+    @app.get("/search")
+    async def search(request: Request) -> dict[str, Any]:
+        await require_token(request, runtime, scope=SCOPE)
+        query = (request.query_params.get("q") or "").strip()
+        if len(query) < SEARCH_MIN:
+            raise HTTPException(
+                status.HTTP_400_BAD_REQUEST, f"q must be at least {SEARCH_MIN} chars"
+            )
+        limit = min(query_int(request, "limit", SEARCH_LIMIT), SEARCH_LIMIT)
+        rows = await conversations.search(query, limit=limit)
+        firsts = await conversations.first_user_texts(
+            cast("int", r.id) for r in rows if not r.title
+        )
+        contexts = await conversations.context_tokens_by_id(r.external_id for r in rows)
+        files = _grep_memory(memory_root, query, limit=limit) if memory_root else []
+        return {
+            "query": query,
+            "conversations": [
+                {
+                    **conversations.public(r),
+                    "title": r.title or implied_title(firsts.get(cast("int", r.id))),
+                    "context_tokens": contexts.get(r.external_id, 0),
+                }
+                for r in rows
+            ],
+            "files": files,
+        }
+
+    @app.post("/conversations", status_code=status.HTTP_201_CREATED)
     async def create_conversation(request: Request) -> dict[str, Any]:
         token = await require_token(request, runtime, scope=SCOPE)
         data = await body_of(request)
@@ -266,25 +325,18 @@ def build_app(runtime: GatewayRuntime, *, memory_root: Path | None = None) -> Fa
         )
         return await conversations.describe(conv)
 
-    @app.get("/api/conversations/{public_id}")
+    @app.get("/conversations/{public_id}")
     async def get_conversation(public_id: str, request: Request) -> dict[str, Any]:
         await require_token(request, runtime, scope=SCOPE)
         conv = await conv_of(public_id)
         out = await conversations.describe(conv)
         out["queue"] = [
-            {
+            _queue_item(i)
-                "id": i.id,
-                "priority": i.priority,
-                "origin": i.origin,
-                "status": i.status,
-                "created_at": _iso(i.created_at),
-                "text": i.text[:200],
-            }
             for i in await conversations.queue.recent(cast("int", conv.id), limit=20)
         ]
         return out
 
-    @app.get("/api/conversations/{public_id}/messages")
+    @app.get("/conversations/{public_id}/messages")
     async def get_messages(public_id: str, request: Request) -> dict[str, Any]:
         await require_token(request, runtime, scope=SCOPE)
         conv = await conv_of(public_id)
@@ -295,13 +347,52 @@ def build_app(runtime: GatewayRuntime, *, memory_root: Path | None = None) -> Fa
             "text": await conversations.read(conv, window=window),
         }
 
-    @app.get("/api/conversations/{public_id}/history")
+    @app.get("/conversations/{public_id}/history")
     async def get_history(public_id: str, request: Request) -> dict[str, Any]:
         await require_token(request, runtime, scope=SCOPE)
         conv = await conv_of(public_id)
         return {"id": conv.external_id, "messages": await conversations.history(conv)}
 
-    @app.get("/api/conversations/{public_id}/entries")
+    @app.get("/conversations/{public_id}/context")
+    async def get_context(public_id: str, request: Request) -> dict[str, Any]:
+        await require_token(request, runtime, scope=SCOPE)
+        conv = await conv_of(public_id)
+        agent = runtime.agents.get(conv.agent_name)
+        if not isinstance(agent, ClaudeAgent):
+            raise HTTPException(
+                status.HTTP_404_NOT_FOUND, f"no claude agent behind {public_id}"
+            )
+        entries = list(await conversations.entries(conv))
+        for sub in await conversations.subpaths(conv):
+            entries.extend(await conversations.entries(conv, subpath=sub))
+        out = compose(
+            agent,
+            as_kind(conv.kind),
+            entries,
+            context_tokens=await conversations.context_tokens(conv),
+        )
+        out["id"] = conv.external_id
+        out["turns"] = prompt_count(entries)
+        if request.query_params.get("prompt"):
+            sources = agent.prompt_for(as_kind(conv.kind))
+            out["prompt_text"] = (
+                assemble(sources) if sources is not None else agent.system_prompt
+            )
+        return out
+
+    @app.get("/vault/graph")
+    async def vault_graph(request: Request) -> dict[str, Any]:
+        await require_token(request, runtime, scope=SCOPE)
+        if links is None:
+            raise HTTPException(
+                status.HTTP_404_NOT_FOUND,
+                "no vault root: set ApiFrontend(vault_root=...)",
+            )
+        paths = [p for p in request.query_params.getlist("path") if p]
+        limit = min(query_int(request, "limit", GRAPH_LIMIT), GRAPH_LIMIT)
+        return {"root": str(links.root), **links.neighbours(paths, limit=limit)}
+
+    @app.get("/conversations/{public_id}/entries")
     async def get_entries(public_id: str, request: Request) -> dict[str, Any]:
         await require_token(request, runtime, scope=SCOPE)
         conv = await conv_of(public_id)
@@ -319,7 +410,7 @@ def build_app(runtime: GatewayRuntime, *, memory_root: Path | None = None) -> Fa
         }
 
     @app.post(
-        "/api/conversations/{public_id}/messages", status_code=status.HTTP_202_ACCEPTED
+        "/conversations/{public_id}/messages", status_code=status.HTTP_202_ACCEPTED
     )
     async def post_message(public_id: str, request: Request) -> dict[str, Any]:
         token = await require_token(request, runtime, scope=SCOPE)
@@ -337,22 +428,16 @@ def build_app(runtime: GatewayRuntime, *, memory_root: Path | None = None) -> Fa
         )
         return {"id": conv.external_id, "item": item.id, "status": item.status}
 
-    @app.post(
+    @app.post("/conversations/{public_id}/inject", status_code=status.HTTP_202_ACCEPTED)
-        "/api/conversations/{public_id}/inject", status_code=status.HTTP_202_ACCEPTED
-    )
     async def post_inject(public_id: str, request: Request) -> dict[str, Any]:
         token = await require_token(request, runtime, scope=SCOPE)
         conv = await conv_of(public_id)
         data = await body_of(request)
-        urgency = str(data.get("urgency") or "normal")
+        urgency = urgency_of(data, "normal")
-        if urgency not in ("normal", "urgent"):
-            raise HTTPException(
-                status.HTTP_400_BAD_REQUEST, "urgency must be normal|urgent"
-            )
         item = await conversations.inject(
             conv,
             text_of(data),
-            urgency=cast("Any", urgency),
+            urgency=urgency,
             origin=str(data.get("origin") or "api"),
         )
         await audit.log(
@@ -365,13 +450,13 @@ def build_app(runtime: GatewayRuntime, *, memory_root: Path | None = None) -> Fa
         )
         return {"id": conv.external_id, "item": item.id, "priority": item.priority}
 
-    @app.post("/api/conversations/{public_id}/say")
+    @app.post("/conversations/{public_id}/say")
     async def post_say(public_id: str, request: Request) -> dict[str, Any]:
         await require_token(request, runtime, scope=SCOPE)
         conv = await conv_of(public_id)
         return await conversations.say(conv, text_of(await body_of(request)))
 
-    @app.post("/api/conversations/{public_id}/answer")
+    @app.post("/conversations/{public_id}/answer")
     async def post_answer(public_id: str, request: Request) -> dict[str, Any]:
         await require_token(request, runtime, scope=SCOPE)
         conv = await conv_of(public_id)
@@ -383,9 +468,7 @@ def build_app(runtime: GatewayRuntime, *, memory_root: Path | None = None) -> Fa
             )
         return {"id": conv.external_id, "question_id": question_id}
 
-    @app.post(
+    @app.post("/conversations/{public_id}/branch", status_code=status.HTTP_201_CREATED)
-        "/api/conversations/{public_id}/branch", status_code=status.HTTP_201_CREATED
-    )
     async def post_branch(public_id: str, request: Request) -> dict[str, Any]:
         token = await require_token(request, runtime, scope=SCOPE)
         parent = await conv_of(public_id)
@@ -422,7 +505,7 @@ def build_app(runtime: GatewayRuntime, *, memory_root: Path | None = None) -> Fa
         )
         return await conversations.describe(child)
 
-    @app.post("/api/conversations/{public_id}/merge")
+    @app.post("/conversations/{public_id}/merge")
     async def post_merge(public_id: str, request: Request) -> dict[str, Any]:
         token = await require_token(request, runtime, scope=SCOPE)
         conv = await conv_of(public_id)
@@ -444,7 +527,37 @@ def build_app(runtime: GatewayRuntime, *, memory_root: Path | None = None) -> Fa
             "text": result.text,
         }
 
-    @app.post("/api/conversations/{public_id}/fork")
+    @app.post("/conversations/{public_id}/close")
+    async def post_close(public_id: str, request: Request) -> dict[str, Any]:
+        token = await require_token(request, runtime, scope=SCOPE)
+        conv = await conv_of(public_id)
+        if conv.kind != "deep":
+            closed = await conversations.close(conv)
+            return {"id": closed.external_id, "status": closed.status}
+        try:
+            result = await conversations.distill(conv, reason="api")
+        except (ValueError, LookupError) as exc:
+            raise HTTPException(status.HTTP_400_BAD_REQUEST, str(exc)) from exc
+        except RuntimeError as exc:
+            raise HTTPException(status.HTTP_409_CONFLICT, str(exc)) from exc
+        await audit.log(
+            runtime,
+            actor=f"token:{token}",
+            kind="api_close",
+            agent_name=conv.agent_name,
+            conversation=conv.external_id,
+            digest=str(result.digest.path) if result.digest else None,
+        )
+        return {
+            "id": conv.external_id,
+            "status": "closed",
+            "fork": result.fork.external_id,
+            "text": result.text,
+            "digest": str(result.digest.path) if result.digest else None,
+            "error": result.error,
+        }
+
+    @app.post("/conversations/{public_id}/fork")
     async def post_fork(public_id: str, request: Request) -> dict[str, Any]:
         await require_token(request, runtime, scope=SCOPE)
         conv = await conv_of(public_id)
@@ -464,32 +577,38 @@ def build_app(runtime: GatewayRuntime, *, memory_root: Path | None = None) -> Fa
             "text": result.text,
         }
 
-    @app.post("/api/conversations/{public_id}/bind")
+    @app.post("/conversations/{public_id}/bind")
     async def post_bind(public_id: str, request: Request) -> dict[str, Any]:
         await require_token(request, runtime, scope=SCOPE)
         conv = await conv_of(public_id)
         data = await body_of(request)
         frontend = text_of(data, "frontend")
-        external_id = text_of(data, "external_id")
+        external_id = data.get("external_id")
         try:
+            if isinstance(external_id, str) and external_id.strip():
                 await conversations.bind(
                     conv,
                     frontend=frontend,
                     external_id=external_id,
                     visible=bool(data.get("visible", True)),
                 )
+            elif await conversations.frontend(frontend).materialize(conv) is None:
+                raise HTTPException(
+                    status.HTTP_400_BAD_REQUEST,
+                    f"frontend {frontend!r} cannot open a window for {conv.kind!r}",
+                )
         except ValueError as exc:
             raise HTTPException(status.HTTP_400_BAD_REQUEST, str(exc)) from exc
         return await conversations.describe(conv)
 
-    @app.patch("/api/conversations/{public_id}/flags")
+    @app.patch("/conversations/{public_id}/flags")
     async def patch_flags(public_id: str, request: Request) -> dict[str, Any]:
         await require_token(request, runtime, scope=SCOPE)
         conv = await conv_of(public_id)
         data = await body_of(request)
         return conversations.public(await conversations.set_flags(conv, data))
 
-    @app.patch("/api/conversations/{public_id}")
+    @app.patch("/conversations/{public_id}")
     async def patch_conversation(public_id: str, request: Request) -> dict[str, Any]:
         await require_token(request, runtime, scope=SCOPE)
         conv = await conv_of(public_id)
@@ -503,18 +622,18 @@ def build_app(runtime: GatewayRuntime, *, memory_root: Path | None = None) -> Fa
             raise HTTPException(status.HTTP_400_BAD_REQUEST, str(exc)) from exc
         return conversations.public(conv)
 
-    @app.get("/api/conversations/{public_id}/events")
+    @app.get("/conversations/{public_id}/events")
     async def conversation_events(public_id: str, request: Request) -> Any:
         await require_token(request, runtime, scope=SCOPE)
         conv = await conv_of(public_id)
         return _sse(runtime, conversation_id=conv.external_id)
 
-    @app.get("/api/events")
+    @app.get("/events")
     async def all_events(request: Request) -> Any:
         await require_token(request, runtime, scope=SCOPE)
         return _sse(runtime, conversation_id=None)
 
-    @app.get("/api/sessions")
+    @app.get("/sessions")
     async def sessions(request: Request) -> dict[str, Any]:
         await require_token(request, runtime, scope=SCOPE)
         pool = runtime.pool
@@ -524,26 +643,70 @@ def build_app(runtime: GatewayRuntime, *, memory_root: Path | None = None) -> Fa
             "sessions": pool.snapshot() if pool is not None else [],
         }
 
-    @app.get("/api/schedules")
+    @app.get("/schedules")
     async def schedules(request: Request) -> dict[str, Any]:
         await require_token(request, runtime, scope=SCOPE)
         raw = request.query_params.get("conversation")
         conv = await conv_of(raw) if raw else None
-        return {
+        return {"schedules": await conversations.schedules(conv)}
-            "schedules": [
-                {
-                    "id": s.id,
-                    "conversation_row": s.conversation_id,
-                    "execute_at": _iso(s.execute_at),
-                    "text": s.text,
-                    "created_at": _iso(s.created_at),
-                    "delivered_at": _iso(s.delivered_at),
-                }
-                for s in await conversations.schedules(conv)
-            ]
-        }
 
-    @app.get("/api/usage")
+    def scheduler_of() -> Scheduler:
+        if runtime.scheduler is None:
+            raise HTTPException(status.HTTP_503_SERVICE_UNAVAILABLE, "no scheduler")
+        return cast("Scheduler", runtime.scheduler)
+
+    @app.get("/jobs")
+    async def jobs(request: Request) -> dict[str, Any]:
+        await require_token(request, runtime, scope=SCOPE)
+        return await scheduler_of().snapshot()
+
+    def job_of(scheduler: Scheduler, name: str) -> Job:
+        job = scheduler.job(name)
+        if job is None:
+            raise HTTPException(status.HTTP_404_NOT_FOUND, f"no job {name!r}")
+        return job
+
+    @app.post("/jobs/{name}/run", status_code=status.HTTP_202_ACCEPTED)
+    async def run_job(name: str, request: Request) -> dict[str, Any]:
+        await require_token(request, runtime, scope=SCOPE)
+        scheduler = scheduler_of()
+        job = job_of(scheduler, name)
+        return {"job": await scheduler.trigger(job, await body_of(request))}
+
+    @app.get("/jobs/{name}/runs")
+    async def job_runs(name: str, request: Request) -> dict[str, Any]:
+        await require_token(request, runtime, scope=SCOPE)
+        scheduler = scheduler_of()
+        job = job_of(scheduler, name)
+        limit = min(int(request.query_params.get("limit", 50)), 500)
+        return {"job": job.name, "runs": await scheduler.runs(job.name, limit)}
+
+    @app.delete("/jobs/queue/{job_id}")
+    async def cancel_job(job_id: int, request: Request) -> dict[str, Any]:
+        await require_token(request, runtime, scope=SCOPE)
+        if not await scheduler_of().cancel(job_id):
+            raise HTTPException(status.HTTP_404_NOT_FOUND, f"no queued job {job_id}")
+        return {"cancelled": job_id}
+
+    @app.post(
+        "/conversations/{public_id}/schedule", status_code=status.HTTP_201_CREATED
+    )
+    async def post_schedule(public_id: str, request: Request) -> dict[str, Any]:
+        await require_token(request, runtime, scope=SCOPE)
+        conv = await conv_of(public_id)
+        data = await body_of(request)
+        try:
+            job_id, when = await conversations.schedule(
+                conv,
+                text_of(data, "at"),
+                text_of(data, "text"),
+                urgency=urgency_of(data, "wake"),
+            )
+        except (RuntimeError, ValueError) as exc:
+            raise HTTPException(status.HTTP_400_BAD_REQUEST, str(exc)) from exc
+        return {"job": job_id, "execute_at": _iso(when)}
+
+    @app.get("/usage")
     async def usage(request: Request) -> dict[str, Any]:
         await require_token(request, runtime, scope=SCOPE)
         q = request.query_params
@@ -570,37 +733,66 @@ def build_app(runtime: GatewayRuntime, *, memory_root: Path | None = None) -> Fa
             "rows": groups,
         }
 
-    @app.get("/api/limits")
+    @app.get("/limits")
     async def limits(request: Request) -> dict[str, Any]:
         await require_token(request, runtime, scope=SCOPE)
         rows = await conversations.rate_limits(limit=200)
         latest: dict[str, RateLimit] = {}
+        unified: dict[str, tuple[RateLimit, dict[str, Any]]] = {}
         for row in rows:
             latest.setdefault(row.window, row)
+            for name, info in _unified_windows(row).items():
+                unified.setdefault(name, (row, info))
         now = datetime.now(UTC)
         windows = []
-        for window, row in latest.items():
+        for window in dict.fromkeys([*latest, *unified]):
-            length = WINDOWS.get(window)
+            row = latest.get(window)
-            since = (
+            seen = unified.get(window)
-                _aware(row.resets_at) - length
+            public = _limit_public(row) if row else _limit_blank(window, seen)
-                if length is not None and row.resets_at is not None
+            resets = row.resets_at if row else None
-                else _aware(row.ts)
+            if seen and _newer_figure(seen, row):
-            )
+                carrier, info = seen
+                public["utilization"] = info.get("utilization")
+                public["reported_at"] = _iso(carrier.ts)
+                resets = _unix_dt(info.get("resetsAt")) or resets
+                public["resets_at"] = _iso(resets)
+            length = _window_length(window)
+            anchor = row if row is not None else (seen[0] if seen else None)
+            if length is not None and resets is not None:
+                since = _aware(resets) - length
+            else:
+                since = _aware(anchor.ts) if anchor else now
             gateway = _sum_usage(await _usage_rows(runtime, since, now))
             gateway["since"] = since.isoformat(timespec="seconds")
-            windows.append({**_limit_public(row), "gateway": gateway})
+            known = next(
+                (
+                    r
+                    for r in rows
+                    if r.window == window
+                    and r.utilization is not None
+                    and _aware(r.ts) >= since
+                ),
+                None,
+            )
+            windows.append(
+                {
+                    **public,
+                    "gateway": gateway,
+                    "last_known": _limit_public(known) if known else None,
+                }
+            )
         windows.sort(
-            key=lambda w: (WINDOWS.get(w["window"], timedelta.max), w["window"])
+            key=lambda w: (_window_length(w["window"]) or timedelta.max, w["window"])
         )
         return {"windows": windows, "history": [_limit_public(r) for r in rows[:50]]}
 
-    @app.get("/api/memory")
+    @app.get("/memory")
     async def memory_tree(request: Request) -> dict[str, Any]:
         await require_token(request, runtime, scope=SCOPE)
         root = _memory_root(memory_root)
         return {"root": str(root), "tree": _tree(root, root, depth=0)}
 
-    @app.get("/api/memory/file")
+    @app.get("/memory/file")
     async def memory_file(request: Request) -> dict[str, Any]:
         await require_token(request, runtime, scope=SCOPE)
         root = _memory_root(memory_root)
@@ -623,7 +815,20 @@ def build_app(runtime: GatewayRuntime, *, memory_root: Path | None = None) -> Fa
             "content": content,
         }
 
-    @app.get("/api/tokens")
+    @app.get("/scopes")
+    async def scopes(request: Request) -> dict[str, Any]:
+        await require_token(request, runtime, scope=ADMIN_SCOPE)
+        by_frontend = {
+            fe.scope: fe.name or fe.path or "" for fe in runtime.frontends if fe.scope
+        }
+        return {
+            "scopes": [
+                {"scope": s, "frontend": by_frontend.get(s)}
+                for s in sorted(runtime.scopes)
+            ]
+        }
+
+    @app.get("/tokens")
     async def tokens(request: Request) -> dict[str, Any]:
         await require_token(request, runtime, scope=ADMIN_SCOPE)
         include_revoked = request.query_params.get("include_revoked") == "1"
@@ -631,13 +836,13 @@ def build_app(runtime: GatewayRuntime, *, memory_root: Path | None = None) -> Fa
             rows = await list_tokens(session, include_revoked=include_revoked)
         return {"tokens": [_token_public(t) for t in rows]}
 
-    @app.post("/api/tokens", status_code=status.HTTP_201_CREATED)
+    @app.post("/tokens", status_code=status.HTTP_201_CREATED)
     async def token_create(request: Request) -> dict[str, Any]:
         actor = await require_token(request, runtime, scope=ADMIN_SCOPE)
         data = await body_of(request)
         name = text_of(data, "name").strip()
         scope = str(data.get("scope") or "*")
-        if scope not in VALID_SCOPES:
+        if scope not in runtime.scopes:
             raise HTTPException(status.HTTP_400_BAD_REQUEST, f"invalid scope {scope!r}")
         plaintext = secrets.token_urlsafe(32)
         async with runtime.db.session() as session:
@@ -660,7 +865,7 @@ def build_app(runtime: GatewayRuntime, *, memory_root: Path | None = None) -> Fa
         )
         return {"token": _token_public(row), "plaintext": plaintext}
 
-    @app.post("/api/tokens/{token_id}/revoke")
+    @app.post("/tokens/{token_id}/revoke")
     async def token_revoke(token_id: int, request: Request) -> dict[str, Any]:
         actor = await require_token(request, runtime, scope=ADMIN_SCOPE)
         async with runtime.db.session() as session:
@@ -675,7 +880,7 @@ def build_app(runtime: GatewayRuntime, *, memory_root: Path | None = None) -> Fa
         )
         return {"id": token_id, "revoked": True}
 
-    @app.get("/api/audit")
+    @app.get("/audit")
     async def audit_list(request: Request) -> dict[str, Any]:
         await require_token(request, runtime, scope=ADMIN_SCOPE)
         before_raw = request.query_params.get("before")
@@ -859,6 +1064,72 @@ async def _conversation_titles(
     }
 
 
+def _queue_item(item: InjectQueueItem | None) -> dict[str, Any] | None:
+    if item is None:
+        return None
+    return {
+        "id": item.id,
+        "priority": item.priority,
+        "origin": item.origin,
+        "status": item.status,
+        "created_at": _iso(item.created_at),
+        "text": item.text[:200],
+    }
+
+
+def _window_length(name: str) -> timedelta | None:
+    if name.startswith("five_hour"):
+        return timedelta(hours=5)
+    if "seven_day" in name:
+        return timedelta(days=7)
+    return WINDOWS.get(name)
+
+
+def _unix_dt(value: Any) -> datetime | None:
+    if isinstance(value, int | float) and value > 0:
+        return datetime.fromtimestamp(value, tz=UTC)
+    return None
+
+
+def _unified_windows(row: RateLimit) -> dict[str, dict[str, Any]]:
+    """Every window the event carried a figure for, not just the one it was about."""
+    raw = row.raw if isinstance(row.raw, dict) else {}
+    found = raw.get("unifiedWindows")
+    if not isinstance(found, dict):
+        return {}
+    return {
+        str(name): info
+        for name, info in found.items()
+        if isinstance(info, dict) and info.get("utilization") is not None
+    }
+
+
+def _newer_figure(
+    seen: tuple[RateLimit, dict[str, Any]], row: RateLimit | None
+) -> bool:
+    if row is None or row.utilization is None:
+        return True
+    return seen[0].id != row.id and _aware(seen[0].ts) > _aware(row.ts)
+
+
+def _limit_blank(
+    window: str, seen: tuple[RateLimit, dict[str, Any]] | None
+) -> dict[str, Any]:
+    carrier = seen[0] if seen else None
+    return {
+        "id": None,
+        "ts": _iso(carrier.ts) if carrier else None,
+        "window": window,
+        "status": "allowed",
+        "utilization": None,
+        "resets_at": None,
+        "overage_status": None,
+        "overage_resets_at": None,
+        "agent": carrier.agent_name if carrier else None,
+        "session_id": carrier.session_id if carrier else None,
+    }
+
+
 def _limit_public(row: RateLimit) -> dict[str, Any]:
     return {
         "id": row.id,
@@ -908,6 +1179,35 @@ def _memory_path(root: Path, raw: str) -> Path:
     return target
 
 
+def _grep_memory(root: Path, query: str, *, limit: int) -> list[dict[str, Any]]:
+    needle = query.casefold()
+    hits: list[dict[str, Any]] = []
+    for path in sorted(root.rglob("*")):
+        if len(hits) >= limit:
+            break
+        if not path.is_file() or any(part.startswith(".") for part in path.parts):
+            continue
+        if path.suffix not in (".md", ".txt", ".json", ".yaml", ".yml"):
+            continue
+        try:
+            if path.stat().st_size > MEMORY_MAX_FILE:
+                continue
+            text = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        rel = str(path.relative_to(root))
+        if needle in rel.casefold():
+            hits.append({"path": rel, "line": 0, "snippet": ""})
+            continue
+        for number, line in enumerate(text.splitlines(), 1):
+            if needle in line.casefold():
+                hits.append(
+                    {"path": rel, "line": number, "snippet": line.strip()[:SNIPPET_MAX]}
+                )
+                break
+    return hits
+
+
 def _tree(root: Path, directory: Path, *, depth: int) -> list[dict[str, Any]]:
     if depth > MEMORY_MAX_DEPTH:
         return []

src/beaver_gateway/frontends/base.py

@@ -1,11 +1,7 @@
-"""Frontend ABC + the runtime context handed to ``configure``.
+"""Frontend ABC and the runtime context handed to ``configure``.
 
-A frontend is anything that listens on a port and routes inbound traffic
+A frontend routes inbound traffic into the gateway (an HTTP mount, a
-into the gateway. ``GatewayRuntime`` carries everything a frontend may
+poller, or both); ``GatewayRuntime`` carries the built state each needs.
-need that isn't user-config: built registries, per-agent backends, and
-the in-memory token store. The user's ``/config/config.py`` defines a
-``Gateway`` (lists); ``cli.main`` turns that into a ``GatewayRuntime``
-and hands it to each frontend's ``configure``.
 """
 
 from __future__ import annotations
@@ -14,14 +10,20 @@ from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any
 
+from beaver_gateway.frontends.files import SendFileError
+from beaver_gateway.security.auth import BUILTIN_SCOPES
+
 if TYPE_CHECKING:
     from collections.abc import Awaitable, Callable, Mapping, Sequence
+    from pathlib import Path
 
+    from starlette.types import ASGIApp
+
+    from beaver_gateway.app import AgentRegistry, McpRegistry
     from beaver_gateway.backends.base import Backend
-    from beaver_gateway.core.auth import TokenStore
+    from beaver_gateway.conversations.kinds import Kind
-    from beaver_gateway.core.kinds import Kind
+    from beaver_gateway.frontends.turn_record import TurnRecord
-    from beaver_gateway.core.registry import AgentRegistry, McpRegistry
+    from beaver_gateway.security.auth import TokenStore
-    from beaver_gateway.core.turn_record import TurnRecord
     from beaver_gateway.storage import Database
     from beaver_gateway.storage.models import Conversation, ConversationBinding
 
@@ -32,20 +34,8 @@ if TYPE_CHECKING:
 class GatewayRuntime:
     """Post-build state of the gateway, shared with every frontend.
 
-    Backends are keyed by **agent name**, not type — one ``RaycastBackend``
+    Backends are keyed by agent name, not type: one backend instance may
-    instance can serve many ``RaycastAgent`` instances, but the lookup
+    serve several agents, so the indirection lives at lookup time.
-    site (an inbound request with ``model=<agent.name>``) already has
-    the name in hand, so the indirection lives one step earlier.
-
-    ``mcp_internal_urls`` is filled in Phase 2.1: one loopback URL per
-    declared ``McpServer`` so ``ClaudeSdkBackend``
-    can pass them to ``BackendOptions.mcp_servers`` without re-running
-    discovery.
-
-    ``db`` (Phase 4.1) is the shared :class:`Database` handle. Phase 4.2
-    will switch ``TokenStore`` to read from it; Phase 4.3 admin/audit
-    write through it. Phase 4.1 only attaches it — existing frontends
-    ignore it.
     """
 
     agents: AgentRegistry
@@ -54,64 +44,85 @@ class GatewayRuntime:
     token_store: TokenStore
     db: Database
     mcp_internal_urls: Mapping[str, str] = field(default_factory=dict)
-    # Phase 4.3 — AdminFrontend reads creds + cookie-signing key from
-    # the runtime so the user's ``config.py`` doesn't have to know
-    # anything about env wiring. Defaulted to empty so existing tests /
-    # call sites that don't touch the admin path keep building; the
-    # admin frontend ``configure()`` itself rejects empty values.
     admin_user: str = ""
+    """Operator login for the admin console, checked by ``AdminFrontend``."""
     admin_pass: str = ""
     session_secret: str = ""
-    # The full sibling-frontends list, in declaration order. AdminFrontend
-    # uses it to advertise concrete bearer-endpoint URLs (host/port) on
-    # the dashboard so the operator can copy ready-to-use links / curl
-    # snippets. Other frontends ignore it.
     frontends: Sequence[Frontend] = field(default_factory=tuple)
-    # Frontends that finish a turn (Anthropic Messages, Markdown) iterate
+    """Every frontend in declaration order, for advertising their URLs."""
-    # this list and ``await`` each handler with a ``TurnRecord``. Handlers
-    # are appended during ``configure()`` by frontends that want a
-    # cross-frontend chat archive — currently the markdown frontend's
-    # ``log_all_chats`` mode. Handler exceptions are caught at the call
-    # site; they never block the user-visible response.
-    #
-    # The field is typed as ``list[Any]`` rather than the precise
-    # ``list[TurnLogHandler]`` because the alias lives under TYPE_CHECKING
-    # to keep ``anthropic.types`` out of the runtime import graph for
-    # this base module.
     turn_log_handlers: list[TurnLogHandler] = field(default_factory=list)
-    # M1b: conversations service, event bus and the shared session pool.
+    """Called with a ``TurnRecord`` after each turn; failures never reach the user."""
-    # ``Any`` for the same import-graph reason as above; ``None`` only in
-    # tests that build a runtime without them.
     conversations: Any = None
     bus: Any = None
     pool: Any = None
+    scheduler: Any = None
+    public_url: str | None = None
+    """``Gateway.public_url``; ``None`` derives the origin from the request."""
+    scopes: frozenset[str] = BUILTIN_SCOPES
+    """Every token scope this gateway knows: the builtins plus each frontend's."""
+    send_file_roots: tuple[Path, ...] = ()
+    """Directories ``send_file`` may read, from ``SEND_FILE_ROOTS``."""
 
 
 class Frontend(ABC):
-    """Listens on a port, dispatches into the gateway.
+    """Routes inbound traffic into the gateway.
+
+    HTTP frontends set ``path`` and return their ASGI app from ``app()``;
+    these are mounted under that path on the one gateway port. ``serve()``
+    is for non-HTTP work (polling, vault mirrors) and defaults to nothing.
+    ``landing`` marks the app that ``/`` redirects to.
+
+    ``scope`` is the token scope this frontend's routes are gated by; a
+    frontend that names its own scope gets keys nobody else's token opens,
+    and ``POST /api/tokens`` will mint them (see ``security/auth.py``).
 
     A frontend that shows conversations declares ``name`` (the binding
-    key) and ``kinds`` (which conversation kinds it shows);
+    key) and ``kinds`` (which conversation kinds it shows). The first
-    ``core/conversations`` refuses to bind a conversation to a frontend
+    frontend whose ``materialize`` returns a binding is the *home* of
-    outside its declaration. The first frontend in declaration order
+    that kind, used by ``spawn`` for new conversations; ``agent_for``
-    whose ``materialize`` returns a binding is the *home* of that kind:
+    names the default agent for a kind. Stateless frontends (MCP, admin)
-    ``spawn`` calls it so a new conversation gets a window (a vault file,
+    leave these at their defaults.
-    a Telegram topic). ``agent_for`` names the default agent for a kind
-    so callers may omit ``agent``. Stateless frontends (MCP, admin) keep
-    the defaults and stay outside the routing.
     """
 
     name: str = ""
     kinds: tuple[Kind, ...] = ()
+    path: str | None = None
+    landing: bool = False
+    scope: str | None = None
+    sends_files: bool = False
+    """Whether ``send_file`` reaches a human through this frontend."""
 
     @abstractmethod
     def configure(self, runtime: GatewayRuntime) -> None: ...
 
-    @abstractmethod
+    def app(self) -> ASGIApp | None:
-    async def serve(self) -> None: ...
+        return None
+
+    async def serve(self) -> None:
+        return
 
     def agent_for(self, kind: Kind) -> str | None:  # noqa: ARG002
         return None
 
     async def materialize(self, conv: Conversation) -> ConversationBinding | None:  # noqa: ARG002
         return None
+
+    async def mark_closed(self, conv: Conversation) -> bool:  # noqa: ARG002
+        """Show in the window that the conversation is over (a renamed topic)."""
+        return False
+
+    async def send_file(
+        self,
+        conv: Conversation,  # noqa: ARG002
+        path: str,  # noqa: ARG002
+        *,
+        caption: str = "",  # noqa: ARG002
+        method: str = "auto",  # noqa: ARG002
+    ) -> str:
+        """Put a file in this conversation's window; the answer goes to the model."""
+        msg = f"frontend {self.name!r} cannot send files"
+        raise SendFileError(msg)
+
+    def file_note(self) -> str:
+        """Roots and ceiling, for the tool description the model reads."""
+        return ""

src/beaver_gateway/frontends/bearer.py

@@ -1,8 +1,7 @@
 """Shared bearer-token verification for HTTP frontends.
 
-Extracted from ``AnthropicMessagesFrontend`` so the markdown frontend
+Reused by every bearer-protected frontend instead of duplicating the
-(and any future bearer-protected frontend) can reuse one canonical
+header-parsing logic.
-verifier instead of copy-pasting the header-parsing dance.
 """
 
 from __future__ import annotations
@@ -23,22 +22,21 @@ __all__ = ["require_token"]
 async def require_token(
     request: Request, runtime: GatewayRuntime, *, scope: str
 ) -> str:
-    """Verify the request's bearer + scope, return the token's audit name.
+    """Verify the request's bearer token and scope; return its audit name.
 
-    Accepts both ``X-Api-Key: <token>`` (Anthropic SDK / LibreChat) and
+    Checks ``X-Api-Key``, then ``Authorization: Bearer``, then ``?token=``.
-    ``Authorization: Bearer <token>`` (curl, Cursor). 401 on missing /
+    401 on a missing/unknown token, 403 if the token's scope doesn't cover
-    unknown token; 403 on a known token whose scope doesn't cover
+    ``scope``. Bootstrap tokens carry ``"*"`` and pass every scope check.
-    ``scope``. Bootstrap tokens implicitly carry ``"*"`` and pass every
-    scope check.
     """
     api_key = request.headers.get("x-api-key")
-    identity = (
+    authorization = request.headers.get("authorization")
-        await runtime.token_store.verify(api_key)
+    if api_key:
-        if api_key
+        identity = await runtime.token_store.verify(api_key)
-        else await runtime.token_store.verify_bearer(
+    elif authorization:
-            request.headers.get("authorization")
+        identity = await runtime.token_store.verify_bearer(authorization)
-        )
+    else:
-    )
+        qs_token = request.query_params.get("token")
+        identity = await runtime.token_store.verify(qs_token) if qs_token else None
     if identity is None:
         raise HTTPException(
             status.HTTP_401_UNAUTHORIZED,

src/beaver_gateway/frontends/files.py

@@ -0,0 +1,95 @@
+"""What an agent may hand to a human: an allowed path, a ceiling, a method.
+
+The ceiling and the method names belong to the frontend's API; the check
+lives here so every frontend refuses the same way, in words the model reads.
+"""
+
+from __future__ import annotations
+
+import mimetypes
+from dataclasses import dataclass, replace
+from pathlib import Path
+
+__all__ = ["AUTO", "DEFAULTS", "METHODS", "SendFileError", "SendFiles", "method_for"]
+
+AUTO = "auto"
+METHODS = ("document", "photo", "audio", "voice", "video", "video_note", "animation")
+
+_BY_SUFFIX = {
+    ".jpg": "photo",
+    ".jpeg": "photo",
+    ".png": "photo",
+    ".webp": "photo",
+    ".gif": "animation",
+    ".mp3": "audio",
+    ".flac": "audio",
+    ".m4a": "audio",
+    ".wav": "audio",
+    ".aac": "audio",
+    ".ogg": "voice",
+    ".oga": "voice",
+    ".opus": "voice",
+    ".mp4": "video",
+    ".m4v": "video",
+    ".mov": "video",
+}
+_BY_TYPE = {"image": "photo", "audio": "audio", "video": "video"}
+
+
+class SendFileError(Exception):
+    """Why a file was not sent, worded for the model that asked."""
+
+
+@dataclass(frozen=True, slots=True)
+class SendFiles:
+    """Which files a frontend accepts from an agent and how big they may be."""
+
+    roots: tuple[Path, ...] = ()
+    """Directories a path must resolve inside; nothing outside is sendable."""
+    max_bytes: int = 50 * 1024 * 1024
+    """Upload ceiling of the API behind the frontend; the Bot API gives 50 MB."""
+
+    def with_roots(self, *roots: Path) -> SendFiles:
+        return replace(self, roots=tuple(dict.fromkeys((*self.roots, *roots))))
+
+    @property
+    def note(self) -> str:
+        """Roots and ceiling as one line for the tool description."""
+        where = ", ".join(str(r) for r in self.roots) or "none, so nothing is sendable"
+        return f"paths under {where}, up to {mb(self.max_bytes)} MB"
+
+    def resolve(self, raw: str) -> Path:
+        path = Path(raw.strip()).expanduser().resolve()
+        if not any(path.is_relative_to(r.expanduser().resolve()) for r in self.roots):
+            msg = f"{path} is outside the allowed roots ({self.note}); copy it there"
+            raise SendFileError(msg)
+        if not path.is_file():
+            msg = f"{path} is not a file"
+            raise SendFileError(msg)
+        size = path.stat().st_size
+        if size > self.max_bytes:
+            msg = (
+                f"{path.name} is {mb(size)} MB, over the {mb(self.max_bytes)} MB limit"
+            )
+            raise SendFileError(msg)
+        return path
+
+
+DEFAULTS = SendFiles()
+
+
+def method_for(path: Path, method: str = AUTO) -> str:
+    if method and method != AUTO:
+        if method not in METHODS:
+            msg = f"unknown method {method!r}; one of: {', '.join((AUTO, *METHODS))}"
+            raise SendFileError(msg)
+        return method
+    guessed = _BY_SUFFIX.get(path.suffix.lower())
+    if guessed:
+        return guessed
+    mime, _ = mimetypes.guess_type(path.name)
+    return _BY_TYPE.get(mime.split("/")[0], "document") if mime else "document"
+
+
+def mb(size: int) -> str:
+    return f"{round(size / 1024 / 1024, 2):g}"

src/beaver_gateway/frontends/markdown/__init__.py

@@ -1,13 +1,7 @@
-"""Markdown frontend — turn-by-turn chat archive backed by ``.md`` files.
+"""Markdown frontend — chat archive backed by ``.md`` files in an Obsidian vault.
 
-The user maintains chats as plain markdown files in an Obsidian vault.
+An Obsidian plugin POSTs ``{filename, content?}`` to ``/chat``; the
-A plugin in Obsidian POSTs ``{filename, content?}`` to ``/chat`` and the
+frontend runs the agent on a trailing user turn and appends the reply.
-frontend parses the file, finds the last turn, and runs the agent if
-the last turn is ``user``. The full response is appended back to the
-file as an ``### Assistant:`` turn. With ``log_all_chats=True`` the
-frontend also subscribes to every other frontend's turns and writes
-them into ``{vault_path}/{logged_subdir}/`` so the vault is the single
-chronological archive of all conversations.
 """
 
 from beaver_gateway.frontends.markdown.frontend import MarkdownFrontend

src/beaver_gateway/frontends/markdown/crossfront.py

@@ -1,17 +1,7 @@
 """Cross-frontend chat logger.
 
-When ``MarkdownFrontend(log_all_chats=True)`` is configured, every turn
+Mirrors turns completed by other frontends into the vault as ``.md``
-completed by any other frontend (currently the Anthropic Messages
+files, matching a conversation's continuation by content-hash fingerprint.
-frontend) is mirrored into the vault as a ``.md`` file. Subsequent
-turns of the same conversation append to the same file — matched by a
-content-hash fingerprint stored in YAML frontmatter.
-
-The fingerprint hashes the message history *before* the new assistant
-reply. So the next request's input history (which now includes the
-prior assistant reply) hashes to the value we just persisted —
-``hash(prev_input + [assistant_reply])`` — and the lookup hits the
-same file. New conversations (no prior fingerprint match) get a fresh
-file under ``{vault_path}/{logged_subdir}/{agent_name}/``.
 """
 
 from __future__ import annotations
@@ -32,7 +22,7 @@ if TYPE_CHECKING:
 
     from anthropic.types import MessageParam
 
-    from beaver_gateway.core.turn_record import TurnRecord
+    from beaver_gateway.frontends.turn_record import TurnRecord
 
 
 _log = logging.getLogger("beaver_gateway.frontends.markdown.crossfront")
@@ -53,12 +43,8 @@ vault. ``None`` keeps ``{vault}/{logged_subdir}/{agent}/{YYYY-MM-DD}_{slug}.md``
 def fingerprint_messages(messages: Iterable[MessageParam]) -> str:
     """Stable, short hex hash of a conversation prefix.
 
-    Built from ``(role, normalized_content)`` pairs only — so the
+    Hashes ``(role, text-only content)`` pairs so differently-shaped message
-    Markdown frontend's parser-shaped messages (text-only) and the
+    histories that carry the same text still fingerprint identically.
-    Anthropic frontend's raw ``messages`` payload (which may also be
-    string-only at v1) hash compatibly when they represent the same
-    conversation. Tool blocks / images would diverge, but those aren't
-    in the v1 ingest path.
     """
     h = hashlib.sha1(usedforsecurity=False)
     for msg in messages:
@@ -85,12 +71,8 @@ def fingerprint_messages(messages: Iterable[MessageParam]) -> str:
 class CrossFrontendLogger:
     """Maintains the fingerprint→file map and writes turns to disk.
 
-    The map is in-process; on startup ``warm_index`` rebuilds it from
+    The map is in-process, rebuilt by ``warm_index`` on startup; all disk
-    YAML frontmatter of every file under ``logged_subdir``. A miss
+    writes funnel through one lock to sidestep races.
-    creates a new file, a hit appends to the existing one. All disk
-    work funnels through one ``asyncio.Lock`` because the writes are
-    cheap and serializing them sidesteps a class of races we don't need
-    to think about.
     """
 
     def __init__(
@@ -105,20 +87,13 @@ class CrossFrontendLogger:
         self._index: dict[str, Path] = {}
         self._lock = asyncio.Lock()
         self._chat_path_fn = chat_path
-        # When the user supplies a custom path function, files can land
-        # anywhere in the vault — so we have to scan the whole vault on
-        # startup to rebuild the fingerprint→path map. With the default
-        # layout we can bound the scan to ``_logs/``.
         self._scan_root = vault_path if chat_path is not None else self._root
 
     def warm_index(self) -> None:
         """Scan logged files synchronously, populating the fingerprint map.
 
-        Called from ``MarkdownFrontend.configure`` so the map is ready
+        Called before any cross-frontend turn arrives; a custom ``chat_path``
-        before any cross-frontend turn arrives. ``frontmatter.load``
+        forces a full-vault walk instead of scanning just ``logged_subdir``.
-        reads only enough of the file to parse the YAML head, so the
-        scan is cheap even on large vaults — but a custom ``log_path``
-        forces a full-vault walk; mention that in the constructor doc.
         """
         if not self._scan_root.exists():
             return
@@ -140,29 +115,19 @@ class CrossFrontendLogger:
     async def handle(self, record: TurnRecord) -> None:
         """Append or create a logged file for ``record``.
 
-        Records that the markdown frontend itself produced
+        Skips ``source == "markdown"`` records (already on disk); matches
-        (``source=="markdown"``) are skipped — those already live in the
+        the target file by fingerprinting ``input_messages`` sans the new turn.
-        user's hand-written file and shouldn't be duplicated into the
-        ``_logs`` shadow tree.
         """
         if record.source == "markdown":
             return
 
         async with self._lock:
-            # ``input_messages`` is the *full* history sent to the backend
-            # (last entry is the new user turn). Match against the prefix
-            # that excludes the new user turn — that's what the previous
-            # write stored as its fingerprint. Empty prefix is the
-            # well-known "brand new chat" sentinel.
             prefix = record.input_messages[:-1]
             prev_fp = fingerprint_messages(prefix) if prefix else None
             target = self._index.get(prev_fp) if prev_fp else None
             if target is None:
                 target = self._new_file_path(record)
 
-            # Build the full history including the assistant reply; the
-            # new fingerprint matches *that* prefix, so the next user
-            # turn (history grows by one user msg) will hit this file.
             assistant_msg: MessageParam = {
                 "role": "assistant",
                 "content": _flatten_text(record.output_message),
@@ -174,9 +139,6 @@ class CrossFrontendLogger:
                 existing = target.read_text(encoding="utf-8")
                 parsed = frontmatter.loads(existing)
                 body = strip_trailing_user_scaffold(parsed.content)
-                # We append only the *new* user turn (the last one in
-                # input_messages, since prior turns are already on disk)
-                # plus the assistant reply.
                 new_user = record.input_messages[-1]
                 new_block = renderer.render_user_param(new_user)
                 new_block = renderer.append_to_body(
@@ -185,7 +147,6 @@ class CrossFrontendLogger:
                 new_body = renderer.append_to_body(body, new_block)
                 metadata = dict(parsed.metadata)
             else:
-                # Materialize the whole conversation from scratch.
                 new_body = _render_full_history(
                     record.input_messages, record.output_message
                 )
@@ -197,21 +158,15 @@ class CrossFrontendLogger:
             metadata["fingerprint"] = new_fp
             metadata["source"] = record.source
             self._write(target, metadata, new_body)
-            # Maintain the index: drop the old fp (it's stale once we
-            # write the new turn), add the new one.
             if prev_fp:
                 self._index.pop(prev_fp, None)
             self._index[new_fp] = target
 
-    # ---- internals -----------------------------------------------------
-
     def _new_file_path(self, record: TurnRecord) -> Path:
         """Pick a fresh filename for a brand-new conversation.
 
-        With a user-supplied ``chat_path`` we delegate to it (joining a
+        Delegates to ``chat_path`` if set; otherwise
-        relative result with the vault root). Without one, we fall back
+        ``{logged_subdir}/{agent}/{date}_{hex8}.md``.
-        to ``{logged_subdir}/{agent}/{date}_{hex8}.md`` and ensure the
-        ``.md`` suffix in case the user picks a non-md extension by hand.
         """
         if self._chat_path_fn is not None:
             result = self._chat_path_fn(
@@ -224,8 +179,6 @@ class CrossFrontendLogger:
             result.parent.mkdir(parents=True, exist_ok=True)
             return result
         day = datetime.now(UTC).strftime("%Y-%m-%d")
-        # Short hex from the input hash so two same-day chats sort
-        # stably and don't collide.
         salt = fingerprint_messages(record.input_messages)[:8]
         agent_dir = self._root / record.agent_name
         agent_dir.mkdir(parents=True, exist_ok=True)
@@ -238,9 +191,6 @@ class CrossFrontendLogger:
             text = frontmatter.dumps(post) + "\n"
         else:
             text = body if body.endswith("\n") else body + "\n"
-        # Sync write inside the lock — keeps the implementation tiny;
-        # individual logged turns are small enough that the blocking
-        # write doesn't matter at human conversation rates.
         path.write_text(text, encoding="utf-8")
 
 
@@ -277,18 +227,13 @@ def _render_full_history(messages: list[MessageParam], assistant: Any) -> str:
 def strip_trailing_user_scaffold(body: str) -> str:
     """Drop a trailing empty ``### User:`` block if present.
 
-    Cross-frontend turns aren't typed into the file by the human — they
+    Avoids leaving two ``### User:`` headers in a row when appending a
-    arrive whole from another frontend. If we leave the previous run's
+    turn that wasn't typed into the file by hand.
-    scaffold in place, we'd write the new user turn right after an
-    empty marker (visual noise, two ``### User:`` headers in a row).
-    Trim it and let the append flow add a fresh scaffold at the end.
     """
     stripped = body.rstrip()
     marker = "### User:"
     if not stripped.endswith(marker):
         return body
-    # Walk back: the scaffold is the marker preceded by either start-of-file
-    # or an HR/blank line. Find the last newline before the marker, cut.
     head = stripped[: -len(marker)].rstrip()
     if head.endswith("---"):
         head = head[: -len("---")].rstrip()

src/beaver_gateway/frontends/markdown/frontend.py

@@ -1,40 +1,11 @@
 """``MarkdownFrontend`` — chat-via-markdown-files frontend.
 
-Wires:
+``POST /chat`` (and SSE ``/chat/stream``) parses the vault file, runs
-
+the agent on the trailing user turn, and appends the reply.
-* ``POST /chat {filename, content?, agent?}`` — bearer-authenticated
-  trigger. The plugin in Obsidian fires this after the user edits a
-  ``.md`` and the file gets synced (or with ``content`` to short-circuit
-  the sync delay). We parse the file, check the last turn — assistant
-  → no-op, user → run the agent and append.
-* ``GET /healthz`` — liveness.
-
-Concurrency model: an in-memory ``set[Path]`` of files currently in
-flight. Two concurrent requests for the same file → the second gets
-409. The set is single-process (one gateway instance) — that's by
-design; the markdown frontend is the only writer in its vault from
-the gateway side. The turn itself runs through ``core/conversations``
-(one turn per conversation, ``running_turn`` in the DB), so a message
-posted to the same conversation via ``/api`` waits its turn.
-
-A chat file is a ``deep`` conversation bound as
-``(markdown, <vault-relative path>)``; frontmatter carries only ``agent``
-and ``conversation_id`` (§3.10), tool calls are never rendered. The
-frontend is the home of ``deep``: ``materialize`` gives a conversation
-spawned elsewhere its file, and :class:`.mirror.ChatMirror` keeps that
-file in step with replies produced outside ``/chat``.
-
-Cross-frontend logging: when ``log_all_chats=True``, ``configure()``
-registers a handler on ``runtime.turn_log_handlers`` so every other
-frontend's completed turns also land in the vault. The handler logic
-lives in :mod:`.crossfront` so this module stays focused on the HTTP
-shape.
 """
 
 from __future__ import annotations
 
-import asyncio
-import contextlib
 import json
 import logging
 import time
@@ -47,23 +18,10 @@ from fastapi import FastAPI, HTTPException, Request, status
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import JSONResponse, StreamingResponse
 
-from beaver_gateway.core import audit
+from beaver_gateway.backends.capture import TurnCapture
-from beaver_gateway.core.conversation_store import (
+from beaver_gateway.frontends.accumulate import StreamAccumulator
-    diff_and_fork,
-    load_messages,
-    rewrite_messages,
-)
-from beaver_gateway.core.turn_capture import TurnCapture
-from beaver_gateway.core.turn_record import TurnRecord
-from beaver_gateway.frontends._accumulate import StreamAccumulator
-from beaver_gateway.frontends._auth import require_token
-from beaver_gateway.frontends._sse import (
-    KEEPALIVE,
-    SSE_HEADERS,
-    events_with_heartbeat,
-    sse_pack,
-)
 from beaver_gateway.frontends.base import Frontend
+from beaver_gateway.frontends.bearer import require_token
 from beaver_gateway.frontends.markdown import parser, renderer
 from beaver_gateway.frontends.markdown.crossfront import CrossFrontendLogger
 from beaver_gateway.frontends.markdown.files import (
@@ -71,12 +29,25 @@ from beaver_gateway.frontends.markdown.files import (
     reattach_frontmatter,
     write_atomic,
 )
+from beaver_gateway.frontends.markdown.history import (
+    diff_and_fork,
+    load_messages,
+    rewrite_messages,
+)
 from beaver_gateway.frontends.markdown.mirror import FRONTEND, ChatMirror
+from beaver_gateway.frontends.sse import (
+    KEEPALIVE,
+    SSE_HEADERS,
+    events_with_heartbeat,
+    sse_pack,
+)
+from beaver_gateway.frontends.turn_record import TurnRecord
+from beaver_gateway.security import audit
 
 if TYPE_CHECKING:
     from collections.abc import AsyncIterator, Callable
 
-    from beaver_gateway.core.kinds import Kind
+    from beaver_gateway.conversations.kinds import Kind
     from beaver_gateway.frontends.base import GatewayRuntime
     from beaver_gateway.storage.models import Conversation, ConversationBinding
 
@@ -87,57 +58,43 @@ _log = logging.getLogger("beaver_gateway.frontends.markdown")
 __all__ = ["MarkdownFrontend"]
 
 
-# How often we re-render the assistant turn into the .md file while the
-# backend stream is still open. Trades responsiveness (faster updates to
-# Obsidian sync / Raycast tailers) against write amplification. Each
-# ``RawContentBlockStopEvent`` also forces a flush regardless of the
-# timer, so block boundaries always land in the file.
 _STREAM_FLUSH_DEBOUNCE = 0.4
 
-# Debounce for the SSE ``/chat/stream`` path. Network IO is cheaper than
-# atomic file rewrites, so we send updates more frequently — the client
-# wants the lowest possible latency and we control the renderer on the
-# other end (the Obsidian plugin splices deltas into the editor, no
-# disk round-trip).
 _SSE_FLUSH_DEBOUNCE = 0.1
 
 
 class MarkdownFrontend(Frontend):
-    """FastAPI app behind ``POST /chat`` driven by Obsidian-vault files."""
+    """FastAPI app behind ``POST /chat`` driven by Obsidian-vault files.
+
+    ``_busy`` tracks in-flight files; check-and-add must stay atomic (no
+    ``await`` between them) so concurrent requests reliably lose to 409.
+    """
 
     name = FRONTEND
     kinds = ("deep",)
+    path = "/md"
 
     def __init__(
         self,
         *,
         vault_path: Path | str,
-        host: str = "0.0.0.0",  # noqa: S104
-        port: int = 8003,
         default_agent: str | None = None,
         log_all_chats: bool = False,
         logged_subdir: str = "_logs",
         chat_path: Callable[[str, str, Path], Path] | None = None,
-        public_base_url: str | None = None,
     ) -> None:
+        """Configure the vault-backed frontend.
+
+        ``chat_path``, if given, overrides where new chat files are created;
+        ``logged_subdir`` holds cross-frontend logs when ``log_all_chats`` is set.
+        """
         self.vault_path = Path(vault_path).expanduser().resolve()
-        self.host = host
-        self.port = port
         self.default_agent = default_agent
         self.log_all_chats = log_all_chats
         self.logged_subdir = logged_subdir
         self.chat_path = chat_path
-        # External URL prefix when behind a reverse proxy — same role as
-        # on the other bearer frontends. Trailing slash trimmed for
-        # idempotent concatenation; ``None`` means "no proxy / advertise
-        # raw host:port".
-        self.public_base_url = public_base_url.rstrip("/") if public_base_url else None
         self._runtime: GatewayRuntime | None = None
         self._app: FastAPI | None = None
-        # Files currently being processed by an in-flight ``POST /chat``.
-        # Checked-and-added atomically in the request handler (no
-        # ``await`` between the check and the insert) so a concurrent
-        # request reliably loses the race to 409.
         self._busy: set[Path] = set()
         self._crossfront: CrossFrontendLogger | None = None
         self._mirror: ChatMirror | None = None
@@ -160,9 +117,6 @@ class MarkdownFrontend(Frontend):
                 logged_subdir=self.logged_subdir,
                 chat_path=self.chat_path,
             )
-            # Scan the existing logged files synchronously here so the
-            # fingerprint→path map is populated before the first
-            # cross-frontend turn arrives. Cheap: frontmatter-only read.
             self._crossfront.warm_index()
             runtime.turn_log_handlers.append(self._crossfront.handle)
         self._app = self._build_app(runtime)
@@ -180,34 +134,16 @@ class MarkdownFrontend(Frontend):
     async def materialize(self, conv: Conversation) -> ConversationBinding | None:
         return await self.mirror.materialize(conv)
 
+    def app(self) -> FastAPI | None:
+        return self._app
+
     async def serve(self) -> None:
-        import uvicorn
+        await self.mirror.run()
-
-        if self._app is None:
-            msg = "configure() must be called before serve()"
-            raise RuntimeError(msg)
-        config = uvicorn.Config(
-            self._app, host=self.host, port=self.port, log_level="info"
-        )
-        server = uvicorn.Server(config)
-        mirror = asyncio.create_task(self.mirror.run())
-        try:
-            await server.serve()
-        finally:
-            mirror.cancel()
-            with contextlib.suppress(asyncio.CancelledError):
-                await mirror
-
-    # ---- app builder ---------------------------------------------------
 
     def _build_app(self, runtime: GatewayRuntime) -> FastAPI:
+        """CORS is wide open here since auth is bearer-token, not cookie-based."""
         app = FastAPI(title="beaver-gateway / Markdown")
 
-        # ``/chat/stream`` is consumed via ``fetch`` from the Obsidian
-        # plugin (``requestUrl`` can't read a body incrementally), and
-        # ``fetch`` is subject to CORS. Auth is bearer-token so we don't
-        # need credentialed mode; allow any origin and the standard
-        # methods/headers. The other endpoints are happy to ride along.
         app.add_middleware(
             CORSMiddleware,
             allow_origins=["*"],
@@ -249,8 +185,6 @@ class MarkdownFrontend(Frontend):
 
             file_path = self._resolve_path(filename)
 
-            # Atomic check-and-claim: both ops run between awaits, so a
-            # second request can't slip into the same file slot.
             if file_path in self._busy:
                 return JSONResponse(
                     status_code=status.HTTP_409_CONFLICT,
@@ -271,12 +205,10 @@ class MarkdownFrontend(Frontend):
 
         @app.post("/chat/stream")
         async def chat_stream(request: Request) -> Any:
-            # Same contract as ``/chat`` (bearer auth, identical body),
+            """SSE variant of ``/chat``: ``delta`` events, one disk write at the end.
-            # but the response is ``text/event-stream`` and intermediate
+
-            # rendered states are pushed as ``delta`` events. The
+            The 409-conflict response is still plain JSON — the stream hasn't started.
-            # gateway-side disk write only happens once, at end of turn,
+            """
-            # so streaming consumers (Obsidian plugin) and Obsidian Sync
-            # don't fight over the same file mid-stream.
             token_name = await require_token(request, runtime, scope="messages")
             try:
                 body = await request.json()
@@ -299,8 +231,6 @@ class MarkdownFrontend(Frontend):
 
             file_path = self._resolve_path(filename)
 
-            # 409 path stays JSON — the stream hasn't started yet, so
-            # the caller can read it the same way as on ``/chat``.
             if file_path in self._busy:
                 return JSONResponse(
                     status_code=status.HTTP_409_CONFLICT,
@@ -328,8 +258,6 @@ class MarkdownFrontend(Frontend):
 
         return app
 
-    # ---- dispatch ------------------------------------------------------
-
     async def _handle_chat(
         self,
         *,
@@ -340,6 +268,7 @@ class MarkdownFrontend(Frontend):
         content_override: Any,
         agent_override: str | None,
     ) -> Any:
+        """Non-streaming ``/chat`` handler: parse, align, run, persist."""
         write_disk = content_override is None
         if isinstance(content_override, str):
             file_text = content_override
@@ -363,8 +292,6 @@ class MarkdownFrontend(Frontend):
                 "or configure `default_agent`",
             )
 
-            # When the parser produced no messages (file empty / only
-            # frontmatter), there's nothing to dispatch.
         if not parsed.messages:
             return {
                 "status": "nothing_to_do",
@@ -407,14 +334,12 @@ class MarkdownFrontend(Frontend):
             msgs=len(parsed.messages),
         )
 
-        # Resolve / mint the conversation row, align incoming against
-        # stored history, and feed the aligned messages to the backend
-        # - see ``core/conversation_store.py`` for the full rationale.
         conv, conv_external_id, stored_msgs = await self._resolve_conversation(
             runtime=runtime,
             metadata=parsed.metadata,
             agent_name=agent.name,
             file_path=file_path,
+            first_user_text=parsed.turns[0].text,
         )
         outcome = diff_and_fork(stored=stored_msgs, incoming=parsed.turns)
         capture = TurnCapture()
@@ -423,7 +348,7 @@ class MarkdownFrontend(Frontend):
             messages=outcome.messages,
             origin="user",
             capture=capture,
-            use_session=outcome.divergence_index is None,
+            use_session=outcome.reuse_session,
         )
         try:
             message = await self._stream_to_file(
@@ -459,9 +384,6 @@ class MarkdownFrontend(Frontend):
             message=message,
         )
 
-        # Broadcast our own turn so other handlers (none today, but the
-        # symmetry is worth keeping) see what happened. ``source`` marks
-        # the origin so ``CrossFrontendLogger`` can skip its own files.
         record = TurnRecord(
             agent_name=agent.name,
             input_messages=list(parsed.messages),
@@ -482,9 +404,7 @@ class MarkdownFrontend(Frontend):
             "new_content": new_content,
         }
 
-    # ---- streaming dispatch (SSE) --------------------------------------
+    async def _handle_chat_streaming(  # noqa: PLR0915
-
-    async def _handle_chat_streaming(  # noqa: PLR0915 — mirrors _handle_chat, splitting only doubles read cost
         self,
         *,
         runtime: GatewayRuntime,
@@ -496,21 +416,9 @@ class MarkdownFrontend(Frontend):
     ) -> AsyncIterator[bytes]:
         """SSE counterpart of :meth:`_handle_chat`.
 
-        Mirrors the same pipeline (resolve file → parse → resolve agent →
+        Errors surface as ``error`` frames (HTTP is already 200 by then); disk
-        run backend → persist), but emits ``event: delta`` frames as the
+        is only written once at the end, avoiding a write race with Obsidian Sync.
-        rendered turn grows and a single terminal ``event: done`` /
-        ``event: error``. Errors that ``_handle_chat`` would surface as
-        ``HTTPException`` go out as ``error`` frames here (the HTTP
-        envelope is already 200 by the time the stream starts).
-
-        Intermediate disk writes are deliberately skipped — only the
-        post-stream :meth:`_write_assistant_reply` lands on disk, so the
-        gateway-side vault and the plugin-side editor are the only
-        writers in their respective halves of Obsidian Sync. Final
-        content is identical on both sides, so Sync no-ops.
         """
-        # With ``content`` the plugin is the only writer of the file
-        # (§3.10): the gateway never touches disk in that case.
         write_disk = content_override is None
         if isinstance(content_override, str):
             file_text = content_override
@@ -610,6 +518,7 @@ class MarkdownFrontend(Frontend):
                 metadata=parsed.metadata,
                 agent_name=agent.name,
                 file_path=file_path,
+                first_user_text=parsed.turns[0].text,
             )
         except HTTPException as exc:
             yield sse_pack(
@@ -646,7 +555,7 @@ class MarkdownFrontend(Frontend):
             messages=outcome.messages,
             origin="user",
             capture=capture,
-            use_session=outcome.divergence_index is None,
+            use_session=outcome.reuse_session,
         )
 
         acc = StreamAccumulator()
@@ -674,18 +583,12 @@ class MarkdownFrontend(Frontend):
                     or (now - last_flush) >= _SSE_FLUSH_DEBOUNCE
                 ):
                     payload = snapshot()
-                    # Skip duplicate snapshots — e.g. tool_use blocks
-                    # render to the same prefix as before they closed
-                    # (we don't surface the tool-call args in markdown).
                     if payload is not None and payload != last_payload:
                         yield sse_pack("delta", {"new_content": payload})
                         last_payload = payload
                     last_flush = now
-        except Exception as exc:  # noqa: BLE001 — wire any backend failure as an SSE error frame
+        except Exception as exc:  # noqa: BLE001
             _log.exception("backend failed for %s", filename)
-            # Mirror the legacy path: write the last partial + an error
-            # callout to disk so other consumers (logs, file watchers)
-            # see what arrived. The client gets a clean SSE ``error``.
             partial = acc.finalize(model=model)
             new_body = parsed.body
             if partial.content:
@@ -749,8 +652,6 @@ class MarkdownFrontend(Frontend):
             },
         )
 
-    # ---- helpers -------------------------------------------------------
-
     async def _stream_to_file(
         self,
         *,
@@ -763,17 +664,8 @@ class MarkdownFrontend(Frontend):
     ) -> Any:
         """Drain ``events`` into a ``Message``, flushing partials to disk.
 
-        Flushes happen on each ``RawContentBlockStopEvent`` (natural
+        Flushes on each block boundary and on a debounce timer; on backend
-        block boundary, content is markdown-consistent) and on the
+        failure it still flushes a partial + error callout, then re-raises.
-        ``_STREAM_FLUSH_DEBOUNCE`` timer between events. The partial
-        write keeps the as-parsed frontmatter; the post-stream final
-        write in ``_write_assistant_reply`` is what stamps the refreshed
-        fingerprint / agent / conversation_id.
-
-        On backend exception we still flush the last partial and append
-        an error callout, so the human sees both what arrived and why it
-        stopped. The exception propagates so ``_handle_chat`` can map it
-        to a 500.
         """
         acc = StreamAccumulator()
 
@@ -846,13 +738,12 @@ class MarkdownFrontend(Frontend):
         metadata: dict[str, Any],
         agent_name: str,
         file_path: Path,
+        first_user_text: str = "",
     ) -> tuple[Conversation, str, list[dict[str, Any]]]:
         """Resolve the ``deep`` conversation for this file + its stored messages.
 
-        Frontmatter ``conversation_id`` wins; a file that lost it is found
+        Precedence: frontmatter ``conversation_id`` > existing path binding >
-        by its visible ``(markdown, path)`` binding; otherwise a new
+        an adopted unbound conversation with the same first prompt > a new one.
-        conversation is created. The binding follows the file: a moved
-        chat re-binds to its new path on the next turn.
         """
         conversations = runtime.conversations
         rel = file_path.relative_to(self.vault_path).as_posix()
@@ -860,6 +751,12 @@ class MarkdownFrontend(Frontend):
         conv = await conversations.get(raw) if isinstance(raw, str) and raw else None
         if conv is None:
             conv = await conversations.find_bound(frontend=FRONTEND, external_id=rel)
+        if conv is None:
+            conv = await conversations.adopt(
+                kind="deep", first_user_text=first_user_text
+            )
+            if conv is not None:
+                _log.info("adopted conversation %s for %s", conv.external_id, rel)
         if conv is None:
             try:
                 conv = await conversations.create(
@@ -895,9 +792,8 @@ class MarkdownFrontend(Frontend):
     ) -> None:
         """Stamp the DB with the post-turn canonical Anthropic-shape history.
 
-        Combines the matched/spliced prior state, the new user prompt,
+        Combines prior state + new user prompt + the backend's synthesized
-        and the synthesized assistant/tool cycle from the backend (or a
+        cycle, falling back to text-only if ``capture`` is empty.
-        text-only fallback for backends that left ``capture`` empty).
         """
         new_user_msg = {"role": "user", "content": new_user_text}
         synthesized = capture.synthesized_messages or _fallback_synthesized(message)
@@ -919,12 +815,11 @@ class MarkdownFrontend(Frontend):
         )
 
     def _resolve_path(self, filename: str) -> Path:
-        """Resolve ``filename`` under the vault; reject escapes."""
+        """Resolve ``filename`` under the vault; reject escapes.
-        # ``filename`` may be relative or absolute; we always anchor
+
-        # under ``vault_path`` so absolute paths from outside the vault
+        Leading slashes are stripped first — ``Path.__truediv__`` would
-        # don't sneak through. ``Path("/foo/bar")`` combined with a
+        otherwise discard ``vault_path`` for an absolute ``filename``.
-        # vault path keeps the absolute side; we strip leading slashes
+        """
-        # to coerce the rooted form into a relative path before joining.
         rel = filename.lstrip("/")
         if not rel.endswith(".md"):
             rel = rel + ".md"
@@ -941,12 +836,8 @@ class MarkdownFrontend(Frontend):
 def _fallback_synthesized(message: Any) -> list[dict[str, Any]]:
     """Build a single-assistant ``synthesized_messages`` list from a raw ``Message``.
 
-    For backends that don't populate a :class:`TurnCapture` (anthropic
+    Fallback for backends that don't populate :class:`TurnCapture` (anthropic
-    HTTP, raycast, …) we don't have access to per-tool-cycle
+    HTTP, raycast, …); the reply lands as one canonical-block message.
-    granularity, so the assistant reply lands in the DB as one
-    canonical-block message. Tool memory across cache misses would
-    degrade in that case, but those backends don't have the cache-miss
-    re-seed problem to begin with — they manage history client-side.
     """
     content: list[dict[str, Any]] = []
     for block in getattr(message, "content", ()):

src/beaver_gateway/frontends/markdown/history.py

@@ -1,41 +1,7 @@
-"""Stateful conversation history for the markdown frontend.
+"""Stored conversation history for the markdown frontend.
 
-The gateway used to be stateless about identity: claude-code-api's
+Aligns the file the user is editing against the DB-stored Anthropic-shape
-in-memory session pool was keyed by a fingerprint of the messages the
+message history, splicing text edits or forking on structural changes.
-gateway forwarded, and on a fingerprint miss the same fingerprint was
-used to seed a fresh PTY's JSONL transcript. That worked as long as
-the frontend could round-trip the *exact* content blocks the live
-session had observed. The markdown frontend can't — the parser strips
-``[!tool]-`` callouts because the human is allowed to edit the prose,
-and the rendered tool callouts don't carry the canonical ``tool_use``
-block fields anyway. So a continuation hit was *only* reliable for
-turns that never used a tool; once tools entered the picture, every
-subsequent turn missed the cache and reseeded from a tool-less
-transcript, leading to "assistant doesn't remember the tool calls it
-just made."
-
-This module makes the gateway stateful for the markdown frontend (and
-any other frontend that wants in). The DB stores the full
-Anthropic-shape message list — text blocks, ``tool_use`` blocks,
-``tool_result`` blocks, thinking signatures — exactly as
-claude-code-api would have seen on the wire. Before each turn we
-align the file the user is editing against the stored history:
-
-* If the user just appended a new user turn at the bottom, we feed
-  the backend our stored-plus-new history and the fingerprint hits.
-* If the user edited the *text* inside an assistant turn but left the
-  tool callouts alone, we splice the new text into the stored
-  ``tool_use`` blocks and feed *that* — the fingerprint misses (text
-  differs), claude-code-api reseeds with a full transcript (tools and
-  all), the new live session has memory of the prior tool calls.
-* If the user changed the *structure* (added/removed/reordered a tool
-  callout, edited an old user turn, etc.) we fork: take stored history
-  up to the divergence, take incoming text-only past the divergence.
-  The fingerprint misses; claude-code-api reseeds with a clean
-  truncated history; downstream turns continue from there.
-
-"Divergence point" is found by walking the file's turns and the
-stored display turns in lockstep. See :func:`diff_and_fork`.
 """
 
 from __future__ import annotations
@@ -67,29 +33,23 @@ __all__ = [
 ]
 
 
-# ---- types --------------------------------------------------------------
-
-
 @dataclass(frozen=True, slots=True)
 class ForkOutcome:
     """Result of aligning the incoming file against stored history.
 
-    ``messages`` is what the gateway feeds to the backend (already
+    ``messages`` is the backend input; ``persist_messages`` is history to
-    includes the new user prompt at the tail). ``persist_messages``
+    store before the new reply; ``divergence_index`` is where they diverged.
-    is the canonical conversation state the gateway should hold in
-    the DB *up to but not including* the new assistant reply — the
-    caller appends the synthesized turn from the backend onto this
-    and writes the result back. ``divergence_index`` is the
-    display-turn index at which incoming first disagreed with stored
-    (``None`` if everything matched; the new tail is appended cleanly).
     """
 
     messages: list[MessageParam]
     persist_messages: list[dict[str, Any]]
     divergence_index: int | None
+    edited: bool = False
+    """An earlier assistant turn's prose was rewritten in the file."""
 
-
+    @property
-# ---- public store API ---------------------------------------------------
+    def reuse_session(self) -> bool:
+        return self.divergence_index is None and not self.edited
 
 
 async def load_conversation(
@@ -109,9 +69,7 @@ async def mint_conversation(
 ) -> Conversation:
     """Create a fresh conversation row with a new uuid for external_id.
 
-    Caller is responsible for persisting the returned ``external_id`` on
+    Caller must persist the returned ``external_id`` so future requests can find it.
-    the frontend side (frontmatter, response header, …) so future
-    requests can find this conversation again.
     """
     row = Conversation(
         frontend=frontend, external_id=str(uuid.uuid4()), agent_name=agent_name
@@ -138,9 +96,8 @@ async def load_messages(
 ) -> list[dict[str, Any]]:
     """Return stored messages ordered by ``seq`` ascending.
 
-    Each entry is a canonical Anthropic ``MessageParam`` dict — ``role``
+    Each entry is a canonical Anthropic ``MessageParam`` dict, the same
-    plus ``content`` (string or list of block dicts). The same shape
+    shape fed to the backend on continuation.
-    we feed to the backend on continuation.
     """
     stmt = (
         select(ConversationMessage)
@@ -158,10 +115,8 @@ async def load_messages(
 def _sanitize_content(content: Any) -> Any:
     """Strip wire-illegal fields from stored Anthropic content blocks.
 
-    Older capture code emitted ``"is_error": null`` on ``tool_result``
+    Drops ``tool_result.is_error: null`` — the API rejects null there
-    blocks; the Anthropic API rejects null there (the field is optional
+    though the field is optional.
-    but, when present, must be boolean). We omit the key on read so
-    historical rows don't break continuation.
     """
     if not isinstance(content, list):
         return content
@@ -182,27 +137,17 @@ def _sanitize_content(content: Any) -> Any:
 async def rewrite_messages(
     session: AsyncSession, *, conversation_id: int, messages: list[dict[str, Any]]
 ) -> None:
-    """Replace the conversation's stored messages with ``messages``.
+    """Replace the conversation's stored messages (full overwrite, no branch history).
 
-    The user said no branch history — we overwrite on fork. Cheap at
+    Deletes and flushes before inserting — SQLAlchemy's default INSERT-before-DELETE
-    our volume; if it ever matters we can switch to soft-delete +
+    flush order would otherwise collide with ``uq_msg_conv_seq``.
-    branch pointers.
     """
-    # Bulk-delete and flush before inserting the new sequence: SQLAlchemy's
-    # unit-of-work flushes INSERTs before DELETEs by default, which would
-    # trip ``uq_msg_conv_seq`` when the new rows reuse the same seq numbers
-    # as the soon-to-be-deleted ones.
-    # SQLModel descriptors resolve to ColumnElement at runtime but to bare
-    # ``int`` in ty's stubs; the select-path at line 135 lives behind sqlmodel's
-    # own ``select`` overloads that hide it, but ``sqlalchemy.delete().where``
-    # uses the raw stubs.
     await session.execute(  # ty: ignore[deprecated]
         delete(ConversationMessage).where(
             ConversationMessage.conversation_id == conversation_id  # ty: ignore[invalid-argument-type]
         )
     )
     await session.flush()
-    # Insert the new sequence.
     for seq, m in enumerate(messages):
         session.add(
             ConversationMessage(
@@ -212,7 +157,6 @@ async def rewrite_messages(
                 content_json=json.dumps(m["content"], separators=(",", ":")),
             )
         )
-    # Bump conversation.updated_at.
     conv = await session.get(Conversation, conversation_id)
     if conv is not None:
         from datetime import UTC, datetime
@@ -222,21 +166,11 @@ async def rewrite_messages(
     await session.commit()
 
 
-# ---- alignment ----------------------------------------------------------
-
-
 @dataclass(frozen=True, slots=True)
 class _StoredDisplayTurn:
     """A "display turn" reconstructed from stored raw messages.
 
-    ``role`` is ``"user"`` (single user-prompt message) or
+    Parser-equivalent view used to diff the file against the DB.
-    ``"assistant"`` (one or more assistant messages, optionally
-    interleaved with user-only-tool_result messages). ``messages`` is
-    the slice of stored raw messages this display turn covers, in
-    order. ``spoken_text`` and ``skeleton`` are the
-    parser-equivalents for diff purposes; ``text_segment_count`` lets
-    us refuse a splice when the user edited across a tool boundary in
-    a way we can't safely undo.
     """
 
     role: str
@@ -249,10 +183,8 @@ class _StoredDisplayTurn:
 def _group_display_turns(stored: list[dict[str, Any]]) -> list[_StoredDisplayTurn]:
     """Walk raw stored messages, group them into Obsidian-visible turns.
 
-    A user-prompt message (``role=user`` with string content, or list
+    A user-prompt message (no ``tool_result`` blocks) opens a new turn;
-    content with no ``tool_result`` blocks) opens a user display turn.
+    tool-result-only messages roll into the current assistant turn.
-    Otherwise it's a tool-result follow-up and rolls into the current
-    assistant display turn.
     """
     out: list[_StoredDisplayTurn] = []
     i = 0
@@ -271,7 +203,6 @@ def _group_display_turns(stored: list[dict[str, Any]]) -> list[_StoredDisplayTur
             )
             i += 1
             continue
-        # Assistant display turn: collect consecutive non-prompt messages.
         group: list[dict[str, Any]] = []
         while i < len(stored):
             m = stored[i]
@@ -293,14 +224,16 @@ def _group_display_turns(stored: list[dict[str, Any]]) -> list[_StoredDisplayTur
 
 
 def _is_user_prompt(content: Any) -> bool:
-    """A user message is a *prompt* unless its content carries tool_result blocks."""
+    """A user message is a *prompt* unless its content carries tool_result blocks.
+
+    Unknown content shapes are conservatively treated as a prompt.
+    """
     if isinstance(content, str):
         return True
     if isinstance(content, list):
         return not any(
             isinstance(b, dict) and b.get("type") == "tool_result" for b in content
         )
-    # Unknown shape — be conservative, treat as prompt.
     return True
 
 
@@ -322,13 +255,9 @@ def _summarize_assistant_group(
 ) -> tuple[str, list[str], int]:
     """Compute (spoken_text, tool_skeleton, text_segment_count) for a display group.
 
-    Mirrors what ``parser.parse_assistant_structure`` would produce when
+    Must mirror ``parser.parse_assistant_structure``: text blocks collapse into
-    re-parsing the rendered version of this group: consecutive text
+    one segment, tool_use becomes a skeleton entry, tool_result/thinking are invisible.
-    blocks across assistant messages collapse into one text segment;
-    tool_use blocks become skeleton entries; tool_result messages and
-    thinking blocks are invisible.
     """
-    # See ``diff_and_fork`` for why the parser-type imports are deferred.
     from beaver_gateway.frontends.markdown.parser import TextSegment, ToolSegment
 
     segments: list[TextSegment | ToolSegment] = []
@@ -345,7 +274,6 @@ def _summarize_assistant_group(
 
     for msg in group:
         if msg["role"] == "user":
-            # tool_result message — boundary for text but emits no segment.
             _flush()
             continue
         content = msg.get("content")
@@ -362,7 +290,6 @@ def _summarize_assistant_group(
             elif btype == "tool_use":
                 _flush()
                 segments.append(ToolSegment(name=str(blk.get("name", ""))))
-            # thinking: skip silently
     _flush()
     spoken_chunks = [s.text for s in segments if isinstance(s, TextSegment)]
     spoken = "\n\n".join(c for c in spoken_chunks if c).strip()
@@ -371,30 +298,14 @@ def _summarize_assistant_group(
     return spoken, skeleton, text_count
 
 
-# ---- the core algorithm -------------------------------------------------
-
-
 def diff_and_fork(
     *, stored: list[dict[str, Any]], incoming: list[ParsedTurn]
 ) -> ForkOutcome:
     """Align the incoming parsed file against stored history.
 
-    ``stored`` is the raw Anthropic-shape message list from the DB
+    ``incoming`` must end with a user turn (the new prompt); raises otherwise.
-    (one entry per ``ConversationMessage`` row). ``incoming`` is the
+    Segment-class imports below are deferred to avoid a cycle with ``parser``.
-    user-visible turn list from the markdown parser. The last
-    ``incoming`` entry must be a user turn — that's the new prompt
-    triggering this request.
-
-    Returns a :class:`ForkOutcome` whose ``messages`` is what the
-    backend should run on and whose ``persist_messages`` is the
-    canonical history to store in the DB once the backend's
-    synthesized cycle is appended.
     """
-    # ``parser`` lives under ``frontends/markdown/`` whose ``__init__``
-    # eagerly loads ``frontend.py``, which in turn imports this module
-    # — pulling the parser at module-import time creates a cycle. The
-    # helpers below import the segment classes lazily inside their own
-    # function bodies to break it.
     if not incoming or incoming[-1].role != "user":
         msg = (
             "diff_and_fork expects incoming to end with a user turn "
@@ -407,20 +318,14 @@ def diff_and_fork(
     new_user_turn = incoming[-1]
     prior_incoming = incoming[:-1]
 
-    spliced_groups, divergence = _walk_prefix(prior_incoming, stored_groups)
+    spliced_groups, divergence, edited = _walk_prefix(prior_incoming, stored_groups)
 
     if divergence is None and len(prior_incoming) < len(stored_groups):
         if _file_lags_store(stored_groups, len(prior_incoming), new_user_turn):
-            # Not a deletion — the file simply never received turns we
-            # already ran. Adopt the stored tail verbatim so history stays
-            # structured and its fingerprint still matches the live
-            # session's. See ``_file_lags_store`` for why this matters.
             spliced_groups.extend(
                 list(g.messages) for g in stored_groups[len(prior_incoming) :]
             )
         else:
-            # Incoming truncated stored (user deleted some past turns).
-            # Truncate stored to match.
             divergence = len(prior_incoming)
 
     backend_msgs, persist_msgs = _assemble_tail(
@@ -433,6 +338,7 @@ def diff_and_fork(
         messages=backend_msgs,
         persist_messages=persist_msgs,
         divergence_index=divergence,
+        edited=edited,
     )
 
 
@@ -441,26 +347,9 @@ def _file_lags_store(
 ) -> bool:
     """Is the shorter incoming file a stale view rather than a deletion?
 
-    A file with fewer display turns than the DB has two possible causes,
+    Tell: if the DB already holds the submitted prompt at the position the
-    and they need opposite handling:
+    file stops at, it's a lagging render, not a deletion — misjudging this
-
+    forks history, breaks the fingerprint, and respawns the backend session.
-    * the user deleted trailing turns — we should truncate to match;
-    * the turn ran, was persisted, but its reply never made it back into
-      the ``.md`` (the render lost a race with the user's next prompt, or
-      the reply rendered to nothing visible). The file is simply behind.
-
-    The tell is the prompt the user is submitting right now: if the DB
-    already holds it at exactly the position the file stops at, this is a
-    re-submission of a turn we've already run, not a deletion. Nobody
-    deletes a turn and immediately retypes it verbatim.
-
-    Getting this wrong is expensive and self-sustaining. Forking here
-    flattens every post-divergence turn into plain text (losing tool_use /
-    tool_result structure), persists that flattened history, and changes
-    the conversation fingerprint — so the backend's session pool misses,
-    spawns a fresh ``claude``, reseeds it from a multi-MB JSONL, and
-    strands the previous process. The file still lags afterwards, so the
-    next turn does it again.
     """
     if prior_len >= len(stored_groups):
         return False
@@ -470,46 +359,44 @@ def _file_lags_store(
 
 def _walk_prefix(
     prior_incoming: list[ParsedTurn], stored_groups: list[_StoredDisplayTurn]
-) -> tuple[list[list[dict[str, Any]]], int | None]:
+) -> tuple[list[list[dict[str, Any]]], int | None, bool]:
     """Walk incoming vs stored side-by-side until first divergence.
 
-    Returns the spliced/matched group list (one entry per matched
+    An empty incoming skeleton (no tool callouts rendered) means prose
-    display turn, each carrying the raw messages we'll feed to the
+    alone decides the match; a mismatch forces a fresh backend session.
-    backend for that turn) and the divergence index (``None`` if all
-    of ``prior_incoming`` matched).
     """
     from beaver_gateway.frontends.markdown.parser import TextSegment, ToolSegment
 
     spliced_groups: list[list[dict[str, Any]]] = []
+    edited = False
     for i, inc in enumerate(prior_incoming):
         if i >= len(stored_groups):
-            return spliced_groups, i
+            return spliced_groups, i, edited
         st = stored_groups[i]
         if inc.role != st.role:
-            return spliced_groups, i
+            return spliced_groups, i, edited
         if inc.role == "user":
             if inc.text != st.spoken_text:
-                return spliced_groups, i
+                return spliced_groups, i, edited
             spliced_groups.append(list(st.messages))
             continue
         inc_skeleton = tuple(
             s.name for s in inc.structure if isinstance(s, ToolSegment)
         )
         inc_text_count = sum(1 for s in inc.structure if isinstance(s, TextSegment))
-        # Files rendered without tool callouts (§3.10) carry no skeleton:
-        # prose alone decides whether the turn matched.
         if inc_skeleton and inc_skeleton != st.skeleton:
-            return spliced_groups, i
+            return spliced_groups, i, edited
         if inc.text == st.spoken_text:
             spliced_groups.append(list(st.messages))
             continue
         if inc_skeleton and inc_text_count != st.text_segment_count:
-            return spliced_groups, i
+            return spliced_groups, i, edited
         spliced = _splice_assistant_group(stored_group=st, incoming=inc)
         if spliced is None:
-            return spliced_groups, i
+            return spliced_groups, i, edited
         spliced_groups.append(spliced)
-    return spliced_groups, None
+        edited = True
+    return spliced_groups, None, edited
 
 
 def _assemble_tail(
@@ -565,21 +452,10 @@ def _splice_in_place(
 ) -> list[dict[str, Any]] | None:
     """Copy the stored messages, swapping only their text block contents.
 
-    Rebuilding a turn from the file loses everything the markdown never
+    Preserves message/thinking-block boundaries that a rebuild would lose
-    carried — thinking blocks, and the message boundaries claude chose.
+    (and that a cache-hit continuation depends on); returns ``None`` if
-    Both matter: an ``assistant[thinking] + assistant[text]`` pair (what
+    text blocks aren't 1:1 with incoming segments, so the caller rebuilds instead.
-    claude emits for a reasoning turn) collapses into a single message,
-    so the history is one message shorter than the one the backend
-    pooled its live session under, and the next turn misses the cache
-    and respawns. Substituting in place keeps the message count and the
-    invisible blocks exactly as stored.
-
-    Returns ``None`` when stored text blocks and incoming text segments
-    aren't one-to-one — consecutive text blocks merge into a single
-    rendered segment, so there'd be no way to know how to split the
-    edited prose back apart. The caller then rebuilds instead.
     """
-    # See ``diff_and_fork`` for why the parser-type import is deferred.
     from beaver_gateway.frontends.markdown.parser import TextSegment
 
     new_texts = [
@@ -615,18 +491,9 @@ def _splice_by_rebuild(
 ) -> list[dict[str, Any]] | None:
     """Rebuild an assistant display turn with new text + stored tool_use blocks.
 
-    Walks the incoming structure; for each ``TextSegment`` emits a
+    Matches tool_use blocks to incoming ``ToolSegment``s by position; returns
-    text block into the current assistant message; for each
+    ``None`` (caller forks) if a matching stored ``tool_result`` is missing.
-    ``ToolSegment`` consumes the next stored ``tool_use`` block (by
-    position), closes the current assistant message, emits the
-    matching ``tool_result`` user message, and opens a new assistant
-    message. Final ``TextSegment`` closes the last assistant message.
-
-    Returns ``None`` if we can't find a matching tool_result for some
-    tool_use (stored history is malformed) — caller falls back to
-    fork.
     """
-    # See ``diff_and_fork`` for why this import is deferred.
     from beaver_gateway.frontends.markdown.parser import TextSegment
 
     tool_uses, tool_results_by_id = _harvest_tool_blocks(stored_group)
@@ -653,8 +520,6 @@ def _splice_by_rebuild(
     if current_asst:
         spliced.append({"role": "assistant", "content": current_asst})
     elif not spliced:
-        # Defensive: assistant turn with no text and no tools makes no
-        # sense; caller will treat as fork.
         return None
     return spliced
 

src/beaver_gateway/frontends/markdown/mirror.py

@@ -1,13 +1,8 @@
-"""Vault files for ``deep`` conversations that were not typed into a file (§3.10).
+"""Vault files for ``deep`` conversations that were not typed into a file.
 
-``materialize`` is the markdown frontend's answer to ``spawn(kind=deep)``:
+``materialize`` creates the file for a conversation spawned elsewhere;
-a new file in the vault with ``agent`` + ``conversation_id`` frontmatter
+``run`` appends replies produced by other origins and keeps the canonical
-and the ``(markdown, path)`` binding. ``run`` tails the gateway bus and
+history in sync so a continuation typed in Obsidian resumes the same session.
-appends every ``reply`` of a markdown-bound conversation to its file -
-the seed turn of a spawn, a message posted through ``/api``, a turn
-that came in over ``/v1/messages`` - and stamps the same exchange into
-the canonical history, so a continuation typed in Obsidian aligns
-against the store and resumes the same SDK session instead of reseeding.
 """
 
 from __future__ import annotations
@@ -19,8 +14,6 @@ from typing import TYPE_CHECKING, Any
 
 import frontmatter
 
-from beaver_gateway.core.conversation_store import load_messages, rewrite_messages
-from beaver_gateway.core.turn_record import slugify
 from beaver_gateway.frontends.markdown import renderer
 from beaver_gateway.frontends.markdown.crossfront import strip_trailing_user_scaffold
 from beaver_gateway.frontends.markdown.files import (
@@ -28,12 +21,14 @@ from beaver_gateway.frontends.markdown.files import (
     reattach_frontmatter,
     write_atomic,
 )
+from beaver_gateway.frontends.markdown.history import load_messages, rewrite_messages
+from beaver_gateway.frontends.turn_record import slugify
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Sequence
     from pathlib import Path
 
-    from beaver_gateway.core.bus import Event
+    from beaver_gateway.events.bus import Event
     from beaver_gateway.frontends.base import GatewayRuntime
     from beaver_gateway.storage.models import Conversation, ConversationBinding
 

src/beaver_gateway/frontends/markdown/parser.py

@@ -1,18 +1,7 @@
 """Parse a markdown chat file into Anthropic ``MessageParam`` history.
 
-The file format is documented in ``frontends/markdown/__init__.py``:
+Turn markers are ``### User:`` / ``### Assistant:`` H3 headers; backend
-``### User:`` / ``### Assistant:`` H3 headers split turns, optional
+input drops thinking/tool callouts, keeping assistant turns text-only.
-``---`` HRs between turns are visual-only, ``> [!thinking]-`` and
-``> [!tool]- <name>`` callouts mark structured assistant content.
-
-For backend consumption we strip thinking and tool_use callouts —
-assistant turns become text-only. Rationale: history replay through
-claude-code's JSONL injection only needs the *narrated* answer (the
-thinking signatures expire and the original tool_results aren't
-captured in the renderer's output, so a faithful tool_use round-trip
-isn't possible today). The renderer keeps callouts in the file because
-they're informational for the human reader; the parser drops them when
-shaping the backend's input.
 """
 
 from __future__ import annotations
@@ -51,11 +40,7 @@ class TextSegment:
 class ToolSegment:
     """A ``> [!tool]- <name>`` callout placeholder.
 
-    Only the tool ``name`` is captured — the " · summary" suffix on the
+    Only the tool name is captured; the summary suffix is decorative.
-    callout title and the JSON body inside the quote block are
-    decorative for the human reader; the canonical tool_use block lives
-    in the DB and is keyed by *position+name* against the structure
-    parsed here.
     """
 
     name: str
@@ -64,26 +49,11 @@ class ToolSegment:
 AssistantSegment = TextSegment | ToolSegment
 
 
-# Turn marker — must be exactly ``### User:`` or ``### Assistant:`` on
-# its own line. Trailing whitespace tolerated; nothing after the colon
-# on the same line (any inline content would mean the user typed
-# something that just happens to look like a header, and we'd rather
-# misparse than silently fold inline content into a turn).
 _TURN_RE = re.compile(r"^###\s+(User|Assistant):\s*$", re.MULTILINE)
 
-# Callout-start lines we strip from assistant turns when extracting
-# text. We don't try to parse the contents — for backend input we just
-# need to drop the whole quoted block.
 _CALLOUT_START_RE = re.compile(r"^>\s+\[!(thinking|tool)\]")
 
-# Tool-callout title line: ``> [!tool]- <name>`` or ``> [!tool]- <name> · <summary>``.
-# We only need the ``<name>`` part for skeleton matching; the summary is
-# decorative (built by ``renderer.summarize_tool_input`` from inputs the
-# user can edit visually without semantic consequence).
 _TOOL_TITLE_RE = re.compile(r"^>\s+\[!tool\]-\s*(.*?)\s*$")
-# Renderer joins name + summary with " · " (U+00B7) — see
-# ``renderer.summarize_tool_input``. We split on it to recover the
-# bare tool name.
 _TOOL_TITLE_SEP = " · "
 
 
@@ -91,14 +61,8 @@ _TOOL_TITLE_SEP = " · "
 class ParsedTurn:
     """One turn extracted from the chat file.
 
-    ``role`` is ``"user"`` or ``"assistant"``. ``text`` is the spoken
+    ``text`` is spoken content only; ``structure`` (assistant turns only)
-    content with callouts stripped and HRs dropped — used both as the
+    carries the ordered text/tool segments used to align with stored history.
-    backend's ``MessageParam.content`` (back-compat with the existing
-    parser shape) and as the diff key against stored turns.
-    ``structure`` is non-empty only for assistant turns: an ordered
-    list of ``TextSegment`` / ``ToolSegment`` reflecting the visible
-    layout of the assistant block, used by the conversation store to
-    align with the canonical tool_use blocks held in DB.
     """
 
     role: str
@@ -110,16 +74,8 @@ class ParsedTurn:
 class ParsedFile:
     """Result of parsing a single chat ``.md``.
 
-    ``metadata`` is the YAML frontmatter as a plain dict (empty if the
+    ``messages`` is text-only history for the backend; ``turns`` carries
-    file has none). ``messages`` is the conversation history shaped for
+    per-turn structure; ``body`` is the raw content after frontmatter.
-    ``Backend.complete`` — assistant turns are text-only. ``turns`` is
-    1:1 with ``messages`` and carries the per-turn structure (for
-    assistant turns) that the conversation store needs to detect
-    text-only edits vs. structural forks. ``body`` is the raw markdown
-    content *after* the frontmatter is stripped; the renderer needs it
-    when it appends a new assistant turn so it can preserve whatever
-    the human typed verbatim (including any callouts or HRs they
-    added).
     """
 
     metadata: dict[str, Any]
@@ -131,15 +87,9 @@ class ParsedFile:
 def parse(text: str) -> ParsedFile:
     """Parse a chat ``.md`` into ``(metadata, body, messages, turns)``.
 
-    A file with no turn markers but non-empty body is treated as a
+    A bare file (no turn markers) is treated as a single user turn; a
-    single user turn — the friendly path for "user types into a new
+    tool-only assistant turn gets placeholder ``" "`` content since the
-    file and hits send" before any turn markers exist.
+    backend rejects an empty string.
-
-    Assistant turns that have *only* tool callouts (no spoken text) are
-    preserved here even though their ``MessageParam.content`` is empty
-    — the structure carries tool-segment information the conversation
-    store needs for skeleton matching. The renderer in practice always
-    emits at least a trailing text block, so this branch is defensive.
     """
     parsed = frontmatter.loads(text)
     metadata = dict(parsed.metadata)
@@ -175,14 +125,6 @@ def parse(text: str) -> ParsedFile:
                     )
                 )
             elif has_tools:
-                # Tool-only assistant turn: nothing to feed the backend
-                # as ``content`` (it'd reject an empty string), but the
-                # structure must survive so the store can align it
-                # against stored tool_use blocks. We synthesize a
-                # single-space text content for backend round-trip; the
-                # conversation store will replace this payload with the
-                # canonical stored blocks before the backend ever sees
-                # it on a continuation.
                 messages.append({"role": "assistant", "content": " "})
                 parsed_turns.append(
                     ParsedTurn(role="assistant", text="", structure=tuple(structure))
@@ -196,18 +138,8 @@ def parse(text: str) -> ParsedFile:
 def parse_assistant_structure(raw: str) -> list[TextSegment | ToolSegment]:
     """Walk an assistant turn body, return its ordered text/tool segments.
 
-    Tool callouts become :class:`ToolSegment` with just the tool name —
+    Tool callouts become :class:`ToolSegment` (name only); thinking callouts
-    the title's optional ``" · summary"`` suffix and the JSON body
+    and HR lines are stripped; boundary-empty text segments are dropped.
-    inside the quote block are decorative; the canonical tool_use
-    block is held in the conversation store. Thinking callouts are
-    stripped entirely (they were never round-trippable through the
-    file — signatures expire). HR separator lines drop out.
-
-    Empty / whitespace-only text segments at the boundaries (start,
-    end, between adjacent tool callouts) are dropped so the skeleton
-    is robust against renderer whitespace choices; a non-empty text
-    segment with surrounding whitespace is trimmed on both ends but
-    preserved.
     """
     segments: list[TextSegment | ToolSegment] = []
     pending_text: list[str] = []
@@ -216,9 +148,6 @@ def parse_assistant_structure(raw: str) -> list[TextSegment | ToolSegment]:
         if not pending_text:
             return
         joined = "\n".join(pending_text)
-        # Collapse runs of >2 blank lines (created when we stripped a
-        # mid-block callout) into one so the diff against a re-render
-        # is stable.
         cleaned = re.sub(r"\n{3,}", "\n\n", joined).strip()
         pending_text.clear()
         if cleaned:
@@ -231,7 +160,6 @@ def parse_assistant_structure(raw: str) -> list[TextSegment | ToolSegment]:
         callout_match = _CALLOUT_START_RE.match(line)
         if callout_match:
             kind = callout_match.group(1)
-            # Capture tool name *before* advancing past the block.
             if kind == "tool":
                 title_match = _TOOL_TITLE_RE.match(line)
                 title = title_match.group(1) if title_match else ""
@@ -239,9 +167,7 @@ def parse_assistant_structure(raw: str) -> list[TextSegment | ToolSegment]:
                 _flush_text()
                 segments.append(ToolSegment(name=name))
             else:
-                # Thinking callout — drop the whole block, emit nothing.
                 _flush_text()
-            # Skip the rest of the quote block.
             while i < len(lines) and lines[i].lstrip().startswith(">"):
                 i += 1
             continue
@@ -257,11 +183,7 @@ def parse_assistant_structure(raw: str) -> list[TextSegment | ToolSegment]:
 def _segments_to_spoken_text(segments: list[TextSegment | ToolSegment]) -> str:
     r"""Reduce a structure list to the spoken-text view the backend sees.
 
-    Concatenates :class:`TextSegment` contents with ``\n\n`` between
+    Concatenates text segments with ``\n\n``, dropping tool segments.
-    them, dropping :class:`ToolSegment` entries. Equivalent to what
-    the pre-Conversation-store parser did — we keep that behavior so
-    existing fingerprints (frontmatter ``fingerprint`` field) stay
-    valid.
     """
     chunks = [s.text for s in segments if isinstance(s, TextSegment)]
     return "\n\n".join(c for c in chunks if c).strip()
@@ -290,15 +212,11 @@ def resolve_agent(
     return default
 
 
-# ---- internals ---------------------------------------------------------
-
-
 def _split_turns(body: str) -> list[tuple[str, str]]:
     """Walk turn markers, return ``[(role_lc, raw_body), ...]``.
 
-    Body for each turn is everything between this marker and the next
+    A marker is an exact ``### User:`` / ``### Assistant:`` line; trailing
-    (or EOF). Leading marker line itself is dropped. We don't trim
+    content after the colon means it's not a marker, not a turn boundary.
-    whitespace here — that's per-role.
     """
     matches = list(_TURN_RE.finditer(body))
     if not matches:
@@ -315,9 +233,8 @@ def _split_turns(body: str) -> list[tuple[str, str]]:
 def _strip_hrs(raw: str) -> str:
     """Drop decorative ``---`` separator lines (whole-line HRs only).
 
-    A ``---`` mid-paragraph (rare, but possible) stays. Only lines that
+    Only lines that are exactly ``---`` (with optional surrounding
-    are *exactly* the HR after optional surrounding whitespace are
+    whitespace) are removed; a ``---`` mid-paragraph stays.
-    removed — those are the ones the renderer emits between turns.
     """
     lines = raw.splitlines()
     kept = [ln for ln in lines if ln.strip() != "---"]

src/beaver_gateway/frontends/markdown/renderer.py

@@ -1,10 +1,7 @@
-"""Render Anthropic ``Message`` (and individual user turns) into markdown.
+"""Render Anthropic ``Message`` (and user turns) into markdown.
 
-The renderer is one-way: it produces the human-facing artifact in the
+One-way: produces the human-facing artifact only. The parser strips
-vault. The parser strips tool/thinking callouts when reshaping the file
+tool/thinking callouts separately when reshaping history for backend replay.
-for backend replay — so what we write here is purely for the human
-reader (and for the cross-frontend logger, which materializes turns
-from other frontends).
 """
 
 from __future__ import annotations
@@ -30,23 +27,11 @@ __all__ = [
 ]
 
 
-# Empty ``### User:`` block appended after each assistant reply so the
-# human has an obvious place to type the next turn. Parser drops empty
-# user blocks, so this doesn't re-trigger dispatch on its own.
-# Blank line after the header, like every rendered turn - the file stays
-# symmetric whether the human or the gateway wrote the marker.
 USER_SCAFFOLD = "### User:\n\n"
 
 
-# Default 4-backtick fence so tool results that contain literal ```` ``` ````
-# don't collide. JSON inputs use 3 backticks because they almost never
-# contain ``` and we get language syntax highlighting in Obsidian for free.
 FENCE = "````"
 
-# Input keys we dangle after the tool name in the callout title, best
-# first — purely cosmetic. ``description`` wins because when a tool
-# offers one it's a human-written summary of the call, which beats a
-# truncated shell command or path.
 _TITLE_KEYS = ("description", "path", "file", "filename", "url", "command", "query")
 
 
@@ -61,25 +46,21 @@ def render_assistant_text(text: str) -> str:
 
 
 def render_assistant_message(message: Message) -> str:
-    """Render an assistant ``Message`` (with content blocks) into a turn block.
+    """Render an assistant ``Message`` into a turn block.
 
-    Blocks render in their original order:
+    Tool-use blocks render to nothing; of the thinking blocks between two
-
+    texts only the first one reaches the file.
-    * ``ThinkingBlock`` → ``> [!thinking]-`` collapsed callout
-    * ``TextBlock`` → plain text (the spoken answer)
-    * ``ToolUseBlock`` → nothing (§3.10: tool calls never reach the file;
-      "what the agent is doing" is the activity panel fed by SSE)
-
-    Blank lines separate adjacent blocks; trailing newline guarantees
-    the next ``---`` / ``### User:`` marker lands on its own line.
     """
     parts: list[str] = ["### Assistant:", ""]
+    after_thinking = False
     for block in message.content:
+        thinking = isinstance(block, ThinkingBlock)
+        if thinking and after_thinking:
+            continue
         lines = list(_render_block(block))
         if not lines:
-            # Tool calls render to nothing - no separator for them either,
-            # or every tool leaves a blank line behind.
             continue
+        after_thinking = thinking
         parts.extend(lines)
         parts.append("")
     return "\n".join(parts).rstrip() + "\n"
@@ -88,19 +69,12 @@ def render_assistant_message(message: Message) -> str:
 def render_user_param(param: MessageParam) -> str:
     """Render a ``MessageParam`` user message into a ``### User:`` block.
 
-    Used by the cross-frontend logger when materializing turns from
+    Tool_result blocks in the content list are dropped silently.
-    other frontends. Tool_result blocks in the content list are dropped
-    silently — the markdown view doesn't track them (see ``parser.py``).
     """
     content = param.get("content", "")
     if isinstance(content, str):
         text = content
     else:
-        # The Anthropic SDK types ``content`` as a union of typed-dict
-        # *Param classes plus pydantic block models — both shapes appear
-        # in practice (raw incoming JSON yields dicts, SDK-built params
-        # yield BaseModels). Treat each entry as a dict-like and pull
-        # ``text`` opportunistically.
         chunks = [
             str(blk.get("text", ""))
             for blk in content
@@ -111,11 +85,9 @@ def render_user_param(param: MessageParam) -> str:
 
 
 def append_to_body(existing: str, new_block: str) -> str:
-    """Append ``new_block`` to ``existing`` with a decorative HR separator.
+    """Append ``new_block`` to ``existing`` with a decorative ``---`` separator.
 
-    Preserves the original body verbatim (whitespace, callouts, any
+    The separator is visual only; the parser ignores it.
-    formatting the human added). The HR is purely visual: parser ignores
-    it.
     """
     head = existing.rstrip()
     if head:
@@ -124,18 +96,9 @@ def append_to_body(existing: str, new_block: str) -> str:
 
 
 def summarize_tool_input(name: str, tool_input: object) -> str:
-    """Build the ``[!tool]- <summary>`` title string.
+    """Build the ``[!tool]- <summary>`` title, picking one salient input field."""
-
-    Tries to pick a single salient field (``description``, ``path``,
-    ``command``, etc.) from the input dict so the collapsed callout shows
-    something meaningful in Obsidian. Falls back to just the tool name.
-    """
     if not isinstance(tool_input, dict):
         return name
-    # Anthropic ``ToolUseBlock.input`` is typed as ``object`` — the
-    # SDK's runtime value is always a JSON dict (str→Any), so a local
-    # cast keeps the rest of the function readable without sprinkling
-    # per-line type narrowing on every ``.get`` call.
     d = cast("dict[str, Any]", tool_input)
     for key in _TITLE_KEYS:
         value = d.get(key)
@@ -145,9 +108,6 @@ def summarize_tool_input(name: str, tool_input: object) -> str:
     return name
 
 
-# ---- internals ---------------------------------------------------------
-
-
 def _render_block(block: object) -> Iterable[str]:
     if isinstance(block, TextBlock):
         text = (block.text or "").strip()
@@ -157,7 +117,6 @@ def _render_block(block: object) -> Iterable[str]:
     if isinstance(block, ThinkingBlock):
         yield from _render_thinking(block.thinking or "")
         return
-    # Tool-use blocks and unknown block types never reach the file.
 
 
 def _render_thinking(text: str) -> Iterable[str]:
@@ -167,12 +126,7 @@ def _render_thinking(text: str) -> Iterable[str]:
 
 
 def adaptive_fence(content: str) -> str:
-    """Return a backtick fence at least one longer than the longest run in ``content``.
+    """Return a backtick fence longer than any backtick run in ``content``."""
-
-    Currently unused (tool *results* aren't persisted yet) — kept here
-    so when result capture lands the rendering side already has the
-    primitive.
-    """
     longest = 0
     for match in re.finditer(r"`+", content):
         longest = max(longest, len(match.group(0)))

src/beaver_gateway/frontends/mcp_server.py

@@ -1,43 +1,13 @@
-"""External MCP frontend (Phase 3.1).
+"""External MCP frontend.
 
-A streamable-HTTP gateway in front of the internal MCP aggregator
+Streamable-HTTP gateway that reverse-proxies the internal MCP aggregator,
-(``beaver_gateway.mcp.internal_app``). The aggregator hosts every
+adding bearer auth, an audit log line per request, and a discovery page.
-declared ``McpServer`` (``python_tool``, stdio proxy, HTTP proxy)
-under ``/mcp/<name>`` plus a flat ``/mcp/all`` bundle on
-``127.0.0.1:INTERNAL_MCP_PORT`` — that's the *internal* shape.
-
-This frontend re-exposes those namespaces on its own port directly at
-``/<name>/`` (no ``/mcp/`` prefix in the external routes — the port
-itself already disambiguates). Caddy / nginx / Cloudflare in front
-typically strips a prefix back on: ``domain.com/mcp/* → :8001/*``,
-controlled by the operator's reverse-proxy config and surfaced to the
-admin dashboard via ``public_base_url``. Three additions on top of the
-raw aggregator:
-
-* **Bearer auth** — ``Authorization: Bearer <token>``, ``X-Api-Key``,
-  or ``?token=<…>`` query string. All three forms verify against the
-  same :class:`TokenStore` as ``AnthropicMessagesFrontend``.
-* **Audit log** — one line per request (token name, namespace,
-  request method/path, response status). The DB-backed audit log lives
-  in Phase 4; for now we just emit a structured log line.
-* **Discovery page** at ``GET /`` (auth-gated) — HTML rendered with a
-  tiny inline Jinja2 template listing every namespace plus copy-pastable
-  config snippets for Cursor / claude.ai / Claude Desktop.
-
-Why a reverse proxy and not a second mount? FastMCP's session managers
-are tied to the lifespan they were created in; running the same
-aggregator under two uvicorn servers double-initializes state. Building
-two parallel aggregators would double upstream connections (two
-subprocesses for every stdio MCP, two HTTP clients for every remote).
-A loopback proxy keeps one source of truth — the internal aggregator —
-and lets us layer policy on the outside.
 """
 
 from __future__ import annotations
 
 import asyncio
 import logging
-from contextlib import asynccontextmanager
 from typing import TYPE_CHECKING, Any
 from urllib.parse import urlencode
 
@@ -46,9 +16,10 @@ from starlette.applications import Starlette
 from starlette.responses import HTMLResponse, JSONResponse, StreamingResponse
 from starlette.routing import Route
 
-from beaver_gateway.core import audit
 from beaver_gateway.frontends.base import Frontend
+from beaver_gateway.frontends.urls import external_base
 from beaver_gateway.mcp.internal_app import ALL_NAMESPACE
+from beaver_gateway.security import audit
 
 if TYPE_CHECKING:
     from collections.abc import AsyncIterator, Mapping
@@ -61,10 +32,6 @@ if TYPE_CHECKING:
 _log = logging.getLogger("beaver_gateway.frontends.mcp_server")
 
 
-# Hop-by-hop headers that must NOT be forwarded across an HTTP proxy
-# (RFC 7230 §6.1). Bypassing this filter would break chunked transfer
-# encoding when ``Content-Length`` arrives, or upstream-aware proxies
-# would refuse the second hop's connection-pool reuse.
 _HOP_BY_HOP_HEADERS = frozenset(
     {
         "connection",
@@ -80,11 +47,6 @@ _HOP_BY_HOP_HEADERS = frozenset(
     }
 )
 
-# Standard auth-bearing headers we *do not* forward to the internal app —
-# the internal app is on loopback with no auth of its own, and forwarding
-# the inbound bearer would only confuse it. Each method-specific MCP
-# request from the upstream Cursor/etc. carries a fresh ``mcp-session-id``
-# that we *must* forward.
 _AUTH_HEADERS = frozenset({"authorization", "x-api-key"})
 
 
@@ -94,87 +56,41 @@ __all__ = ["McpServerFrontend"]
 class McpServerFrontend(Frontend):
     """Auth + audit + reverse-proxy in front of the internal MCP aggregator."""
 
-    def __init__(
+    path = "/mcp"
-        self,
+
-        *,
+    def __init__(self) -> None:
-        host: str = "0.0.0.0",  # noqa: S104
-        port: int = 8001,
-        public_base_url: str | None = None,
-    ) -> None:
-        self.host = host
-        self.port = port
-        # External URL prefix the reverse proxy uses to reach this
-        # frontend. Internal routes mount namespaces at the port root
-        # (``/<ns>/`` and ``/all/``) — Caddy / nginx / Cloudflare in
-        # front decides what external prefix they sit under. Typical
-        # symmetric setup:
-        #
-        #     Caddy: handle_path /mcp/* { reverse_proxy localhost:8001 }
-        #     config: public_base_url -> https://api.example.com/mcp
-        #     dashboard advertises: https://api.example.com/mcp/<ns>/
-        #
-        # The frontend's ``/<ns>/`` segment gets appended verbatim. Set
-        # it to whatever matches your proxy. ``None`` means "advertise
-        # raw ``host:port`` derived from the inbound request" (dev /
-        # no proxy).
-        self.public_base_url = public_base_url.rstrip("/") if public_base_url else None
         self._runtime: GatewayRuntime | None = None
         self._app: Starlette | None = None
-        # Single shared aiohttp session, opened once when uvicorn starts
-        # the Starlette lifespan. Reused across every proxied request —
-        # MCP clients (esp. claude.ai) reconnect frequently, and a fresh
-        # ClientSession per call would cost a TCP handshake every time.
         self._http: aiohttp.ClientSession | None = None
 
     def configure(self, runtime: GatewayRuntime) -> None:
         self._runtime = runtime
         self._app = self._build_app(runtime)
 
+    def app(self) -> Starlette | None:
+        return self._app
+
     async def serve(self) -> None:
-        import uvicorn
-
-        if self._app is None:
-            msg = "configure() must be called before serve()"
-            raise RuntimeError(msg)
-
-        config = uvicorn.Config(
-            self._app, host=self.host, port=self.port, log_level="info"
-        )
-        server = uvicorn.Server(config)
-        await server.serve()
-
-    def _build_app(self, runtime: GatewayRuntime) -> Starlette:  # noqa: ARG002
-        # The Starlette lifespan owns the shared aiohttp session: opened
-        # at startup, closed at shutdown so we don't leak sockets when
-        # uvicorn is restarted under the same process. Starlette wants a
-        # plain context manager, not an async-generator function — we
-        # decorate to match.
-        @asynccontextmanager
-        async def lifespan(_app: Starlette) -> AsyncIterator[None]:
         self._http = aiohttp.ClientSession(
-                # Long sock_read because MCP tool calls can take a while
-                # (a claude tool over HTTP can easily stretch beyond 30s
-                # on a real tool).
             timeout=aiohttp.ClientTimeout(total=None, sock_read=600)
         )
         try:
-                yield
+            await asyncio.Event().wait()
         finally:
-                if self._http is not None:
             await self._http.close()
             self._http = None
 
+    def _build_app(self, runtime: GatewayRuntime) -> Starlette:  # noqa: ARG002
+        """Build the Starlette app.
+
+        Literal routes (``/``, ``/healthz``) are listed before the
+        namespace wildcard so they win the match instead of being
+        swallowed by it; two routes per namespace cover both ``/x`` and
+        ``/x/y`` since Starlette won't fold them into one.
+        """
         routes = [
             Route("/", self._discovery, methods=["GET"]),
             Route("/healthz", self._healthz, methods=["GET"]),
-            # Namespaces mount at the root of this port — the port
-            # itself already disambiguates this from any other gateway
-            # surface. Two routes per namespace so both the
-            # trailing-slash and sub-path forms work (``/time`` AND
-            # ``/time/foo``); Starlette doesn't fold them into one
-            # route automatically. The literal routes above (``/``,
-            # ``/healthz``) are listed first and win the match, so
-            # they're not eaten by ``/{namespace}``.
             Route(
                 "/{namespace}",
                 self._proxy_endpoint,
@@ -186,7 +102,7 @@ class McpServerFrontend(Frontend):
                 methods=["GET", "POST", "DELETE", "OPTIONS"],
             ),
         ]
-        return Starlette(routes=routes, lifespan=lifespan)
+        return Starlette(routes=routes)
 
     async def _healthz(self, _request: Request) -> JSONResponse:
         return JSONResponse({"status": "ok"})
@@ -196,14 +112,8 @@ class McpServerFrontend(Frontend):
         token_name, err = await _verify_request(request, runtime)
         if err is not None:
             return err
-        assert token_name is not None  # noqa: S101 — narrow for ty
+        assert token_name is not None  # noqa: S101
-        # ``public_base_url`` wins if configured — it's the operator's
+        base = external_base(request, runtime)
-        # explicit statement of "this is the URL my reverse proxy puts
-        # in front of me". Otherwise: use the request's own scheme+host
-        # so snippets work behind generic reverse proxies / tunnels;
-        # and fall back to the configured host:port if the client
-        # didn't send Host (curl --raw).
-        base = self.public_base_url or _external_base_url(request, self.host, self.port)
         html = _render_discovery_page(
             base_url=base, namespaces=list(runtime.mcps), actor=token_name
         )
@@ -216,7 +126,7 @@ class McpServerFrontend(Frontend):
         token_name, err = await _verify_request(request, runtime)
         if err is not None:
             return err
-        assert token_name is not None  # noqa: S101 — narrow for ty
+        assert token_name is not None  # noqa: S101
 
         namespace = request.path_params["namespace"]
         subpath = request.path_params.get("path", "")
@@ -240,7 +150,6 @@ class McpServerFrontend(Frontend):
             )
 
         if self._http is None:
-            # Lifespan hasn't run yet (shouldn't happen with uvicorn).
             return JSONResponse({"error": "frontend not ready"}, status_code=503)
 
         return await _reverse_proxy(
@@ -253,11 +162,12 @@ class McpServerFrontend(Frontend):
         )
 
     def _upstream_url(self, namespace: str, subpath: str) -> str | None:
+        """Resolve ``namespace`` to its internal loopback URL.
+
+        ``ALL_NAMESPACE`` isn't in the URL map, so its URL is synthesized
+        from any per-domain entry's authority.
+        """
         runtime = self._require_runtime()
-        # ``all`` is built by the aggregator unconditionally when at least
-        # one MCP is configured; the URL map only contains per-domain
-        # entries (see ``build_internal_app``), so we synthesize ``all``'s
-        # loopback URL from any per-domain URL's authority.
         if namespace == ALL_NAMESPACE:
             sample = next(iter(runtime.mcp_internal_urls.values()), None)
             if sample is None:
@@ -284,13 +194,8 @@ async def _verify_request(
 ) -> tuple[str | None, JSONResponse | None]:
     """Accept ``Authorization: Bearer``, ``X-Api-Key``, or ``?token=``.
 
-    The third form is the escape hatch for clients that can only put
+    Returns ``(actor_name, None)`` on success, else ``(None, error_response)``
-    secrets in the URL (claude.ai's MCP config historically did this).
+    — 401 for a missing/unknown token, 403 for one whose scope doesn't cover this call.
-    All three roads end at the same :class:`TokenStore`. Returns
-    ``(actor_name, None)`` on success, ``(None, 401|403)`` otherwise
-    — the caller forwards the response as-is. Splitting auth vs scope
-    failures matters: 401 says "send me a token", 403 says "this token
-    is real but not for this endpoint".
     """
     api_key = request.headers.get("x-api-key")
     if api_key:
@@ -328,23 +233,13 @@ def _forbidden(scope: str, required: str) -> JSONResponse:
 def _join_subpath(base_url: str, subpath: str) -> str:
     """Concatenate the loopback URL with the proxied sub-path.
 
-    ``base_url`` always ends in ``/`` (the aggregator publishes URLs
+    ``base_url`` always ends in ``/`` to avoid Starlette's redirect dance.
-    that way to avoid Starlette's 307 redirect dance); the sub-path is
-    appended verbatim, with the query string handled by the caller.
     """
     if subpath:
         return base_url + subpath.lstrip("/")
     return base_url
 
 
-def _external_base_url(request: Request, fallback_host: str, fallback_port: int) -> str:
-    host = request.headers.get("host")
-    if host:
-        scheme = request.headers.get("x-forwarded-proto", request.url.scheme)
-        return f"{scheme}://{host}"
-    return f"http://{fallback_host}:{fallback_port}"
-
-
 async def _reverse_proxy(
     *,
     client: aiohttp.ClientSession,
@@ -354,18 +249,14 @@ async def _reverse_proxy(
     actor: str,
     runtime: GatewayRuntime,
 ) -> StreamingResponse | JSONResponse:
-    """Bidirectionally stream an MCP request between client ↔ internal aggregator.
+    """Bidirectionally stream an MCP request between client and internal aggregator.
 
-    Streamable-HTTP MCP responses can be a long-running SSE stream
+    The audit row is written right after the upstream response headers
-    (tools that emit partial progress) or a one-shot JSON body; we
+    arrive, before relaying its body, so a client-truncated stream is
-    don't peek — just relay chunks as they arrive in either direction
+    still audited.
-    until both sides close.
     """
     qs = request.url.query
     if qs:
-        # Drop ``?token=`` from the forwarded URL — internal app doesn't
-        # need it, and propagating creds further than necessary widens
-        # the leak surface (logs, metrics, traces all see query strings).
         scrubbed = _scrub_query(qs, drop={"token"})
         if scrubbed:
             upstream_url = f"{upstream_url}?{scrubbed}"
@@ -411,9 +302,6 @@ async def _reverse_proxy(
         request.url.path,
         upstream_resp.status,
     )
-    # Audit at upstream-response time: status reflects the MCP call's
-    # outcome (200 / tool-error / 4xx). Streaming relay below may be
-    # cut short by the client, but the row is already in by then.
     await audit.log(
         runtime,
         actor=f"token:{actor}",
@@ -430,7 +318,6 @@ async def _reverse_proxy(
             async for chunk in upstream_resp.content.iter_any():
                 yield chunk
         except (aiohttp.ClientError, asyncio.CancelledError):
-            # Caller hung up or upstream dropped — just stop relaying.
             return
         finally:
             upstream_resp.release()
@@ -450,6 +337,11 @@ async def _request_body_iter(request: Request) -> AsyncIterator[bytes]:
 
 
 def _forward_headers(request: Request) -> dict[str, str]:
+    """Drop hop-by-hop headers (RFC 7230 §6.1) and inbound auth headers.
+
+    The internal aggregator is loopback-only with no auth of its own,
+    so forwarding the caller's bearer would only confuse it.
+    """
     out: dict[str, str] = {}
     for key, value in request.headers.items():
         lowered = key.lower()
@@ -482,11 +374,7 @@ def _scrub_query(query: str, *, drop: frozenset[str] | set[str]) -> str:
 
 
 def _render_discovery_page(*, base_url: str, namespaces: list[Any], actor: str) -> str:
-    """Render the auth-gated namespace + config-snippet page.
+    """Render the auth-gated namespace + config-snippet page."""
-
-    Inline HTML (no Jinja file) — keeps Phase 3 free of template-dir
-    plumbing that Phase 4's AdminFrontend will own.
-    """
     name_list = [getattr(ns, "name", str(ns)) for ns in namespaces]
     rows = (
         "\n".join(
@@ -520,7 +408,7 @@ def _escape(value: str) -> str:
     )
 
 
-_DISCOVERY_TEMPLATE = "\n".join(  # noqa: FLY002 — readability beats one-string-blob
+_DISCOVERY_TEMPLATE = "\n".join(  # noqa: FLY002
     [
         "<!doctype html>",
         '<html lang="en">',

src/beaver_gateway/frontends/root.py

@@ -0,0 +1,54 @@
+"""The one ASGI app the gateway listens with.
+
+Every HTTP frontend is mounted under its ``path`` (``/anthropic``,
+``/mcp``, ``/md``, ``/api``, ``/admin``); ``/healthz`` answers for the
+whole process and ``/`` redirects to the landing frontend (the admin
+console) when one is configured.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from starlette.applications import Starlette
+from starlette.responses import JSONResponse, RedirectResponse
+from starlette.routing import Mount, Route
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Mapping
+
+    from starlette.requests import Request
+    from starlette.types import ASGIApp
+
+    from beaver_gateway.frontends.base import Frontend
+
+__all__ = ["build_root_app"]
+
+
+def build_root_app(
+    frontends: Iterable[Frontend], *, extra: Mapping[str, ASGIApp] | None = None
+) -> Starlette:
+    mounted = [fe for fe in frontends if fe.path and fe.app() is not None]
+    landing = next((fe for fe in mounted if fe.landing), None)
+    paths = [*(fe.path for fe in mounted), *(extra or {})]
+
+    async def healthz(_request: Request) -> JSONResponse:
+        return JSONResponse({"status": "ok", "frontends": paths})
+
+    async def index(_request: Request) -> JSONResponse | RedirectResponse:
+        if landing is not None:
+            return RedirectResponse(f"{landing.path}/", status_code=307)
+        return JSONResponse({"frontends": paths})
+
+    routes: list[Route | Mount] = [
+        Route("/healthz", healthz, methods=["GET"]),
+        Route("/", index, methods=["GET"]),
+    ]
+    for fe in mounted:
+        app = fe.app()
+        assert app is not None  # noqa: S101
+        assert fe.path is not None  # noqa: S101
+        routes.append(Mount(fe.path, app=app, name=fe.name or fe.path.strip("/")))
+    for path, app in (extra or {}).items():
+        routes.append(Mount(path, app=app, name=path.strip("/")))
+    return Starlette(routes=routes)

src/beaver_gateway/frontends/sse.py

@@ -29,10 +29,8 @@ async def events_with_heartbeat(
 ) -> AsyncIterator[Any]:
     """Pass ``events`` through, yielding ``None`` after ``interval`` seconds of silence.
 
-    One in-flight ``__anext__`` task is reused across timeouts: a second
+    Only one consumer may iterate the result at a time; cancelling the
-    consumer on the same async generator raises ``RuntimeError``.
+    outer scope cancels the in-flight upstream fetch instead of leaking it.
-    Cancellation of the outer scope cancels that task instead of leaving
-    it dangling.
     """
     src = events.__aiter__()
     next_task: asyncio.Task[Any] | None = None

src/beaver_gateway/frontends/telegram/__init__.py

@@ -1,5 +1,6 @@
-"""Telegram frontend (§3.8): General = master, topic = branch, drafts, inbox/outbox."""
+"""Telegram frontend: General = master, topic = branch, drafts, inbox/outbox."""
 
 from beaver_gateway.frontends.telegram.frontend import Attachments, TelegramFrontend
+from beaver_gateway.frontends.telegram.texts import TelegramTexts
 
-__all__ = ["Attachments", "TelegramFrontend"]
+__all__ = ["Attachments", "TelegramFrontend", "TelegramTexts"]

src/beaver_gateway/frontends/telegram/drafts.py

@@ -1,13 +1,8 @@
-"""One ``sendMessageDraft`` stream per running turn (§3.8).
+"""One ``sendMessageDraft`` stream per running turn.
 
-The client folds a draft into the message that follows only when their
+Telegram folds a draft into the following message only when their texts are
-texts are identical - so the last push is the final text itself, rendered
+identical, so the last push is the final text verbatim. Drafts live 30s and
-exactly as the outbox will send it, with no status line.
+throttle to about one edit/s, so this refreshes on a timer, not every delta.
-
-A draft is ephemeral and lives 30 s, Telegram throttles edits to about one
-per second per chat, and thinking or a tool call would otherwise look like a
-hang - so the draft opens with a status line straight away, is refreshed on
-a timer rather than on every delta, and is kept alive while nothing changes.
 """
 
 from __future__ import annotations
@@ -21,7 +16,7 @@ from typing import TYPE_CHECKING
 
 from aiogram.exceptions import TelegramAPIError, TelegramBadRequest
 
-from beaver_gateway.frontends.telegram.render import to_html
+from beaver_gateway.frontends.telegram.render import to_html, to_html_tail
 
 if TYPE_CHECKING:
     from aiogram import Bot
@@ -43,7 +38,7 @@ class Draft:
         thread_id: int | None,
         turn_id: str,
         interval: float = 0.7,
-        status: str = "⏳ думаю",
+        status: str = "⏳ thinking",
     ) -> None:
         self._bot = bot
         self._chat_id = chat_id
@@ -52,12 +47,17 @@ class Draft:
         self._interval = interval
         self.status = status
         self.text = ""
+        self._paused = False
         self._dirty = True
         self._broken = False
         self._last_sent = 0.0
         self._task: asyncio.Task[None] | None = None
         self._inflight: asyncio.Future[None] | None = None
 
+    @property
+    def draft_id(self) -> int:
+        return self._draft_id
+
     def start(self) -> None:
         if self._task is None:
             self._task = asyncio.create_task(self._run())
@@ -66,10 +66,21 @@ class Draft:
         if status != self.status:
             self.status = status
             self._dirty = True
+            self._paused = bool(self.text.strip())
 
     def append(self, text: str) -> None:
-        if text:
+        """Add streamed text; a tool call in between starts a new paragraph.
+
+        The model ends a sentence, calls a tool, then goes on without a
+        break - the same text the final message shows as paragraphs.
+        """
+        if not text:
+            return
+        if self._paused and not self.text.endswith("\n"):
+            self.text = self.text.rstrip() + "\n\n" + text.lstrip()
+        else:
             self.text += text
+        self._paused = False
         self._dirty = True
 
     async def stop(self) -> None:
@@ -112,12 +123,12 @@ class Draft:
     async def _push(self) -> None:
         self._dirty = False
         self._last_sent = time.monotonic()
-        text = self._render()
+        rendered, plain = self._render()
         try:
             try:
-                await self._send(to_html(text), "HTML")
+                await self._send(rendered, "HTML")
             except TelegramBadRequest:
-                await self._send(text, None)
+                await self._send(plain, None)
         except TelegramAPIError as exc:
             self._broken = True
             _log.warning(
@@ -131,8 +142,12 @@ class Draft:
             message_thread_id=self._thread_id,
             text=text,
             parse_mode=parse_mode,
+            can_stop=True,
         )
 
-    def _render(self) -> str:
+    def _render(self) -> tuple[str, str]:
         tail = self.text[-_TAIL:]
-        return f"{self.status}\n\n{tail}" if tail.strip() else self.status
+        if not tail.strip():
+            return to_html(self.status), self.status
+        rendered = f"{to_html(self.status)}\n\n{to_html_tail(self.text, _TAIL)}"
+        return rendered, f"{self.status}\n\n{tail}"

src/beaver_gateway/frontends/telegram/inbox.py

@@ -1,8 +1,7 @@
-"""Long-polling inbox (§3.8).
+"""Long-polling inbox.
 
 Every update lands in ``telegram_updates`` before the offset moves past it;
-a worker handles rows from the table, oldest first, and finishes whatever a
+a worker handles rows from the table, oldest first, resuming after a restart.
-previous process left unprocessed at startup.
 """
 
 from __future__ import annotations
@@ -32,7 +31,11 @@ __all__ = ["Inbox"]
 
 _log = logging.getLogger("beaver_gateway.frontends.telegram.inbox")
 
-ALLOWED_UPDATES = ("message", "callback_query")
+ALLOWED_UPDATES = ("message", "callback_query", "stopped_message_generation")
+
+
+def _unset(_value: object) -> None:
+    """Unset aiogram ``Default`` sentinels (link previews) are stored as null."""
 
 
 class Inbox:
@@ -85,7 +88,9 @@ class Inbox:
     async def _store(self, update: Update) -> None:
         row = TelegramUpdate(
             update_id=update.update_id,
-            payload=update.model_dump(mode="json", by_alias=True, exclude_none=True),
+            payload=update.model_dump(
+                mode="json", by_alias=True, exclude_none=True, fallback=_unset
+            ),
         )
         async with self._db.session() as session:
             session.add(row)

src/beaver_gateway/frontends/telegram/outbox.py

@@ -1,8 +1,7 @@
-"""Outbox (§3.8): a reply is a ``deliveries`` row first, a message second.
+"""Outbox: a reply is a ``deliveries`` row first, a message second.
 
-Rows are sent oldest first, retried with backoff on network errors and
+Rows are sent oldest first, retried with backoff on network errors, resent
-flood limits, resent as plain text when Telegram rejects our HTML, and
+as plain text when Telegram rejects our HTML, and given up once it's gone.
-given up only when Telegram says the window is gone.
 """
 
 from __future__ import annotations
@@ -32,7 +31,7 @@ from beaver_gateway.storage.models import Delivery
 if TYPE_CHECKING:
     from aiogram import Bot
 
-    from beaver_gateway.core.bus import EventBus
+    from beaver_gateway.events.bus import EventBus
     from beaver_gateway.storage.db import Database
 
 __all__ = ["Outbox"]
@@ -143,7 +142,7 @@ class Outbox:
             if "parse" in text and not row.plain:
                 await self._retry(row, str(exc), delay=0.0, plain=True)
             elif any(marker in text for marker in _GONE):
-                await self._fail(row, str(exc))
+                await self._fail(row, str(exc), gone=True)
             else:
                 await self._fail(row, str(exc))
         except (TelegramNotFound, TelegramForbiddenError) as exc:
@@ -180,7 +179,7 @@ class Outbox:
         if delay < 5.0:
             self._wake.set()
 
-    async def _fail(self, row: Delivery, error: str) -> None:
+    async def _fail(self, row: Delivery, error: str, *, gone: bool = False) -> None:
         _log.error(
             "delivery #%s to %s/%s given up: %s",
             row.id,
@@ -196,6 +195,7 @@ class Outbox:
             chat_id=row.chat_id,
             thread_id=row.thread_id,
             error=error,
+            gone=gone,
         )
 
     async def _mark(

src/beaver_gateway/frontends/telegram/render.py

@@ -4,96 +4,89 @@ from __future__ import annotations
 
 import html
 import re
-from typing import Any
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal
 
-__all__ = ["LIMIT", "chunks", "status_label", "to_html"]
+from beaver_gateway.frontends.telegram.texts import TOOL_LABELS
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+
+__all__ = ["LIMIT", "chunks", "status_label", "to_html", "to_html_tail"]
 
 LIMIT = 4000
-_FENCE = re.compile(r"```[^\n]*\n(.*?)(?:```|$)", re.DOTALL)
+_SNAP = 200
-_INLINE_CODE = re.compile(r"(`[^`\n]+`)")
+
-_HEADING = re.compile(r"^#{1,6}\s+(.+)$", re.MULTILINE)
+_FENCE_OPEN = re.compile(r"^\s*```(.*)$")
-_BOLD = re.compile(r"\*\*(.+?)\*\*|__(.+?)__", re.DOTALL)
+_FENCE_CLOSE = re.compile(r"^\s*```\s*$")
+_LANG = re.compile(r"[\w+#.-]+")
+_QUOTE = re.compile(r"^\s*(?:>\s?)+")
+_TABLE_SEP = re.compile(r"^\s*\|?\s*:?-+:?\s*(?:\|\s*:?-+:?\s*)*\|?\s*$")
+_CELL_SPLIT = re.compile(r"(?<!\\)\|")
+_HEADING = re.compile(r"^\s{0,3}#{1,6}\s+(.+?)\s*#*\s*$")
+_RULE = re.compile(r"^\s*([-*_])(?:\s*\1){2,}\s*$")
+_TASK = re.compile(r"^(\s*)[-*+]\s+\[([ xX])\]\s*(.*)$")
+_BULLET = re.compile(r"^(\s*)[-*+]\s+(.*)$")
+_NUMBERED = re.compile(r"^(\s*)(\d+)[.)]\s+(.*)$")
+_TOKEN = re.compile(
+    r"`[^`\n]+`|\[\[[^\]\n]+\]\]|!?\[[^\]]*\]\((?:https?|tg)://[^)\s]+\)"
+)
+_WIKILINK = re.compile(r"\[\[([^\]|#]+)(?:#([^\]|]+))?(?:\|([^\]]+))?\]\]")
+_LINK = re.compile(r"(!?)\[([^\]]*)\]\(([^)\s]+)\)")
+_BOLD = re.compile(r"\*\*(.+?)\*\*|__(.+?)__")
 _ITALIC = re.compile(r"(?<![\w*])\*(?!\s)(.+?)(?<!\s)\*(?![\w*])")
 _ITALIC_U = re.compile(r"(?<![\w_])_(?!\s)(.+?)(?<!\s)_(?![\w_])")
-_LINK = re.compile(r"\[([^\]]+)\]\((https?://[^)\s]+)\)")
-_BULLET = re.compile(r"^(\s*)[-*]\s+", re.MULTILINE)
 _STRIKE = re.compile(r"~~(.+?)~~")
+_SPOILER = re.compile(r"\|\|(.+?)\|\|")
 
-_LABELS: dict[str, str] = {
+
-    "Read": "читаю vault",
+_Kind = Literal["fence", "quote", "table", "text"]
-    "Glob": "ищу файлы",
+
-    "Grep": "ищу в vault",
+
-    "Edit": "правлю файл",
+@dataclass(slots=True)
-    "Write": "пишу файл",
+class _Block:
-    "MultiEdit": "правлю файлы",
+    kind: _Kind
-    "Bash": "выполняю команду",
+    lines: list[str]
-    "WebSearch": "ищу в сети",
-    "WebFetch": "читаю страницу",
-    "Task": "запустил сабагента",
-    "Agent": "запустил сабагента",
-    "AskUserQuestion": "спрашиваю",
-    "TodoWrite": "планирую",
-    "Skill": "открываю скилл",
-    "mcp__gateway__spawn": "открываю разговор",
-    "mcp__gateway__read_conversation": "читаю разговор",
-    "mcp__gateway__say": "говорю",
-    "mcp__gateway__schedule": "ставлю напоминание",
-    "mcp__gateway__inject": "передаю в другой разговор",
-}
 
 
 def to_html(text: str) -> str:
-    out: list[str] = []
+    return "\n".join(_render(block) for block in _blocks(text)).strip()
-    pos = 0
-    for match in _FENCE.finditer(text):
-        out.append(_inline(text[pos : match.start()]))
-        out.append(f"<pre>{html.escape(match.group(1).rstrip())}</pre>")
-        pos = match.end()
-    out.append(_inline(text[pos:]))
-    return "".join(out).strip()
 
 
-def _inline(text: str) -> str:
+def to_html_tail(text: str, tail_chars: int) -> str:
-    parts = _INLINE_CODE.split(text)
+    start = max(len(text) - tail_chars, 0)
-    for i, part in enumerate(parts):
+    if start:
-        if i % 2:
+        newline = text.find("\n", start, start + _SNAP)
-            parts[i] = f"<code>{html.escape(part[1:-1])}</code>"
+        if newline >= 0:
-            continue
+            start = newline + 1
-        s = html.escape(part, quote=False)
+    opening = _open_fence(text[:start])
-        s = _HEADING.sub(r"<b>\1</b>", s)
+    tail = text[start:]
-        s = _BOLD.sub(lambda m: f"<b>{m.group(1) or m.group(2)}</b>", s)
+    return to_html(f"{opening}\n{tail}" if opening else tail)
-        s = _ITALIC.sub(r"<i>\1</i>", s)
-        s = _ITALIC_U.sub(r"<i>\1</i>", s)
-        s = _STRIKE.sub(r"<s>\1</s>", s)
-        s = _LINK.sub(r'<a href="\2">\1</a>', s)
-        parts[i] = _BULLET.sub(r"\1• ", s)
-    return "".join(parts)
 
 
 def chunks(text: str, limit: int = LIMIT) -> list[str]:
     text = text.strip()
-    if len(text) <= limit:
+    if not text:
-        return [text] if text else []
+        return []
+    if _fits(text, limit):
+        return [text]
     out: list[str] = []
-    while len(text) > limit:
+    cur: list[str] = []
-        cut = _cut_point(text, limit)
+    for block in _blocks(text):
-        out.append(text[:cut].rstrip())
+        for piece in _pieces(block, limit):
-        text = text[cut:].lstrip()
+            if cur and not _fits("\n".join([*cur, piece]), limit):
-    if text:
+                _flush(out, cur)
-        out.append(text)
+            cur.append(piece)
+    _flush(out, cur)
     return out
 
 
-def _cut_point(text: str, limit: int) -> int:
+def status_label(
-    for sep in ("\n\n", "\n", ". ", " "):
+    name: str,
-        cut = text.rfind(sep, limit // 2, limit)
+    tool_input: dict[str, Any] | None = None,
-        if cut > 0:
+    labels: Mapping[str, str] | None = None,
-            return cut + len(sep)
+) -> str:
-    return limit
+    label = (labels if labels is not None else TOOL_LABELS).get(name)
-
-
-def status_label(name: str, tool_input: dict[str, Any] | None = None) -> str:
-    label = _LABELS.get(name)
     if label is not None:
         return label
     if name.startswith("mcp__"):
@@ -109,3 +102,245 @@ def status_label(name: str, tool_input: dict[str, Any] | None = None) -> str:
                 hint = value.strip().splitlines()[0][:60]
                 break
     return f"{name} {hint}" if hint else name
+
+
+def _blocks(text: str) -> list[_Block]:
+    lines = text.split("\n")
+    blocks: list[_Block] = []
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        if _FENCE_OPEN.match(line):
+            j = i + 1
+            while j < len(lines) and not _FENCE_CLOSE.match(lines[j]):
+                j += 1
+            end = min(j + 1, len(lines))
+            blocks.append(_Block("fence", lines[i:end]))
+            i = end
+        elif _QUOTE.match(line):
+            j = i + 1
+            while j < len(lines) and _QUOTE.match(lines[j]):
+                j += 1
+            blocks.append(_Block("quote", lines[i:j]))
+            i = j
+        elif _is_table_start(lines, i):
+            j = i + 2
+            while j < len(lines) and "|" in lines[j] and lines[j].strip():
+                j += 1
+            blocks.append(_Block("table", lines[i:j]))
+            i = j
+        elif not line.strip():
+            blocks.append(_Block("text", [line]))
+            i += 1
+        else:
+            j = i + 1
+            while j < len(lines) and _is_plain(lines, j):
+                j += 1
+            blocks.append(_Block("text", lines[i:j]))
+            i = j
+    return blocks
+
+
+def _is_table_start(lines: list[str], i: int) -> bool:
+    if "|" not in lines[i] or i + 1 >= len(lines):
+        return False
+    sep = lines[i + 1]
+    return "|" in sep and _TABLE_SEP.match(sep) is not None
+
+
+def _is_plain(lines: list[str], i: int) -> bool:
+    line = lines[i]
+    return bool(
+        line.strip()
+        and not _FENCE_OPEN.match(line)
+        and not _QUOTE.match(line)
+        and not _is_table_start(lines, i)
+    )
+
+
+def _open_fence(text: str) -> str | None:
+    opening: str | None = None
+    for line in text.split("\n"):
+        if opening is None:
+            if _FENCE_OPEN.match(line):
+                opening = line
+        elif _FENCE_CLOSE.match(line):
+            opening = None
+    return opening
+
+
+def _render(block: _Block) -> str:
+    if block.kind == "fence":
+        return _render_fence(block.lines)
+    if block.kind == "quote":
+        body = "\n".join(_line(_QUOTE.sub("", line, 1)) for line in block.lines)
+        return f"<blockquote>{body}</blockquote>" if body.strip() else ""
+    if block.kind == "table":
+        return _render_table(block.lines)
+    return "\n".join(_line(line) for line in block.lines)
+
+
+def _fence_parts(lines: list[str]) -> tuple[str, list[str]]:
+    body = lines[1:]
+    if body and _FENCE_CLOSE.match(body[-1]):
+        body = body[:-1]
+    return lines[0], body
+
+
+def _render_fence(lines: list[str]) -> str:
+    head, body = _fence_parts(lines)
+    code = html.escape("\n".join(body).rstrip())
+    if not code:
+        return ""
+    lang = _language(head)
+    if lang:
+        return f'<pre><code class="language-{lang}">{code}</code></pre>'
+    return f"<pre>{code}</pre>"
+
+
+def _language(head: str) -> str:
+    match = _FENCE_OPEN.match(head)
+    info = match.group(1).strip() if match else ""
+    token = info.split()[0] if info else ""
+    return token if _LANG.fullmatch(token) else ""
+
+
+def _render_table(lines: list[str]) -> str:
+    rows = [_cells(line) for i, line in enumerate(lines) if i != 1]
+    width = max(len(row) for row in rows)
+    rows = [[*row, *[""] * (width - len(row))] for row in rows]
+    widths = [max(len(row[c]) for row in rows) for c in range(width)]
+    text = "\n".join(_table_row(row, widths) for row in rows)
+    return f"<pre>{html.escape(text)}</pre>"
+
+
+def _table_row(row: list[str], widths: list[int]) -> str:
+    cells = (cell.ljust(w) for cell, w in zip(row, widths, strict=True))
+    return " | ".join(cells).rstrip(" |")
+
+
+def _cells(line: str) -> list[str]:
+    inner = line.strip()
+    inner = inner.removeprefix("|").removesuffix("|")
+    return [cell.strip().replace("\\|", "|") for cell in _CELL_SPLIT.split(inner)]
+
+
+def _line(line: str) -> str:
+    if _RULE.match(line):
+        return "———"
+    if match := _HEADING.match(line):
+        return f"<b>{_inline(match.group(1))}</b>"
+    if match := _TASK.match(line):
+        box = "☐" if match.group(2) == " " else "☑"
+        return f"{match.group(1)}{box} {_inline(match.group(3))}"
+    if match := _BULLET.match(line):
+        return f"{match.group(1)}• {_inline(match.group(2))}"
+    if match := _NUMBERED.match(line):
+        return f"{match.group(1)}{match.group(2)}. {_inline(match.group(3))}"
+    return _inline(line)
+
+
+def _inline(text: str) -> str:
+    out: list[str] = []
+    pos = 0
+    for match in _TOKEN.finditer(text):
+        out.append(_format(text[pos : match.start()]))
+        out.append(_token(match.group()))
+        pos = match.end()
+    out.append(_format(text[pos:]))
+    return "".join(out)
+
+
+def _token(token: str) -> str:
+    if token.startswith("`"):
+        return f"<code>{html.escape(token[1:-1])}</code>"
+    if token.startswith("[["):
+        return _wikilink(token)
+    match = _LINK.fullmatch(token)
+    if match is None:
+        return html.escape(token, quote=False)
+    href = html.escape(match.group(3), quote=True)
+    label = _format(match.group(2)) or href
+    return f'<a href="{href}">{label}</a>'
+
+
+def _wikilink(token: str) -> str:
+    match = _WIKILINK.fullmatch(token)
+    if match is None:
+        return html.escape(token, quote=False)
+    note, heading, alias = (g.strip() if g else "" for g in match.groups())
+    label = alias or (f"{note} › {heading}" if heading else note)  # noqa: RUF001
+    return f"<u>{html.escape(label, quote=False)}</u>"
+
+
+def _format(text: str) -> str:
+    s = html.escape(text, quote=False)
+    s = _BOLD.sub(lambda m: f"<b>{m.group(1) or m.group(2)}</b>", s)
+    s = _ITALIC.sub(r"<i>\1</i>", s)
+    s = _ITALIC_U.sub(r"<i>\1</i>", s)
+    s = _STRIKE.sub(r"<s>\1</s>", s)
+    return _SPOILER.sub(r"<tg-spoiler>\1</tg-spoiler>", s)
+
+
+def _fits(text: str, limit: int) -> bool:
+    return len(to_html(text)) <= limit
+
+
+def _flush(out: list[str], cur: list[str]) -> None:
+    chunk = "\n".join(cur).strip()
+    if chunk:
+        out.append(chunk)
+    cur.clear()
+
+
+def _pieces(block: _Block, limit: int) -> list[str]:
+    whole = "\n".join(block.lines)
+    if _fits(whole, limit):
+        return [whole]
+    if block.kind == "fence":
+        head, body = _fence_parts(block.lines)
+        return _pack(body, lambda ls: "\n".join([head, *ls, "```"]), limit)
+    if block.kind == "quote":
+        inner = [_QUOTE.sub("", line, 1) for line in block.lines]
+        return _pack(inner, lambda ls: "\n".join(f"> {s}" for s in ls), limit)
+    if block.kind == "table":
+        header = block.lines[:2]
+        return _pack(block.lines[2:], lambda ls: "\n".join(header + ls), limit)
+    return _pack(block.lines, "\n".join, limit)
+
+
+def _pack(lines: list[str], wrap: Callable[[list[str]], str], limit: int) -> list[str]:
+    pieces: list[str] = []
+    cur: list[str] = []
+    for line in lines:
+        if cur and not _fits(wrap([*cur, line]), limit):
+            pieces.append(wrap(cur))
+            cur = []
+        if _fits(wrap([line]), limit):
+            cur.append(line)
+        else:
+            pieces.extend(wrap([part]) for part in _shatter(line, wrap, limit))
+    if cur:
+        pieces.append(wrap(cur))
+    return pieces
+
+
+def _shatter(line: str, wrap: Callable[[list[str]], str], limit: int) -> list[str]:
+    parts: list[str] = []
+    while line:
+        cut = len(line)
+        while cut > 1 and not _fits(wrap([line[:cut].rstrip()]), limit):
+            rendered = len(to_html(wrap([line[:cut]])))
+            cut = min(cut - 1, _cut_point(line, max(1, cut * limit // rendered)))
+        if part := line[:cut].rstrip():
+            parts.append(part)
+        line = line[cut:].lstrip()
+    return parts
+
+
+def _cut_point(text: str, limit: int) -> int:
+    for sep in ("\n\n", "\n", ". ", " "):
+        cut = text.rfind(sep, limit // 2, limit)
+        if cut > 0:
+            return cut + len(sep)
+    return limit

src/beaver_gateway/frontends/telegram/texts.py

@@ -0,0 +1,106 @@
+"""Every string the Telegram frontend shows the user; English defaults, overridable."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+__all__ = ["TOOL_LABELS", "TelegramTexts"]
+
+TOOL_LABELS: dict[str, str] = {
+    "Read": "reading",
+    "Glob": "looking for files",
+    "Grep": "searching",
+    "Edit": "editing a file",
+    "Write": "writing a file",
+    "MultiEdit": "editing files",
+    "Bash": "running a command",
+    "WebSearch": "searching the web",
+    "WebFetch": "reading a page",
+    "Task": "started a subagent",
+    "Agent": "started a subagent",
+    "AskUserQuestion": "asking",
+    "TodoWrite": "planning",
+    "Skill": "opening a skill",
+    "mcp__gateway__spawn": "opening a conversation",
+    "mcp__gateway__read_conversation": "reading a conversation",
+    "mcp__gateway__say": "speaking",
+    "mcp__gateway__schedule": "setting a reminder",
+    "mcp__gateway__inject": "passing to another conversation",
+    "mcp__gateway__send_file": "sending a file",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class TelegramTexts:
+    commands: tuple[tuple[str, str], ...] = (
+        ("merge", "merge this branch into the master"),
+        ("new", "new branch: in General a new topic, in a topic a fresh one here"),
+        ("chat", "open a deep chat in the vault: /chat topic"),
+        ("status", "this conversation"),
+        ("help", "commands"),
+    )
+    help_head: str = "General is the master, any other topic is a branch."
+    branch: str = "branch"
+    closed_prefix: str = "✅ "
+    waiting: str = "⏳ thinking"
+    thinking: str = "🤔 thinking"
+    writing: str = "✍️ writing"
+    tool: str = "⏳ {label}"
+    tool_labels: dict[str, str] = field(default_factory=lambda: dict(TOOL_LABELS))
+    attachment_sticker: str = "[attachment: sticker - not supported]"
+    attachment_animation: str = "[attachment: animation - not supported]"
+    attachment_kinds: dict[str, str] = field(
+        default_factory=lambda: {
+            "photo": "photo",
+            "document": "file",
+            "voice": "voice message",
+            "audio": "audio",
+            "video": "video",
+            "video_note": "video note",
+        }
+    )
+    attachment_too_big: str = (
+        "[attachment: {kind} {name}, {mb} MB - over 20 MB, Telegram does not "
+        "serve it to bots]"
+    )
+    attachment_failed: str = "[attachment: {kind} {name} - download failed: {error}]"
+    attachment_size: str = ", {kb} KB"
+    attachment: str = "[attachment: {kind} {path}{size}]"
+    attachment_kept: str = (
+        "[attachment: {kind} {path}{size}; kept {days} days, move it into the "
+        "vault if it matters]"
+    )
+    merge_nothing: str = "nothing to merge: this is not an open branch"
+    merging: str = "🔀 merging into the master"
+    merged: str = "✅ merged into the master"
+    merge_failed: str = "⚠️ merge failed: {error}"
+    new_branch_topic: str = "🌿 branch «{title}» - in a new topic"
+    new_branch_here: str = "🌿 new branch on this topic"
+    chat_usage: str = "/chat <topic>"
+    chat_failed: str = "could not open: {error}"
+    chat_opened: str = "💬 deep chat: {where}"
+    status_unbound: str = "this topic is bound to nothing - write, and a branch opens"
+    status_line: str = "session: {live} · turn: {turn} · queued: {queued}"
+    status_live: str = "live"
+    status_dead: str = "none"
+    status_running: str = "running"
+    status_idle: str = "idle"
+    status_question: str = "❓ waiting for an answer"
+    status_pool: str = "pool: {sessions} sessions, rss {mb} MB"
+    status_outbox: str = "outbox: {pending} queued"
+    turn_failed: str = "⚠️ the turn failed, see the gateway logs"
+    background_failed: str = (
+        "⚠️ a background turn ({origin}) failed, see the gateway logs"
+    )
+    question_closed: str = "the question is already closed"
+    question_timeout: str = "⌛ time is up - answer as text"
+    question_answered: str = "✅ {answer}"
+    question_typed: str = "✍️ {text}"
+    done_button: str = "✅ done"
+    mirrored: str = "📝 from the panel:\n{text}"
+
+    @property
+    def help(self) -> str:
+        return (
+            self.help_head + "\n" + "\n".join(f"/{c} - {d}" for c, d in self.commands)
+        )

src/beaver_gateway/frontends/turn_record.py

@@ -0,0 +1,95 @@
+"""Cross-frontend turn record.
+
+Frontends emit a :class:`TurnRecord` to every handler in
+``GatewayRuntime.turn_log_handlers`` after a turn finishes.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from anthropic.types import Message, MessageParam
+
+
+__all__ = ["TurnRecord", "slugify"]
+
+
+_SLUG_BAD_RE = re.compile(r"[^\w\s\-]+", flags=re.UNICODE)
+_SLUG_SEP_RE = re.compile(r"[\s\-]+", flags=re.UNICODE)
+
+
+def slugify(text: str, *, maxlen: int = 40) -> str:
+    """Sanitize ``text`` for use as a filename fragment.
+
+    Truncates to ``maxlen`` and returns ``"untitled"`` for empty input.
+    """
+    cleaned = _SLUG_BAD_RE.sub(" ", text).strip()
+    cleaned = _SLUG_SEP_RE.sub("-", cleaned).strip("-")
+    if not cleaned:
+        return "untitled"
+    if len(cleaned) > maxlen:
+        cleaned = cleaned[:maxlen].rstrip("-")
+    return cleaned or "untitled"
+
+
+@dataclass(frozen=True, slots=True)
+class TurnRecord:
+    """One completed turn, as seen by a frontend.
+
+    ``input_messages`` excludes the assistant reply; ``source`` names the
+    producing frontend so a cross-frontend logger can skip its own turns.
+    """
+
+    agent_name: str
+    input_messages: list[MessageParam]
+    output_message: Message
+    system: str | None = None
+    source: str = "anthropic"
+
+    @property
+    def first_user_text(self) -> str:
+        """Empty string if the input history has no user turn."""
+        for msg in self.input_messages:
+            if msg.get("role") == "user":
+                return _text_of(msg.get("content", ""))
+        return ""
+
+    @property
+    def last_user_text(self) -> str:
+        for msg in reversed(self.input_messages):
+            if msg.get("role") == "user":
+                return _text_of(msg.get("content", ""))
+        return ""
+
+    @property
+    def assistant_text(self) -> str:
+        """Plain text of the assistant reply, with thinking/tool blocks dropped."""
+        chunks = [
+            getattr(block, "text", "") or ""
+            for block in getattr(self.output_message, "content", ())
+            if getattr(block, "type", None) == "text"
+        ]
+        return "\n\n".join(c for c in chunks if c)
+
+
+def _text_of(content: object) -> str:
+    """Flatten an Anthropic ``MessageParam.content`` field to a plain string.
+
+    Handles both raw-string and block-list shapes; unrecognized content is
+    silently skipped since this exists for naming, not faithful reconstruction.
+    """
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts: list[str] = []
+        for blk in content:
+            if not isinstance(blk, dict):
+                continue
+            d: Any = blk
+            if d.get("type") == "text":
+                parts.append(str(d.get("text", "")))
+        return "\n\n".join(p for p in parts if p)
+    return ""

src/beaver_gateway/frontends/urls.py

@@ -0,0 +1,30 @@
+"""Where a frontend is reachable from outside, as seen by one request."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from starlette.requests import Request
+
+    from beaver_gateway.frontends.base import Frontend, GatewayRuntime
+
+
+def request_origin(request: Request, runtime: GatewayRuntime) -> str:
+    """``Gateway.public_url`` if configured, else the request's own origin."""
+    if runtime.public_url:
+        return runtime.public_url
+    host = request.headers.get("host")
+    if not host:
+        return f"http://{request.url.hostname}:{request.url.port}"
+    scheme = request.headers.get("x-forwarded-proto") or request.url.scheme
+    return f"{scheme}://{host}"
+
+
+def external_base(request: Request, runtime: GatewayRuntime) -> str:
+    """Origin plus the mount path of the app handling ``request``."""
+    return request_origin(request, runtime) + str(request.scope.get("root_path", ""))
+
+
+def frontend_url(request: Request, runtime: GatewayRuntime, fe: Frontend) -> str | None:
+    return request_origin(request, runtime) + fe.path if fe.path else None

src/beaver_gateway/jobs/__init__.py

@@ -0,0 +1 @@
+"""Cron, webhook and event jobs, deferred injects, the subscription budget."""

src/beaver_gateway/jobs/job.py

@@ -0,0 +1,126 @@
+"""What a job is: its triggers, the budget it respects, and what a run may do."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable, Coroutine
+
+    from beaver_gateway.conversations.distill import LineCap
+    from beaver_gateway.conversations.injects import Priority
+    from beaver_gateway.conversations.service import Conversations, DistillResult
+    from beaver_gateway.jobs.scheduler import Scheduler
+    from beaver_gateway.storage.models import Conversation
+
+__all__ = ["Budget", "Job", "JobRun"]
+
+_log = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True, slots=True)
+class Job:
+    name: str
+    run: Callable[[JobRun], Awaitable[None]]
+    cron: str | None = None
+    webhook: bool = False
+    events: tuple[str, ...] = ()
+    critical: bool = True
+    dedupe: bool = True
+
+    @property
+    def entrypoint(self) -> str:
+        return f"job:{self.name}"
+
+
+@dataclass(frozen=True, slots=True)
+class Budget:
+    threshold: float = 0.7
+    tokens: int | None = None
+    window: timedelta = timedelta(hours=5)
+    limit_window: str = "five_hour"
+
+
+@dataclass(slots=True)
+class JobRun:
+    job: Job
+    trigger: str
+    payload: dict[str, Any]
+    scheduler: Scheduler
+
+    @property
+    def conversations(self) -> Conversations:
+        return self.scheduler.conversations
+
+    async def master(self) -> Conversation | None:
+        masters = await self.conversations.find(kind="master", status="open", limit=1)
+        return masters[0] if masters else None
+
+    async def inject_master(
+        self, text: str, *, urgency: Priority = "normal", origin: str | None = None
+    ) -> bool:
+        master = await self.master()
+        if master is None:
+            _log.error(
+                "job %s: no open master, inject lost: %s", self.job.name, text[:200]
+            )
+            return False
+        await self.conversations.inject(
+            master, text, urgency=urgency, origin=origin or self.job.name
+        )
+        return True
+
+    async def spawn_job(
+        self,
+        *,
+        agent: str,
+        text: str,
+        title: str | None = None,
+        line_cap: LineCap | None = None,
+    ) -> Conversation:
+        """A headless job turn; ``line_cap`` bounces a rewrite past the cap."""
+        return await self.conversations.spawn(
+            kind="job",
+            agent=agent,
+            seed="brief",
+            text=text,
+            title=title,
+            origin="job",
+            flags={"line_cap": line_cap.as_flags()} if line_cap else None,
+        )
+
+    async def close_idle(
+        self,
+        *,
+        kind: str = "deep",
+        days: int = 2,
+        limit: int = 3,
+        since: datetime | None = None,
+    ) -> list[DistillResult]:
+        """Close chats quiet for ``days``, at most ``limit`` per run."""
+        out: list[DistillResult] = []
+        for conv in await self.conversations.idle(
+            kind=kind, days=days, since=since, limit=limit
+        ):
+            try:
+                out.append(
+                    await self.conversations.distill(conv, reason=f"idle {days}d")
+                )
+            except Exception:  # noqa: BLE001
+                _log.exception("closing idle %s failed", conv.external_id)
+        return out
+
+    async def retry_in(self, delay: timedelta) -> None:
+        await self.scheduler.trigger(
+            self.job, self.payload, delay=delay, trigger=self.trigger
+        )
+
+    async def rotate(self) -> list[Conversation]:
+        rotation = self.scheduler.rotation
+        return await rotation.tick() if rotation is not None else []
+
+    def background(self, coro: Coroutine[Any, Any, Any]) -> None:
+        self.scheduler.background(coro)

src/beaver_gateway/jobs/scheduler.py

@@ -0,0 +1,494 @@
+"""Jobs and deferred injects on pgqueuer.
+
+A job is a name, a handler and its triggers (cron, webhook, bus events); a
+handler only queues work, and the turn itself runs in the conversation's worker.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import functools
+import json
+import logging
+import traceback
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta, tzinfo
+from typing import TYPE_CHECKING, Any, cast
+from zoneinfo import ZoneInfo
+
+from croniter import croniter
+from pgqueuer import PgQueuer, Queries
+from pgqueuer.core.executors import ScheduleExecutor
+from pgqueuer.models import JobId
+from sqlalchemy import func
+from sqlmodel import col, select
+from starlette.applications import Starlette
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+
+from beaver_gateway.conversations.service import parse_at
+from beaver_gateway.jobs.job import Budget, Job, JobRun
+from beaver_gateway.storage.models import JobRunRecord
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable, Coroutine, Sequence
+
+    from pgqueuer.models import Job as PgJob
+    from pgqueuer.models import Schedule as PgSchedule
+    from pgqueuer.ports.driver import Driver
+    from starlette.requests import Request
+
+    from beaver_gateway.conversations.injects import Priority
+    from beaver_gateway.conversations.rotation import Rotation
+    from beaver_gateway.conversations.service import Conversations
+    from beaver_gateway.storage.models import Conversation
+
+__all__ = ["INJECT", "Budget", "Job", "JobRun", "LocalCron", "Scheduler", "next_run"]
+
+_log = logging.getLogger("beaver_gateway.jobs.scheduler")
+
+INJECT = "inject"
+RETRY = timedelta(minutes=15)
+ERROR_MAX = 2000
+
+
+def next_run(expression: str, tz: tzinfo, now: datetime | None = None) -> datetime:
+    """The cron's next fire time, read in ``tz``, returned in UTC."""
+    start = (now or datetime.now(UTC)).astimezone(tz)
+    return croniter(expression, start_time=start).get_next(datetime).astimezone(UTC)
+
+
+@dataclass
+class LocalCron(ScheduleExecutor):
+    tz: tzinfo = UTC
+
+    def get_next(self) -> datetime:
+        return next_run(self.parameters.expression, self.tz)
+
+
+class Scheduler:
+    def __init__(
+        self,
+        *,
+        conversations: Conversations,
+        jobs: Sequence[Job] = (),
+        driver: Driver | None = None,
+        budget: Budget | None = None,
+        rotation: Rotation | None = None,
+        heartbeat: timedelta = timedelta(seconds=30),
+        tz: str = "UTC",
+    ) -> None:
+        self.conversations = conversations
+        self.rotation = rotation
+        self.tz = ZoneInfo(tz)
+        self.budget = budget or Budget()
+        self._jobs = {job.name: job for job in jobs}
+        self._driver = driver
+        self._queries: Queries | None = None
+        self._heartbeat = heartbeat
+        self._tasks: set[asyncio.Task[Any]] = set()
+        self._runs: dict[str, dict[str, Any]] = {}
+
+    @property
+    def enabled(self) -> bool:
+        return self._queries is not None
+
+    @property
+    def jobs(self) -> list[Job]:
+        return list(self._jobs.values())
+
+    def job(self, name: str) -> Job | None:
+        return self._jobs.get(name)
+
+    async def start(self) -> None:
+        if self._driver is not None:
+            queries = Queries(self._driver)
+            if not await queries.has_table("pgqueuer"):
+                await queries.install()
+            pgq = PgQueuer(self._driver, queries=queries)
+            self._register(pgq)
+            self._queries = queries
+            self._spawn(pgq.run(heartbeat_timeout=self._heartbeat))
+        else:
+            _log.warning("scheduler: no postgres driver - cron and webhooks are off")
+        self._spawn(self._events())
+
+    async def stop(self) -> None:
+        for task in list(self._tasks):
+            task.cancel()
+        for task in list(self._tasks):
+            with contextlib.suppress(BaseException):
+                await task
+        self._tasks.clear()
+        self._queries = None
+
+    def _register(self, pgq: PgQueuer) -> None:
+        @pgq.entrypoint(INJECT)
+        async def deliver(job: PgJob) -> None:
+            await self._deliver(job)
+
+        for job in self._jobs.values():
+            self._register_job(pgq, job)
+
+    def _register_job(self, pgq: PgQueuer, job: Job) -> None:
+        @pgq.entrypoint(job.entrypoint)
+        async def queued(pg_job: PgJob) -> None:
+            data = _decode(pg_job.payload)
+            await self._dispatch(
+                job, trigger=str(data.pop("trigger", "queue")), payload=data
+            )
+
+        if job.cron:
+
+            @pgq.schedule(
+                job.name,
+                job.cron,
+                clean_old=True,
+                executor_factory=functools.partial(LocalCron, tz=self.tz),
+            )
+            async def cron(_schedule: PgSchedule) -> None:
+                await self._dispatch(job, trigger="cron", payload={})
+
+    async def _events(self) -> None:
+        listeners = [job for job in self._jobs.values() if job.events]
+        if not listeners:
+            return
+        async for event in self.conversations.bus.stream():
+            for job in listeners:
+                if event.get("type") in job.events:
+                    self._spawn(
+                        self._dispatch(job, trigger="event", payload=dict(event))
+                    )
+
+    async def _dispatch(
+        self, job: Job, *, trigger: str, payload: dict[str, Any]
+    ) -> None:
+        bus = self.conversations.bus
+        if not job.critical and await self.throttled():
+            bus.publish("job.deferred", job=job.name, trigger=trigger)
+            if trigger != "cron":
+                await self.trigger(job, payload, delay=RETRY, trigger=trigger)
+            return
+        started = datetime.now(UTC)
+        bus.publish("job.start", job=job.name, trigger=trigger)
+        status, error = "done", None
+        try:
+            await job.run(JobRun(job, trigger, payload, self))
+        except Exception as exc:  # noqa: BLE001
+            status, error = "failed", _error_text(exc)
+            _log.exception("job %s (%s) failed", job.name, trigger)
+        record = JobRunRecord(
+            job=job.name,
+            trigger=trigger,
+            started_at=started,
+            finished_at=datetime.now(UTC),
+            status=status,
+            error=error,
+            payload=payload,
+        )
+        await self._record(record)
+        self._runs[job.name] = self._run_public(record)
+        bus.publish("job.end", job=job.name, trigger=trigger, status=status)
+
+    async def _record(self, record: JobRunRecord) -> None:
+        try:
+            async with self.conversations.db.session() as session:
+                session.add(record)
+                await session.commit()
+        except Exception:  # noqa: BLE001
+            _log.exception("job %s: run not recorded", record.job)
+
+    async def trigger(
+        self,
+        job: Job,
+        payload: dict[str, Any] | None = None,
+        *,
+        delay: timedelta | None = None,
+        trigger: str = "manual",
+    ) -> int | None:
+        """Queue one run of ``job``; runs inline when there is no executor."""
+        data = {**(payload or {}), "trigger": trigger}
+        if self._queries is None:
+            self._spawn(
+                self._dispatch(job, trigger=trigger, payload=payload or {}), delay=delay
+            )
+            return None
+        ids = await self._queries.enqueue(
+            job.entrypoint, _encode(data), execute_after=delay
+        )
+        return int(ids[0]) if ids and ids[0] is not None else None
+
+    async def hook(self, name: str, payload: dict[str, Any]) -> int | None:
+        job = self._jobs.get(name)
+        if job is None or not job.webhook:
+            msg = f"no webhook job {name!r}"
+            raise LookupError(msg)
+        self.conversations.bus.publish("hook", job=name)
+        if self._queries is None:
+            return await self.trigger(job, payload, trigger="webhook")
+        ids = await self._queries.enqueue(
+            job.entrypoint,
+            _encode({**payload, "trigger": "webhook"}),
+            dedupe_key=f"hook:{name}" if job.dedupe else None,
+            on_conflict="skip" if job.dedupe else "raise",
+        )
+        return int(ids[0]) if ids and ids[0] is not None else None
+
+    async def schedule(
+        self,
+        conv: Conversation,
+        at: str,
+        text: str,
+        *,
+        urgency: Priority = "wake",
+        dedupe_key: str | None = None,
+    ) -> tuple[int | None, datetime]:
+        """A deferred inject.
+
+        ``wake`` by default: it was promised for a time, so it starts a turn
+        then instead of waiting for the normal window.
+        """
+        if self._queries is None:
+            msg = "scheduler needs postgres; `schedule` is unavailable"
+            raise RuntimeError(msg)
+        when = parse_at(at, self.tz).astimezone(self.tz)
+        delay = max(when - datetime.now(UTC), timedelta(0))
+        payload = _encode(
+            {
+                "conversation": conv.external_id,
+                "text": text,
+                "urgency": urgency,
+                "at": when.isoformat(timespec="minutes"),
+            }
+        )
+        ids = await self._queries.enqueue(
+            INJECT,
+            payload,
+            execute_after=delay,
+            dedupe_key=dedupe_key,
+            on_conflict="skip" if dedupe_key else "raise",
+        )
+        job_id = int(ids[0]) if ids and ids[0] is not None else None
+        self.conversations.bus.publish(
+            "schedule.created",
+            conversation_id=conv.external_id,
+            job=job_id,
+            execute_at=when.isoformat(timespec="minutes"),
+        )
+        return job_id, when
+
+    async def cancel(self, job_id: int) -> bool:
+        if self._queries is None:
+            return False
+        row = await self._queries.queue_job_by_id(JobId(job_id))
+        if row is None:
+            return False
+        await self._queries.mark_job_as_cancelled([JobId(job_id)])
+        self.conversations.bus.publish("schedule.cancelled", job=job_id)
+        return True
+
+    async def _deliver(self, job: PgJob) -> None:
+        data = _decode(job.payload)
+        key = str(data.get("conversation", ""))
+        conv = await self.conversations.resolve(key)
+        if conv is None:
+            _log.error(
+                "scheduled inject #%s lost: conversation %r is gone: %s",
+                job.id,
+                key,
+                str(data.get("text", ""))[:200],
+            )
+            return
+        await self.conversations.inject(
+            conv,
+            str(data.get("text", "")),
+            urgency=cast("Priority", data.get("urgency") or "wake"),
+            origin="schedule",
+        )
+
+    async def utilization(self) -> float | None:
+        now = datetime.now(UTC)
+        values: list[float] = []
+        for row in await self.conversations.rate_limits(limit=100):
+            if row.window != self.budget.limit_window or row.utilization is None:
+                continue
+            fresh = now - _aware(row.ts) < self.budget.window
+            live = row.resets_at is None or _aware(row.resets_at) > now
+            if fresh and live:
+                values.append(float(row.utilization))
+            break
+        if self.budget.tokens:
+            tokens = await self.conversations.usage_tokens(now - self.budget.window)
+            values.append(tokens / self.budget.tokens)
+        return max(values) if values else None
+
+    async def throttled(self) -> bool:
+        utilization = await self.utilization()
+        return utilization is not None and utilization > self.budget.threshold
+
+    async def snapshot(self) -> dict[str, Any]:
+        crons: dict[str, PgSchedule] = {}
+        queue: list[dict[str, Any]] = []
+        if self._queries is not None:
+            for row in await self._queries.peek_schedule():
+                crons[str(row.entrypoint)] = row
+            queue = [
+                _job_public(row, self.tz)
+                for row in await self._queries.browse_queue(limit=200)
+            ]
+        utilization = await self.utilization()
+        last = await self._last_runs()
+        return {
+            "enabled": self.enabled,
+            "tz": str(self.tz),
+            "utilization": utilization,
+            "throttled": utilization is not None
+            and utilization > self.budget.threshold,
+            "threshold": self.budget.threshold,
+            "jobs": [
+                self._job_public(job, crons.get(job.name), last.get(job.name))
+                for job in self.jobs
+            ],
+            "queue": queue,
+        }
+
+    async def scheduled(self, conv: Conversation | None = None) -> list[dict[str, Any]]:
+        if self._queries is None:
+            return []
+        rows = await self._queries.browse_queue(limit=500, entrypoints=[INJECT])
+        out = [_job_public(row, self.tz) for row in rows]
+        if conv is not None:
+            out = [
+                j for j in out if j["payload"].get("conversation") == conv.external_id
+            ]
+        return out
+
+    async def runs(self, name: str, limit: int = 50) -> list[dict[str, Any]]:
+        stmt = (
+            select(JobRunRecord)
+            .where(JobRunRecord.job == name)
+            .order_by(col(JobRunRecord.id).desc())
+            .limit(limit)
+        )
+        async with self.conversations.db.session() as session:
+            rows = (await session.exec(stmt)).all()
+        return [self._run_public(row) for row in rows]
+
+    async def _last_runs(self) -> dict[str, dict[str, Any]]:
+        newest = select(func.max(JobRunRecord.id)).group_by(JobRunRecord.job)
+        stmt = select(JobRunRecord).where(col(JobRunRecord.id).in_(newest))
+        try:
+            async with self.conversations.db.session() as session:
+                rows = (await session.exec(stmt)).all()
+        except Exception:  # noqa: BLE001
+            _log.exception("job runs unreadable, using memory")
+            return dict(self._runs)
+        return {row.job: self._run_public(row) for row in rows}
+
+    def _job_public(
+        self, job: Job, cron: PgSchedule | None, run: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        return {
+            "name": job.name,
+            "cron": job.cron,
+            "webhook": job.webhook,
+            "events": list(job.events),
+            "critical": job.critical,
+            "next_run": _iso(cron.next_run, self.tz) if cron is not None else None,
+            "last_run": _iso(cron.last_run, self.tz) if cron is not None else None,
+            "status": str(cron.status) if cron is not None else None,
+            "run": run or self._runs.get(job.name),
+        }
+
+    def _run_public(self, row: JobRunRecord) -> dict[str, Any]:
+        return {
+            "id": row.id,
+            "job": row.job,
+            "trigger": row.trigger,
+            "started_at": _iso(row.started_at, self.tz),
+            "finished_at": _iso(row.finished_at, self.tz),
+            "status": row.status,
+            "error": row.error,
+            "payload": row.payload,
+        }
+
+    def app(self, authorize: Callable[[Request], Awaitable[Any]]) -> Starlette:
+        async def hook(request: Request) -> JSONResponse:
+            await authorize(request)
+            name = request.path_params["name"]
+            payload = await _payload(request)
+            try:
+                job_id = await self.hook(name, payload)
+            except LookupError as exc:
+                return JSONResponse({"error": str(exc)}, status_code=404)
+            return JSONResponse({"job": job_id, "name": name}, status_code=202)
+
+        return Starlette(routes=[Route("/{name}", hook, methods=["POST"])])
+
+    def background(self, coro: Coroutine[Any, Any, Any]) -> None:
+        self._spawn(coro)
+
+    def _spawn(
+        self, coro: Coroutine[Any, Any, Any], *, delay: timedelta | None = None
+    ) -> None:
+        async def later() -> None:
+            if delay is not None:
+                await asyncio.sleep(delay.total_seconds())
+            await coro
+
+        task = asyncio.create_task(later() if delay is not None else coro)
+        self._tasks.add(task)
+        task.add_done_callback(self._tasks.discard)
+
+
+async def _payload(request: Request) -> dict[str, Any]:
+    body = await request.body()
+    if not body:
+        return dict(request.query_params)
+    try:
+        data = json.loads(body)
+    except ValueError:
+        return {"raw": body.decode("utf-8", errors="replace")}
+    return data if isinstance(data, dict) else {"raw": data}
+
+
+def _encode(data: dict[str, Any]) -> bytes:
+    return json.dumps(data, ensure_ascii=False, default=str).encode("utf-8")
+
+
+def _decode(payload: bytes | None) -> dict[str, Any]:
+    if not payload:
+        return {}
+    try:
+        data = json.loads(payload)
+    except ValueError:
+        return {"raw": payload.decode("utf-8", errors="replace")}
+    return data if isinstance(data, dict) else {"raw": data}
+
+
+def _job_public(row: PgJob, tz: tzinfo) -> dict[str, Any]:
+    return {
+        "id": int(row.id),
+        "entrypoint": row.entrypoint,
+        "status": str(row.status),
+        "execute_after": _iso(row.execute_after, tz),
+        "created": _iso(row.created, tz),
+        "attempts": row.attempts,
+        "payload": _decode(row.payload),
+    }
+
+
+def _error_text(exc: BaseException) -> str:
+    head = f"{type(exc).__name__}: {exc}"
+    return f"{head}\n{''.join(traceback.format_exception(exc))}"[:ERROR_MAX]
+
+
+def _aware(value: datetime) -> datetime:
+    return value if value.tzinfo is not None else value.replace(tzinfo=UTC)
+
+
+def _iso(value: datetime | None, tz: tzinfo = UTC) -> str | None:
+    if value is None:
+        return None
+    return _aware(value).astimezone(tz).isoformat(timespec="seconds")

src/beaver_gateway/mcp/__init__.py

@@ -1,4 +1,4 @@
-"""MCP server definitions and (later) the internal aggregator app."""
+"""MCP server definitions and the internal aggregator app."""
 
 from __future__ import annotations
 

src/beaver_gateway/mcp/client_pool.py

@@ -1,11 +1,7 @@
 """Proxy ``FastMCP`` servers for user-declared external MCPs (``stdio``/``http``).
 
-Both flavours end up as a ``FastMCPProxy`` instance, built via
+Built via ``fastmcp.server.create_proxy``; the proxy lazily opens its
-``fastmcp.server.create_proxy``. The proxy lazily opens the underlying
+transport on first request, so unused MCPs cost nothing until routed to.
-client transport when the first MCP request arrives, so we don't pay
-for connections that nothing routes to. From the aggregator app's
-point of view a proxy is indistinguishable from a regular ``FastMCP``
-namespace — same ``http_app`` surface, same mount semantics.
 """
 
 from __future__ import annotations

src/beaver_gateway/mcp/internal_app.py

@@ -1,26 +1,7 @@
 """Internal MCP aggregator — one ASGI app, N FastMCP namespaces + ``all``.
 
-Each ``McpServer`` declared in the user's config becomes its own
+Each ``McpServer`` in the user's config is mounted under ``/mcp/<name>``;
-``FastMCP`` instance (regular for ``python_tool``, ``FastMCPProxy`` for
+``/mcp/all/`` unions every namespace's tools for single-MCP clients.
-``stdio``/``http``) and is mounted under ``/mcp/<name>`` on a single
-Starlette app. This app runs on ``127.0.0.1:INTERNAL_MCP_PORT`` (not
-EXPOSE'd in Docker) so the ClaudeCode subprocess can reach each
-namespace via loopback as a distinct MCP server URL — preserving
-per-domain framing while costing only one process worth of RAM
-(PRD §6).
-
-Phase 3 adds ``/mcp/all/``: a single FastMCP whose tools are the union
-of every namespace's tools, prefixed by FastMCP's ``namespace_<tool>``
-convention (e.g. ``time_current_time``). It's the escape-hatch for
-clients that can only configure one MCP server — discouraged for tool-
-heavy setups (PRD §6 cites the ~95%→~71% tool-selection drop on flat
-namespaces) but real and reachable.
-
-The aggregator returns both the app and a ``{name: url}`` map; Phase
-``ClaudeSdkBackend`` plugs the map directly into
-``BackendOptions.mcp_servers``. ``/mcp/all/`` is NOT included in that
-map — claude-code-agents always get per-domain framing; only the
-external MCP frontend (Phase 3.1) reverse-proxies the flat endpoint.
 """
 
 from __future__ import annotations
@@ -33,6 +14,7 @@ from starlette.applications import Starlette
 from starlette.routing import Mount
 
 from beaver_gateway.mcp.client_pool import build_http_proxy, build_stdio_proxy
+from beaver_gateway.mcp.redacting import RedactingMiddleware
 from beaver_gateway.mcp.types import HttpMcp, PythonToolMcp, StdioMcp
 from beaver_gateway.mcp.wrap import build_python_tool_server
 
@@ -51,11 +33,13 @@ def build_internal_app(
 ) -> tuple[Starlette, dict[str, str], dict[str, FastMCP]]:
     """Build the aggregator ``Starlette`` app, per-namespace URL map, and server map.
 
-    ``host``/``port`` only flavour the URL strings handed back — actually
+    ``host``/``port`` only flavour the URL strings handed back; the
-    listening on them is the caller's job (``cli.main`` runs a uvicorn
+    caller (``cli.main``) is what actually listens on them. Published
-    server in a TaskGroup). We accept the address here so callers don't
+    URLs carry a trailing slash so ``Mount`` doesn't 307-redirect the
-    have to format the URLs themselves and risk drifting from the
+    first request. Each
-    ``/mcp/<name>`` convention.
+    namespace gets its own :class:`RedactingMiddleware` so a direct
+    ``call_tool`` on a child (e.g. the Raycast backend does that) is
+    filtered too, not just requests through the mounted app.
 
     Returns:
       * Starlette app to serve via uvicorn.
@@ -69,27 +53,28 @@ def build_internal_app(
         MCP tools into the Raycast wire).
     """
     servers: dict[str, FastMCP] = {spec.name: _build_server(spec) for spec in mcps}
+    for server in servers.values():
+        server.add_middleware(RedactingMiddleware())
 
     child_apps = {
         name: s.http_app(transport="http", path="/") for name, s in servers.items()
     }
     routes = [Mount(f"/mcp/{name}", app=app) for name, app in child_apps.items()]
 
-    # /mcp/all — flat-namespace bundle. Skip when there's nothing to
-    # bundle so we don't pay for an empty session manager lifecycle.
     all_app = None
     if servers:
         all_server = _build_all_server(servers)
+        all_server.add_middleware(RedactingMiddleware())
         all_app = all_server.http_app(transport="http", path="/")
         routes.append(Mount(f"/mcp/{ALL_NAMESPACE}", app=all_app))
 
     @asynccontextmanager
     async def lifespan(_parent: Starlette) -> AsyncIterator[None]:
-        # Each FastMCP http_app stores its session manager init in its
+        """Enter every child app's lifespan.
-        # own lifespan. Without entering them the streamable-HTTP layer
+
-        # 500s on every request. AsyncExitStack composes them so all
+        Without it the streamable-HTTP layer 500s on every request;
-        # children come up together and unwind in reverse order on
+        children unwind in reverse order.
-        # shutdown.
+        """
         async with AsyncExitStack() as stack:
             for child in child_apps.values():
                 await stack.enter_async_context(child.router.lifespan_context(child))
@@ -100,23 +85,22 @@ def build_internal_app(
             yield
 
     app = Starlette(routes=routes, lifespan=lifespan)
-    # Trailing slash on the published URL skips Starlette's
-    # 307 redirect from ``/mcp/<name>`` to ``/mcp/<name>/`` that
-    # ``Mount`` produces when a child route lives at ``/``.
     urls = {name: f"http://{host}:{port}/mcp/{name}/" for name in servers}
     return app, urls, servers
 
 
 def _build_server(spec: McpServerT) -> FastMCP:
-    """Dispatch on the discriminated union to the matching builder."""
+    """Dispatch on the discriminated union to the matching builder.
+
+    The final branch is unreachable while ``McpServerT`` stays closed;
+    it exists to keep type-narrowing honest if a variant is ever added.
+    """
     if isinstance(spec, PythonToolMcp):
         return build_python_tool_server(spec)
     if isinstance(spec, StdioMcp):
         return build_stdio_proxy(spec)
     if isinstance(spec, HttpMcp):
         return build_http_proxy(spec)
-    # `McpServerT` is a closed union; this is unreachable but keeps
-    # type-narrowing honest if a new variant lands without updates here.
     msg = f"unsupported McpServer variant: {type(spec).__name__}"
     raise TypeError(msg)
 

src/beaver_gateway/mcp/lenient.py

@@ -1,22 +1,8 @@
 """Tolerant transports for upstream MCPs that don't strictly speak JSON-RPC.
 
-Some real-world MCP servers print non-JSON chatter to stdout before / between
+Some MCP servers print non-JSON chatter to stdout (banners, dependency-load
-their actual JSON-RPC frames (``Processing...``, banners, dependency-load
+messages) that the reference client forwards as exceptions, which bleed into
-messages, etc.). The reference ``mcp.client.stdio.stdio_client`` parses every
+client UIs as warnings. This transport drops those lines instead.
-stdout line as JSON-RPC and ships any parse failure downstream as an
-exception, which the MCP ``ClientSession`` then logs as a warning that bleeds
-into client UIs (Cursor, Cline) when they connect through us.
-
-``LenientStdioTransport`` re-implements the stdio-client wiring with one
-behavioural change: lines that don't parse as JSON-RPC are *silently
-dropped* (one ``DEBUG`` log entry, no exception forwarded). Downstream
-consumers see only valid messages. We keep the rest of the contract identical
-to the reference client, including the spec-mandated graceful shutdown
-sequence (close stdin → wait → SIGTERM → SIGKILL).
-
-The transport plugs into ``fastmcp.server.create_proxy`` just like
-``StdioTransport`` does, so the rest of the aggregator doesn't need to
-know which flavour it got.
 """
 
 from __future__ import annotations
@@ -70,13 +56,15 @@ class LenientStdioTransport(ClientTransport):
         cwd: str | None = None,
         log_file: TextIO | None = None,
     ) -> None:
+        """``log_file`` takes an already-open ``TextIO``.
+
+        Unlike the upstream transport, this one does not open a ``Path``
+        for you.
+        """
         self.command = command
         self.args = args
         self.env = env
         self.cwd = cwd
-        # TextIO only — pre-open Path callers themselves. The upstream
-        # ``StdioTransport`` opens Path for you, but we keep this thin so
-        # the type contract stays narrow and easy to validate.
         self.log_file = log_file
 
     @contextlib.asynccontextmanager
@@ -100,7 +88,7 @@ class LenientStdioTransport(ClientTransport):
 
 
 @contextlib.asynccontextmanager
-async def _lenient_stdio_client(  # noqa: PLR0915 — mirrors mcp.client.stdio.stdio_client
+async def _lenient_stdio_client(  # noqa: PLR0915
     server: StdioServerParameters, errlog: TextIO = sys.stderr
 ) -> AsyncIterator[
     tuple[
@@ -112,8 +100,8 @@ async def _lenient_stdio_client(  # noqa: PLR0915 — mirrors mcp.client.stdio.s
 
     All differences from upstream live in ``stdout_reader``: lines that fail
     ``JSONRPCMessage.model_validate_json`` are logged at DEBUG and skipped,
-    never forwarded as exceptions. This is what makes warning-noisy MCPs
+    never forwarded as exceptions. Shutdown still follows the MCP spec
-    quiet from the consumer's point of view.
+    sequence: close stdin, wait, SIGTERM, then SIGKILL.
     """
     read_stream_writer, read_stream = anyio.create_memory_object_stream[
         SessionMessage | Exception
@@ -159,7 +147,7 @@ async def _lenient_stdio_client(  # noqa: PLR0915 — mirrors mcp.client.stdio.s
                             continue
                         try:
                             message = types.JSONRPCMessage.model_validate_json(stripped)
-                        except Exception:  # noqa: BLE001 — by design, see module doc
+                        except Exception:  # noqa: BLE001
                             _log.debug(
                                 "lenient stdio: dropped non-JSON line: %r",
                                 stripped[:200],
@@ -192,7 +180,6 @@ async def _lenient_stdio_client(  # noqa: PLR0915 — mirrors mcp.client.stdio.s
         try:
             yield read_stream, write_stream
         finally:
-            # MCP spec stdio shutdown: close stdin → wait → SIGTERM → SIGKILL.
             if process.stdin:
                 with contextlib.suppress(Exception):
                     await process.stdin.aclose()

src/beaver_gateway/mcp/redacting.py

@@ -0,0 +1,68 @@
+"""Redact credentials in MCP tool output before it reaches the model.
+
+Covers every MCP route; in-process tools like ``Bash``/``Read`` are
+guarded separately by ``agents.policy``.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import mcp.types as mt
+from fastmcp.server.middleware import Middleware
+from fastmcp.tools.base import ToolResult
+
+from beaver_gateway.security.redact import redact, redact_data
+
+if TYPE_CHECKING:
+    from fastmcp.server.middleware import CallNext, MiddlewareContext
+
+__all__ = ["RedactingMiddleware"]
+
+
+def _redact_block(block: mt.ContentBlock) -> mt.ContentBlock:
+    """Mask a content block's text; binary blocks pass through."""
+    if isinstance(block, mt.TextContent):
+        masked = redact(block.text)
+        return (
+            block if masked == block.text else block.model_copy(update={"text": masked})
+        )
+    if isinstance(block, mt.EmbeddedResource) and isinstance(
+        block.resource, mt.TextResourceContents
+    ):
+        masked = redact(block.resource.text)
+        if masked == block.resource.text:
+            return block
+        resource = block.resource.model_copy(update={"text": masked})
+        return block.model_copy(update={"resource": resource})
+    return block
+
+
+class RedactingMiddleware(Middleware):
+    """Mask credentials in whatever a tool call returns.
+
+    Idempotent, so mounting a server both on its own namespace and in
+    the ``/mcp/all`` bundle costs a second pass, not a double mask.
+    """
+
+    async def on_call_tool(
+        self,
+        context: MiddlewareContext[mt.CallToolRequestParams],
+        call_next: CallNext[mt.CallToolRequestParams, ToolResult],
+    ) -> ToolResult:
+        """Mask the result.
+
+        A non-``None`` ``meta`` on the masked copy takes the
+        ``CallToolResult`` path that skips output-schema validation,
+        since masked structured content may no longer match it.
+        """
+        result = await call_next(context)
+        content = [_redact_block(block) for block in result.content]
+        structured = redact_data(result.structured_content)
+        if content == result.content and structured == result.structured_content:
+            return result
+        return ToolResult(
+            content=content,
+            structured_content=structured,
+            meta=result.meta if result.meta is not None else {},
+        )

src/beaver_gateway/mcp/types.py

@@ -6,7 +6,7 @@ discriminated-union members so downstream code can ``match`` on ``kind``.
 
 from __future__ import annotations
 
-from collections.abc import Callable  # noqa: TC003 — runtime use by pydantic
+from collections.abc import Callable  # noqa: TC003
 from pathlib import Path
 from typing import TYPE_CHECKING, Annotated, Literal
 
@@ -20,39 +20,35 @@ class _BaseMcp(BaseModel):
     model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)
 
     name: str
+    """The namespace this MCP server is mounted under."""
 
 
 class StdioMcp(_BaseMcp):
-    """Subprocess MCP server we spawn and connect to over stdio.
+    """Subprocess MCP server spawned and connected to over stdio."""
-
-    ``lenient`` switches the upstream stdio reader to a tolerant variant
-    that silently drops non-JSON-RPC lines from the subprocess's stdout
-    (``Processing...``-style chatter, banners, dependency-load messages).
-    The reference ``mcp.client.stdio.stdio_client`` forwards those parse
-    failures as exceptions, which bleed into Cursor/Cline UIs as warnings
-    when they connect through us. Default ``False`` keeps the strict
-    contract — flip it on per-namespace for known-noisy upstreams.
-    """
 
     kind: Literal["stdio"] = "stdio"
     command: tuple[str, ...]
+    """Argv used to spawn the subprocess."""
     env: dict[str, str] | None = None
+    """Extra environment variables for the subprocess."""
     cwd: Path | None = None
+    """Working directory to spawn the subprocess in."""
     lenient: bool = False
+    """Tolerate non-JSON-RPC stdout lines instead of raising (the strict
+    reader's parse errors surface as warnings in Cursor/Cline). Off by default."""
 
 
 class HttpMcp(_BaseMcp):
-    """Remote MCP server reached over streamable HTTP.
+    """Remote MCP server reached over streamable HTTP."""
-
-    ``headers`` are forwarded on every request to the upstream MCP — handy
-    for upstreams that authenticate via custom header rather than a Bearer
-    token (``auth``).
-    """
 
     kind: Literal["http"] = "http"
     url: str
+    """Streamable-HTTP endpoint URL."""
     auth: str | None = None
+    """Bearer token sent as the upstream's ``Authorization`` header."""
     headers: dict[str, str] | None = None
+    """Extra headers forwarded on every request; for upstreams that
+    authenticate via a custom header instead of ``auth``."""
 
 
 class PythonToolMcp(_BaseMcp):
@@ -60,13 +56,14 @@ class PythonToolMcp(_BaseMcp):
 
     kind: Literal["python_tool"] = "python_tool"
     tools: tuple[Callable[..., object], ...]
+    """The callables to expose as MCP tools."""
 
 
 McpServerT = Annotated[StdioMcp | HttpMcp | PythonToolMcp, Field(discriminator="kind")]
 
 
 class McpServer:
-    """Factory facade matching the PRD-documented config surface."""
+    """Factory facade for declaring MCP servers in config."""
 
     @classmethod
     def stdio(
@@ -78,6 +75,7 @@ class McpServer:
         cwd: Path | str | None = None,
         lenient: bool = False,
     ) -> StdioMcp:
+        """Declare a subprocess MCP server spawned over stdio."""
         return StdioMcp(
             name=name,
             command=tuple(command),
@@ -95,10 +93,12 @@ class McpServer:
         auth: str | None = None,
         headers: dict[str, str] | None = None,
     ) -> HttpMcp:
+        """Declare a remote MCP server reached over streamable HTTP."""
         return HttpMcp(name=name, url=url, auth=auth, headers=headers)
 
     @classmethod
     def python_tool(
         cls, *, name: str, tools: Iterable[Callable[..., object]]
     ) -> PythonToolMcp:
+        """Declare a namespace of Python callables exposed as MCP tools."""
         return PythonToolMcp(name=name, tools=tuple(tools))

src/beaver_gateway/mcp/wrap.py

@@ -1,8 +1,7 @@
 """Wrap a ``PythonToolMcp`` spec into a mountable ``FastMCP`` instance.
 
-Each ``python_tool`` McpServer in the user's config becomes a separate
+Each ``python_tool`` McpServer becomes its own ``FastMCP`` namespace so
-``FastMCP`` namespace — one domain, one server URL — so models keep the
+models keep the per-domain tool framing they were trained on.
-per-domain framing they were trained on (see PRD §6).
 """
 
 from __future__ import annotations

src/beaver_gateway/security/__init__.py

@@ -0,0 +1 @@
+"""Bearer tokens, the audit log and credential redaction."""

src/beaver_gateway/security/audit.py

@@ -0,0 +1,66 @@
+"""Single entry point for writing :class:`AuditLog` rows.
+
+``log()`` is fire-and-forget: it awaits the DB write so callers get
+ordering, but never raises — failures are logged and swallowed.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from beaver_gateway.storage import append_audit
+
+if TYPE_CHECKING:
+    from beaver_gateway.frontends.base import GatewayRuntime
+
+
+_log = logging.getLogger("beaver_gateway.audit")
+
+
+KNOWN_KINDS: frozenset[str] = frozenset(
+    {
+        "messages",
+        "mcp_call",
+        "tool_call",
+        "login_ok",
+        "login_failed",
+        "logout",
+        "token_create",
+        "token_revoke",
+    }
+)
+"""Kinds the gateway currently emits; ``AuditLog.kind`` stays free-form."""
+
+
+async def log(
+    runtime: GatewayRuntime,
+    *,
+    actor: str,
+    kind: str,
+    agent_name: str | None = None,
+    **detail: Any,
+) -> None:
+    """Best-effort audit insert. Never raises; DB failures are logged.
+
+    ``actor`` is free-form (``"token:<name>"``, ``"admin:<user>"``,
+    ``"anon"``); ``kind`` is a short tag (see :data:`KNOWN_KINDS`); and
+    ``**detail`` is JSON-serialised into ``AuditLog.detail_json`` — keep
+    it small, not full request bodies.
+    """
+    try:
+        async with runtime.db.session() as session:
+            await append_audit(
+                session,
+                actor=actor,
+                kind=kind,
+                agent_name=agent_name,
+                detail=detail or None,
+            )
+    except Exception:  # noqa: BLE001
+        _log.exception(
+            "audit write failed: actor=%s kind=%s agent=%s", actor, kind, agent_name
+        )
+
+
+__all__ = ["KNOWN_KINDS", "log"]

src/beaver_gateway/security/auth.py

@@ -1,32 +1,7 @@
-"""Bearer-token verification (Phase 4.2 — DB-backed with in-memory cache).
+"""Bearer-token verification: a DB-backed store with an in-memory cache.
 
-The store is fed by two sources:
+Optional ``BOOTSTRAP_TOKENS`` env entries are checked first. Verify takes
-
+a raw token or ``Authorization`` header and returns a :class:`TokenIdentity`.
-1. **DB** (``Token`` table from Phase 4.1) — the primary source. Rows
-   carry Argon2id hashes; the admin UI (Phase 4.3) will be the only
-   writer at steady state.
-2. **`BOOTSTRAP_TOKENS`** env — a name→plaintext map kept around for
-   first-run, disaster-recovery, and ``examples/`` smoke tests. These
-   entries live alongside DB rows in the cache and are never persisted.
-
-Hot path is in-memory: at :meth:`start` we pull every non-revoked DB
-row and stash it in a list; subsequent :meth:`verify` calls re-load
-when the cache is older than ``ttl_seconds``. ``last_used_at`` updates
-are coalesced into a small dict and flushed by a background task every
-``flush_interval`` seconds — one transaction per flush rather than one
-per request.
-
-We can't index DB rows by a derived plaintext key because Argon2 salts
-are random — so verify does a linear scan over candidates, calling
-``argon2.PasswordHasher.verify`` on each. N is small by design (single
-operator, ~10 tokens at most); the cost is irrelevant. The scan runs
-through ``asyncio.to_thread`` to keep the event loop free of the ~50ms
-KDF block.
-
-The module knows nothing about HTTP frameworks. It takes a raw token
-(or a verbatim ``Authorization`` header value) and returns a
-:class:`TokenIdentity` (name + scope + db-id), or ``None`` for a miss.
-Frontends own the 401 response shape.
 """
 
 from __future__ import annotations
@@ -46,7 +21,7 @@ from argon2.exceptions import InvalidHashError, VerifyMismatchError
 from beaver_gateway.storage import list_active_tokens, touch_token
 
 if TYPE_CHECKING:
-    from collections.abc import Mapping
+    from collections.abc import Iterable, Mapping
 
     from beaver_gateway.storage import Database
 
@@ -60,8 +35,8 @@ class TokenStoreError(ValueError):
     """Malformed ``BOOTSTRAP_TOKENS`` value or duplicate token."""
 
 
-VALID_SCOPES: frozenset[str] = frozenset({"*", "messages", "mcp", "admin", "api"})
+BUILTIN_SCOPES: frozenset[str] = frozenset({"*", "messages", "mcp", "admin", "api"})
-"""The scopes a ``Token.scope`` may hold (Phase 4.3 admin UI enforces).
+"""The scopes the gateway's own frontends define.
 
 * ``*`` — wildcard, may use any frontend
 * ``messages`` — Anthropic Messages frontend only
@@ -69,17 +44,25 @@ VALID_SCOPES: frozenset[str] = frozenset({"*", "messages", "mcp", "admin", "api"
 * ``api`` — conversations API (``/api``) and its SSE
 * ``admin`` — reserved for programmatic admin access; the AdminFrontend
   itself authenticates via session cookies, not bearer tokens, so this
-  scope is unused today and kept for forward compatibility.
+  scope is unused today.
+
+A setup's own frontend adds its scope on top; see :func:`scopes_with` and
+``GatewayRuntime.scopes``, which is what ``POST /api/tokens`` validates.
 """
 
 
+def scopes_with(extra: Iterable[str | None]) -> frozenset[str]:
+    """The builtin scopes plus every frontend's own; ``None`` entries drop out."""
+    return BUILTIN_SCOPES | {s for s in extra if s}
+
+
 @dataclass(frozen=True, slots=True)
 class TokenIdentity:
     """What :meth:`TokenStore.verify` resolves to on success.
 
     ``token_id`` is the DB row id for persisted tokens, or ``None`` for
     an env-bootstrap match (those have no DB row to touch). ``scope``
-    gates which frontend the token may hit (see :data:`VALID_SCOPES`);
+    gates which frontend the token may hit (see :data:`BUILTIN_SCOPES`);
     bootstrap tokens implicitly get ``"*"``.
     """
 
@@ -92,8 +75,8 @@ class TokenIdentity:
 
         ``"*"`` is the wildcard; an exact match satisfies a single scope.
         Unknown ``required`` values intentionally fall through to a
-        strict equality check — callers should pass one of
+        strict equality check — callers should pass a scope the runtime
-        :data:`VALID_SCOPES`.
+        knows (:data:`BUILTIN_SCOPES` plus every frontend's own).
         """
         return self.scope in ("*", required)
 
@@ -108,33 +91,23 @@ class _CachedToken:
     hashed_value: str
 
 
-# Default Argon2id parameters from ``argon2-cffi`` are fine for our scope.
-# They target ~50ms on a modern CPU — enough to make a stolen-hash brute
-# force expensive, cheap enough to verify a handful per request.
 _HASHER = PasswordHasher()
 
 
 def hash_token(plaintext: str) -> str:
-    """Return an Argon2id hash for ``plaintext`` (admin / seed-only path).
+    """Return an Argon2id hash for ``plaintext``, for admin/seed use."""
-
-    Phase 4.3 will call this when the admin creates a token; Phase 4.2
-    exposes it so smoke scripts can seed the DB without re-implementing
-    the same line.
-    """
     return _HASHER.hash(plaintext)
 
 
 class TokenStore:
-    """DB-backed verifier with in-memory cache + TTL + batched touches.
+    """DB-backed verifier with an in-memory cache, TTL, and batched touches.
 
-    Construct in ``cli.main`` after :class:`Database` is up, then
+    Call ``await store.start()`` after construction to prime the cache
-    ``await store.start()`` to prime the cache and spin up the flusher
+    and start the flusher; ``await store.stop()`` drains the touch queue.
-    task. ``await store.stop()`` on shutdown drains the touch queue.
 
-    Bootstrap entries (from ``BOOTSTRAP_TOKENS``) sit alongside DB rows
+    Bootstrap entries (``BOOTSTRAP_TOKENS``) are checked first and stay
-    in the same lookup path; we check them first, in constant time, so
+    usable even if the DB is unreachable; they never get flushed to
-    they remain usable even if the DB is unreachable. They never appear
+    ``last_used_at`` since they have no DB row.
-    in ``last_used_at`` flushes because they have no DB row.
     """
 
     __slots__ = (
@@ -155,11 +128,15 @@ class TokenStore:
         db: Database | None = None,
         *,
         bootstrap: Mapping[str, str] | None = None,
+        bootstrap_scopes: Mapping[str, str] | None = None,
         ttl_seconds: float = 30.0,
         flush_interval: float = 5.0,
     ) -> None:
-        # Bootstrap is keyed by value internally so verify is O(1) over
+        """Index bootstrap tokens for O(1) verify lookup.
-        # plaintext. Each value also keeps its name for audit lines.
+
+        Each one's scope defaults to ``"*"`` unless narrowed via
+        ``name:value:scope``.
+        """
         by_value: dict[str, str] = {}
         for name, value in (bootstrap or {}).items():
             if not name or not value:
@@ -173,9 +150,10 @@ class TokenStore:
                 raise TokenStoreError(msg)
             by_value[value] = name
         self._bootstrap_by_value: dict[str, str] = by_value
-        self._bootstrap_scopes: dict[str, str] = dict.fromkeys(
+        self._bootstrap_scopes: dict[str, str] = {
-            by_value.values(), _BOOTSTRAP_SCOPE
+            name: (bootstrap_scopes or {}).get(name, _BOOTSTRAP_SCOPE)
-        )
+            for name in by_value.values()
+        }
 
         self._db = db
         self._ttl = ttl_seconds
@@ -187,38 +165,25 @@ class TokenStore:
         self._touch_queue: dict[int, datetime] = {}
         self._flusher_task: asyncio.Task[None] | None = None
 
-    # ---- bootstrap parsing (kept for `cli` / tests) ---------------------
-
     @staticmethod
     def parse_bootstrap(raw: str) -> dict[str, str]:
-        """Parse ``name1:value1,name2:value2`` (the ``BOOTSTRAP_TOKENS`` form)."""
+        """Parse ``name1:value1,name2:value2[:scope]`` (``BOOTSTRAP_TOKENS``)."""
-        tokens: dict[str, str] = {}
+        return {name: value for name, (value, _scope) in _parse_entries(raw).items()}
-        for chunk in raw.split(","):
+
-            entry = chunk.strip()
+    @staticmethod
-            if not entry:
+    def parse_bootstrap_scopes(raw: str) -> dict[str, str]:
-                continue
+        """Scopes given as a third field in ``BOOTSTRAP_TOKENS``; the rest get ``*``."""
-            name, sep, value = entry.partition(":")
+        return {
-            if not sep:
+            name: scope
-                msg = f"token entry missing ':' separator: {entry!r}"
+            for name, (_value, scope) in _parse_entries(raw).items()
-                raise TokenStoreError(msg)
+            if scope is not None
-            name, value = name.strip(), value.strip()
+        }
-            if name in tokens:
-                msg = f"duplicate token name: {name!r}"
-                raise TokenStoreError(msg)
-            tokens[name] = value
-        return tokens
 
     @classmethod
     def from_env(cls, raw: str, db: Database | None = None) -> TokenStore:
-        """Legacy entrypoint: bootstrap-only (or bootstrap + db).
+        """Bootstrap-only (or bootstrap + db) convenience constructor."""
-
-        Phase 1.3 call sites still expect a one-liner; we keep the
-        classmethod so they don't have to learn the new constructor.
-        """
         return cls(db, bootstrap=cls.parse_bootstrap(raw))
 
-    # ---- lifecycle ------------------------------------------------------
-
     async def start(self) -> None:
         """Prime the cache and (if a DB is attached) start the flusher loop."""
         await self._refresh()
@@ -242,19 +207,19 @@ class TokenStore:
         self._bootstrap_scopes[name] = scope
 
     async def invalidate(self) -> None:
-        """Force the next verify to re-read from DB (Phase 4.3 admin hook)."""
+        """Force the next verify to re-read from DB."""
         self._loaded_at = 0.0
 
-    # ---- verify path ----------------------------------------------------
-
     async def verify(self, token: str | None) -> TokenIdentity | None:
-        """Return the matching identity, or ``None`` for unknown/empty tokens."""
+        """Return the matching identity, or ``None`` for unknown/empty tokens.
+
+        Bootstrap entries are checked first via constant-time compare;
+        the DB cache list is swapped rather than mutated on refresh, so
+        a concurrent reload can't affect an in-progress scan.
+        """
         if not token:
             return None
 
-        # Bootstrap first: constant-time compare per entry, never hits DB.
-        # `compare_digest` is overkill for a name→value lookup but cheap
-        # and removes one timing variable for free.
         for value, name in self._bootstrap_by_value.items():
             if hmac.compare_digest(token, value):
                 return TokenIdentity(
@@ -268,9 +233,6 @@ class TokenStore:
 
         await self._ensure_fresh()
 
-        # Snapshot the cache reference so a refresh mid-scan doesn't
-        # surprise us. List itself is immutable per refresh (we swap,
-        # not mutate).
         cache = self._cache
         for entry in cache:
             try:
@@ -306,17 +268,18 @@ class TokenStore:
     def __bool__(self) -> bool:
         return bool(self._cache) or bool(self._bootstrap_by_value)
 
-    # ---- internals ------------------------------------------------------
-
     async def _ensure_fresh(self) -> None:
+        """Reload the cache when stale.
+
+        Double-checked under the lock so concurrent callers don't all
+        trigger a reload.
+        """
         if self._db is None:
             return
         now = time.monotonic()
         if now - self._loaded_at <= self._ttl:
             return
         async with self._lock:
-            # Re-check under the lock — first arrival reloaded, others
-            # should fall through.
             now = time.monotonic()
             if now - self._loaded_at <= self._ttl:
                 return
@@ -331,8 +294,6 @@ class TokenStore:
         next_cache: list[_CachedToken] = []
         for row in rows:
             if row.id is None:
-                # Defensive: SQLModel will assign an id on insert; a
-                # None here would mean someone handed us an unsaved row.
                 continue
             next_cache.append(
                 _CachedToken(
@@ -353,28 +314,48 @@ class TokenStore:
                 await self._flush_now()
         except asyncio.CancelledError:
             raise
-        except Exception:  # noqa: BLE001 — never let the flusher die silently
+        except Exception:  # noqa: BLE001
             _log.exception("token flusher crashed; touches will stop")
 
     async def _flush_now(self) -> None:
+        """Flush queued touches in one transaction.
+
+        Detaches the queue first so concurrent ``verify()`` writes land
+        in the next flush.
+        """
         if self._db is None or not self._touch_queue:
             return
-        # Detach the queue so concurrent verify() writes don't bleed
-        # into the in-flight transaction.
         pending, self._touch_queue = self._touch_queue, {}
         async with self._db.session() as session:
             for token_id in pending:
-                # We don't pass the timestamp through — `touch_token`
-                # stamps `now` itself, and we'd rather have one source
-                # of truth than reconcile clocks.
                 await touch_token(session, token_id=token_id)
         _log.debug("flushed %d token touch(es)", len(pending))
 
 
 __all__ = [
-    "VALID_SCOPES",
+    "BUILTIN_SCOPES",
     "TokenIdentity",
     "TokenStore",
     "TokenStoreError",
     "hash_token",
+    "scopes_with",
 ]
+
+
+def _parse_entries(raw: str) -> dict[str, tuple[str, str | None]]:
+    entries: dict[str, tuple[str, str | None]] = {}
+    for chunk in raw.split(","):
+        entry = chunk.strip()
+        if not entry:
+            continue
+        name, sep, rest = entry.partition(":")
+        if not sep:
+            msg = f"token entry missing ':' separator: {entry!r}"
+            raise TokenStoreError(msg)
+        value, sep, scope = rest.partition(":")
+        name, value, scope = name.strip(), value.strip(), scope.strip()
+        if name in entries:
+            msg = f"duplicate token name: {name!r}"
+            raise TokenStoreError(msg)
+        entries[name] = (value, scope if sep and scope else None)
+    return entries

src/beaver_gateway/security/redact.py

@@ -0,0 +1,235 @@
+"""Recognise credentials in free text and mask them.
+
+Used to filter log output and to redact what MCP tools hand back to
+the model (see :mod:`beaver_gateway.mcp.redacting`).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+from typing import TYPE_CHECKING
+from urllib.parse import quote, unquote
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+
+MASK = "<…>"
+
+CHATTY: tuple[str, ...] = ("httpx", "httpcore", "aiohttp.client", "urllib3")
+"""Loggers that print request URLs at ``INFO``; only their warnings are kept."""
+
+OWN_HANDLERS: tuple[str, ...] = ("uvicorn", "uvicorn.access", "uvicorn.error")
+"""Loggers whose own handlers survive ``dictConfig``, unreached by the
+root formatter."""
+
+_SECRET_NAME = re.compile(
+    r"TOKEN|SECRET|KEY|PASSWORD|PASS\b|PAT\b|BEARER|CREDENTIAL"
+    r"|MCPS?\b|AUTH|PRIVATE|SESSION|DSN",
+    re.IGNORECASE,
+)
+"""Substring match for names whose *value* is a credential."""
+
+_MIN_SECRET = 8
+
+_LEFT = r"(?:(?<![A-Za-z0-9])|(?<=%26)|(?<=%3F))"
+_VALUE = r"(?:(?!%26)[^&\s\"'<>,;)\]}])+"
+"""Query-parameter boundaries: a value may follow a plain or
+percent-encoded ``?``/``&`` and runs to the next separator."""
+
+_SECRET_IN_DUMP = re.compile(r"USER\b|LOGIN\b", re.IGNORECASE)
+"""Masked only when paired with a password in a dump, not hunted as a global literal."""
+
+
+def is_secret_name(name: str) -> bool:
+    """Whether a variable/field of this name holds a credential."""
+    return bool(_SECRET_NAME.search(name) or _SECRET_IN_DUMP.search(name))
+
+
+def _mask_named_value(match: re.Match[str]) -> str:
+    """Mask ``value`` in a ``NAME: value`` match, keeping the name.
+
+    A dump is still worth reading when it says *which* variables are
+    set; it is the values that must not travel. An already-masked or
+    empty value is left alone so the pass stays idempotent, and ``lead``
+    / ``tail`` carry back whatever quoting the surrounding format used.
+    """
+    groups = match.groupdict()
+    name, value = groups["name"], groups["value"]
+    if not is_secret_name(name) or value.strip(" \t\"'") in ("", MASK):
+        return match[0]
+    lead, tail = groups.get("lead") or "", groups.get("tail") or ""
+    return f"{lead}{name}{groups['sep']}{MASK}{tail}"
+
+
+type _Repl = str | Callable[[re.Match[str]], str]
+
+_RULES: tuple[tuple[re.Pattern[str], _Repl], ...] = (
+    (
+        re.compile(r"(private-)(?:(?!%2F)[A-Za-z0-9_%-]){8,}", re.IGNORECASE),
+        r"\1" + MASK,
+    ),
+    (
+        re.compile(
+            _LEFT
+            + r"(api[-_]?key|access[-_]?token|auth[-_]?token"
+            + r"|token|key|secret|password|passwd|pat|signature|sig)"
+            + r"(=|%3D)"
+            + _VALUE,
+            re.IGNORECASE,
+        ),
+        r"\1\2" + MASK,
+    ),
+    (
+        re.compile(
+            r"(authorization[\"']?\s*[:=]\s*[\"']?)(?:\S+\s+)?\S+", re.IGNORECASE
+        ),
+        r"\1" + MASK,
+    ),
+    (re.compile(r"\b(bearer)\s+[A-Za-z0-9._~+/=-]{8,}", re.IGNORECASE), r"\1 " + MASK),
+    (
+        re.compile(
+            r"""(?m)^(?P<lead>[ \t]*(?:-[ \t]+)?["']?)
+                 (?P<name>[A-Z][A-Z0-9_]{2,})
+                 (?P<sep>["']?(?::[ \t]*|=))
+                 (?P<value>"[^"\n]*"|'[^'\n]*'|[^\n]*)""",
+            re.VERBOSE,
+        ),
+        _mask_named_value,
+    ),
+    (
+        re.compile(
+            r"""(?m)^(?P<lead>[ \t]*(?:-[ \t]+)?["']?)
+                 (?P<name>password|passwd|secret|token|api[-_]?key|apikey
+                   |access[-_]?token|auth[-_]?token|private[-_]?key|credentials?)
+                 (?P<sep>["']?(?::[ \t]*|=))
+                 (?P<value>"[^"\n]*"|'[^'\n]*'|[^\n]*)""",
+            re.VERBOSE | re.IGNORECASE,
+        ),
+        _mask_named_value,
+    ),
+    (re.compile(r"(://[^/\s:@]+:)[^@\s/]+(@)"), r"\1" + MASK + r"\2"),
+    (
+        re.compile(
+            r'(?P<lead>")(?P<name>[^"\n]{1,64})(?P<sep>"\s*:\s*")'
+            r'(?P<value>[^"\n]*)(?P<tail>")'
+        ),
+        _mask_named_value,
+    ),
+)
+"""Redaction rules applied in order: calendar tokens, query-string secrets,
+``Authorization`` headers, bare bearer tokens, ``NAME: value``/``NAME=value``
+lines (upper- then lower-case names), connection-string passwords, and
+one-line JSON ``"name": "value"`` pairs."""
+
+_ENV_SECRETS: list[str] = []
+"""Literal secret values to mask, longest first. Filled by :func:`install`."""
+
+
+def env_secrets(env: Mapping[str, str]) -> list[str]:
+    """Literal values worth masking, longest first.
+
+    Each secret-looking variable contributes its value plus the
+    percent-encoded and percent-decoded spellings of it, because a
+    credential that travels inside another URL is logged encoded.
+    """
+    found: set[str] = set()
+    for name, value in env.items():
+        if not _SECRET_NAME.search(name):
+            continue
+        for form in (value, quote(value, safe=""), unquote(value)):
+            if len(form.strip()) >= _MIN_SECRET:
+                found.add(form.strip())
+    ordered = list(found)
+    ordered.sort(key=len, reverse=True)
+    return ordered
+
+
+def redact(text: str) -> str:
+    """Mask every credential we can recognise in ``text``."""
+    for value in _ENV_SECRETS:
+        if value in text:
+            text = text.replace(value, MASK)
+    for pattern, repl in _RULES:
+        text = pattern.sub(repl, text)
+    return text
+
+
+def redact_data(value: object) -> object:
+    """Mask every string inside a decoded JSON tree.
+
+    A field name is the only context a bare value has: ``"0d1e…"`` on
+    its own looks like nothing, ``{"ADMIN_PASS": "0d1e…"}`` is a
+    password. So a secret-looking key masks its whole subtree — the
+    structured twin of the ``NAME: value`` rule above.
+    """
+    if isinstance(value, str):
+        return redact(value)
+    if isinstance(value, dict):
+        return {
+            key: MASK if is_secret_name(str(key)) and item else redact_data(item)
+            for key, item in value.items()
+        }
+    if isinstance(value, list):
+        return [redact_data(item) for item in value]
+    return value
+
+
+class RedactingFormatter(logging.Formatter):
+    """Wrap another formatter and redact whatever it produced.
+
+    Formatting first is the point: it catches the message, its ``%``
+    arguments and the traceback of an ``exception()`` call in one pass,
+    which a record-level filter cannot do.
+    """
+
+    def __init__(self, inner: logging.Formatter | None = None) -> None:
+        super().__init__()
+        self._inner = inner if inner is not None else logging.Formatter()
+
+    def format(self, record: logging.LogRecord) -> str:
+        return redact(self._inner.format(record))
+
+
+class RedactFilter(logging.Filter):
+    """Redact at record level, for loggers whose handlers aren't ours.
+
+    Interpolates first and replaces the record with the result, because
+    a secret is often split across the template and its arguments
+    (``"key=%s", token``) and neither half looks like a credential on
+    its own. The arguments are dropped only when something was actually
+    masked, so untouched records stay structured.
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        """Let a record through unmasked if its template is malformed."""
+        try:
+            message = record.getMessage()
+        except (TypeError, ValueError):
+            return True
+        masked = redact(message)
+        if masked != message:
+            record.msg = masked
+            record.args = ()
+        return True
+
+
+def load_secrets(env: Mapping[str, str] | None = None) -> None:
+    """(Re)read the literal values to mask.
+
+    Called once at startup and again after ``.env`` is loaded, because
+    in dev the process environment only fills up at that point.
+    """
+    _ENV_SECRETS[:] = env_secrets(os.environ if env is None else env)
+
+
+def install(env: Mapping[str, str] | None = None) -> None:
+    """Wire redaction into the root logger. Call right after ``basicConfig``."""
+    load_secrets(env)
+    for handler in logging.getLogger().handlers:
+        handler.setFormatter(RedactingFormatter(handler.formatter))
+    for name in CHATTY:
+        logging.getLogger(name).setLevel(logging.WARNING)
+    for name in OWN_HANDLERS:
+        logging.getLogger(name).addFilter(RedactFilter())

src/beaver_gateway/settings.py

@@ -1,8 +1,8 @@
 """Process-wide configuration loaded from environment (`.env`).
 
-Everything that varies between deployments (creds, paths, ports) lives here.
+Everything that varies between deployments (creds, paths, ports) lives
-User-facing agent/MCP/frontend definitions live in ``/config/config.py``
+here. User-facing agent/MCP/frontend definitions live in ``config_path``
-and are loaded by ``config_loader`` (Phase 0.3).
+and are loaded by :mod:`beaver_gateway.config`.
 """
 
 from __future__ import annotations
@@ -20,12 +20,22 @@ class Settings(BaseSettings):
     )
 
     database_url: str
+    """SQLAlchemy async URL for the gateway's database."""
+
     admin_user: str
+    """Username for the admin UI login."""
+
     admin_pass: str
+    """Password for the admin UI login."""
+
     session_secret: str
+    """Secret used to sign admin UI session cookies."""
 
     internal_mcp_port: int = 8765
+    """Port the gateway's own internal MCP server listens on."""
+
     config_path: Path = Path("/config/config.py")
+    """Where the user-facing agent/MCP/frontend config module lives."""
 
     claude_runner_user: str | None = None
     """Unix user the claude subprocess runs as. Needs the gateway to be root."""
@@ -34,23 +44,23 @@ class Settings(BaseSettings):
     """``HOME`` for the claude subprocess (its ``~/.claude`` lives there)."""
 
     raycast_bearer: str | None = None
+    """Bearer token the gateway presents to the Raycast API."""
+
     raycast_config_path: Path = Path("/config/raycast.json")
+    """Where cached Raycast API config (fetched on first use) is stored."""
+
     raycast_device_id: str | None = None
-    """64-hex-char stable per-install id. Required when any ``RaycastAgent``
+    """Stable per-install id (``secrets.token_hex(32)``); required when any
-    is configured — generate once via ``secrets.token_hex(32)`` and keep
+    ``RaycastAgent`` is configured, so restarts don't look like a new device."""
-    in ``.env`` so Raycast doesn't see every restart as a new device."""
 
     raycast_locale: str = "en-US"
-    """``Accept-Language`` header sent by the shared ``raycast_api.Client``
+    """``Accept-Language`` sent to the Raycast API and the default locale for
-    and the default locale used to render auto ``UserPreferences``. One
+    auto ``UserPreferences``. One value per gateway (one shared Client)."""
-    value per gateway since we open one Client total."""
+
+    send_file_roots: str = "/mnt/hole/shared"
+    """Directories the ``send_file`` tool may read, separated by ``:``. A
+    frontend always adds the inbox its own attachments land in."""
 
     bootstrap_tokens: str = ""
-    """Out-of-band token seed: ``name1:value1,name2:value2``. Empty is
+    """Out-of-band token seed: ``name1:value1,name2:value2``. Layers
-    fine — DB-issued tokens (admin UI) carry steady-state auth.
+    alongside DB-issued tokens; used for first-run setup and recovery."""
-
-    This env channel layers alongside the DB store and is kept for
-    first-run setup, disaster recovery (admin password lost), and
-    ``examples/`` smoke tests. Bootstrap tokens implicitly carry
-    scope ``"*"`` and never get a ``last_used_at`` stamp (no DB row).
-    """

src/beaver_gateway/storage/__init__.py

@@ -9,12 +9,14 @@ from beaver_gateway.storage.db import (
     Database,
     append_audit,
     append_usage,
+    backfill_usage_deltas,
     create_token,
     list_active_tokens,
     list_audit_records,
     list_tokens,
     revoke_token,
     touch_token,
+    usage_deltas,
 )
 from beaver_gateway.storage.models import (
     AuditLog,
@@ -23,7 +25,6 @@ from beaver_gateway.storage.models import (
     Delivery,
     InjectQueueItem,
     RateLimit,
-    Schedule,
     TelegramUpdate,
     Token,
     TranscriptEntry,
@@ -40,17 +41,18 @@ __all__ = [
     "InjectQueueItem",
     "PostgresSessionStore",
     "RateLimit",
-    "Schedule",
     "TelegramUpdate",
     "Token",
     "TranscriptEntry",
     "Usage",
     "append_audit",
     "append_usage",
+    "backfill_usage_deltas",
     "create_token",
     "list_active_tokens",
     "list_audit_records",
     "list_tokens",
     "revoke_token",
     "touch_token",
+    "usage_deltas",
 ]

src/beaver_gateway/storage/backfill_usage.py

@@ -0,0 +1,31 @@
+"""Rewrite ``usage.cost_usd``/``model_usage`` as per-turn deltas.
+
+Older rows stored a cumulative total, which overstates daily sums. Safe
+to rerun; reads ``DATABASE_URL`` like the gateway.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from dotenv import load_dotenv
+
+from beaver_gateway.settings import Settings
+from beaver_gateway.storage.db import Database, backfill_usage_deltas
+
+
+async def _main() -> None:
+    load_dotenv(override=False)
+    settings = Settings()  # ty: ignore[missing-argument]
+    db = Database(settings.database_url)
+    try:
+        await db.create_all()
+        async with db.session() as session:
+            changed = await backfill_usage_deltas(session)
+    finally:
+        await db.dispose()
+    print(f"usage rows rewritten: {changed}")
+
+
+if __name__ == "__main__":
+    asyncio.run(_main())