Chunk A of the search port wave (2026-09-20), per master's assignment:
- web.ts: the Google Custom Search backend is gone — web_search now runs
on the core search port (SearchProvider), injected as a dependency
(import law: the tool never imports server code). createWebTools(search)
resolves the LIVE provider fresh per call; null = the honest
unavailability string (no silent fallback, owner decision). web_fetch
unchanged (needs no engine).
- runner: JobRunnerDeps.searchProvider — the server composition threaded
into the researcher; jobs already in flight when a key disappears still
fail honestly through the same seam, never crash.
- jobTools: the research dispatch tool DROPS from the teacher's registry
when ctx.searchAvailable() is false (owner decision: registry-level
drop — the model never sees the tool, no doomed dispatch, no error
card). Absent seam = available (tests). chat-handler injects
server/searchAvailable + searchProvider.
- tests: stubFetch (the Google wire stub) retired; jobs.test.ts threads
a recording stub provider through all four research runners and asserts
the scripted query hit the port; new web-search.test.ts covers the
factory contract (null → honest string, hits, error strings, fresh
resolution, web_fetch independence) + the registry drop matrix.
Gates: typecheck, 793/793 tests, lint, build — all green.
Chunk B (owner-designed, model-slots wave) on the merged engine surface
(main 1d66a17):
AGENT SECTION — SLOTS ONLY (owner ruling)
- The six per-role model rows are GONE; three slot rows instead:
Strong (Prober + Teacher), Cheap (five workhorse roles), Vision
(visual maker + PDF reader), roster + resolved-default in every hint.
- Slot dropdowns share the app's menu language over the FEDERATED
catalog (/api/models = keyed providers only, fresh per call — saving
a key in Keys immediately widens the picker); the vision slot
filters to image-capable models (Model.input); the menu's highlight
now matches provider+id (ids can collide across providers).
- Slots write the new models section (PUT /api/settings/models) through
the dialog's write seam; per-role overrides stay schema-only.
- ModelMenuList rows read 'provider · id' — federation makes the
provider bookkeeping-relevant. Usage stamps render provider-qualified
(prettyModel(qualified): 'Glm 5.3 Flash · openrouter') in the stats
bar's turn lines.
SEARCH ENGINE (search wave: no default, owner)
- A row in Tools: Tavily/Brave via the shared-menu look, Automatic =
the pin removed (auto-activation). The live reason line comes from
/api/search; no engine key at all grays the whole row + disables the
trigger (a keyless choice would only block auto-activation).
FIRST-RUN SETUP FLOW (owner design A: composer CTA + send interception)
- Chats cannot start until all three slots are picked — no defaults
for 33 providers (slotsConfigured: all three slot models required).
- The graph view's new-session dock (home) shows a 'Set up your models'
CTA while unconfigured; submitting a topic opens the SetupDialog WITH
THE DRAFT PRESERVED; Save stores the models section and the queued
message sends. Same interception on /chat/new sends.
- STAGED BY DEPENDENCY (owner: keys first, models after): no keyed
provider → stage 1 deep-links the settings dialog on Keys (open now
takes a section); a saved key reopens at stage 2 on the next submit.
- Stage 2: Strong → Cheap → Vision pickers (federated, vision-filtered,
all three required). Closable without configuring — browsing stays
possible; the gate is the send, not the dialog. Layered Esc: an open
slot menu eats Esc before the dialog.
- Two closure bugs caught live: onDone→start/send captured the stale
pre-save 'configured' (the flow now forces the replayed send); menu-Esc
used to close the whole dialog.
Settings-dialog provider: open(section?) lands on a section (stage 1
deep-link). Tests: composeSlotModel/composeSearchEngine pure, slot SSR
replacing role rows, slotsConfigured/setupStage first-run gates,
provider-qualified prettyModel. Gates: typecheck, lint, 792/792, build.
The owner called the old section messy; the redesign is theirs:
- MINIMAL TABLE: provider label left, masked status right (…tail ·
chars · env), description hints GONE (they took too much space),
the 'Get a key ↗' link a tiny muted guest on curated rows. Rows
read as clean key-value pairs.
- ENV-OWNED ROWS ARE READ-ONLY (owner ruling): a real environment
variable owns the value — the row dims (graph-view graying) and no
paste field renders, because a paste box on a key the UI cannot
make live would mislead. Clicking does nothing.
- OPENROUTER UN-PINNED (owner ruling): one provider among 33 — a row
only when stored, otherwise it's an option in the Add dropdown like
everyone else. No synthesis, no lifeline description.
- ROW INTERACTION (owner choice): clicking a writable row unfolds a
paste field + Save (+ Delete for a file-sourced value) beneath it;
success folds it back to rest; Esc folds without closing the dialog
(claimed at document CAPTURE phase — the only stopPropagation that
outruns both React handlers and the dialog's window listener; the
React-level attempt leaked and closed the dialog, caught live).
- ADD-PROVIDER = the table's last row, in the app's shared dropdown
language: new ProviderMenuList (fuzzy search + arrow-walk + Enter
over the 33 pi-ai providers, label + envVar rows) in the shared
model-menu.tsx, portaled and fixed-positioned like the role menus.
Picking one unfolds a paste row; Save stores, Cancel/Esc folds.
- Tools & services (Deepgram + the Google pair) keep their own group,
same table look, same unfold interaction.
- Unknown auth.json vars stay read-only dimmed rows.
Tests: classifyKeys re-pinned (openrouter rides the normal provider
classification; addable drops stored keys), keyStatusLine minimal
('not set' for absent, ' · env' marker for environment-owned). Gates:
typecheck, lint, 759/759, build.
Live-verified: add→save→replace→delete round-trips, fold-on-save,
Esc layering both flows, env-owned rows read-only, addable count
31→30→31.
Model slots wave (2026-09-20), chunk B:
- settings: new `models` section {strong, cheap, vision} slots (each
field independent, same shape as a role override); ROLE_SLOT maps all
nine roles to tiers (strong=prober+teacher, cheap=researcher/
demoBuilder/extractor/auditor/labeler, vision=visualMaker+pdfReader);
resolution chain per role: override → slot → factory pin.
- config: ModelSpec gains provider (all pins openrouter, the BYOK
default); MODEL_PINS in stores.ts now spans all nine roles (the strong
slot's factory rep IS the prober pin).
- engine: piModels() registers EVERY builtin provider catalog;
piEngineForSpec(resolved spec) is the new engine factory (pi-ai
resolves per-provider keys from env itself); piEngineFor stays as the
config-pin fallback. chat-handler resolves the conversation chain
(chat override → strong slot → pin) and injects engineFor into the job
runner, closing the old gap where per-role overrides never reached
job engines.
- /api/models: models federate ONLY keyed providers (providers surface
with keyPresent, env-wins, fresh per call); slots (resolved tier pins)
join rolePins; catalogDefaultsFor inherits the strong slot; the models
settings section gets the same catalog gate as chat.
- pricing: PRICES/CONTEXT_LIMITS uniformly keyed provider:id
(regenerated from ALL pi-ai catalogs, 1354 keys); usage stamps
(TurnUsage, JobUsage, extraction stages) switch to provider:id —
owner decision: no legacy compat, old stamps render unpriced.
Search port + model slots wave, chunk A (owner design, 2026-09-20):
- core/search.ts: SearchHit + SearchProvider port + SearchStatus —
pure, browser-safe; adapters arrive as injected dependencies.
- server/search.ts: Tavily + Brave adapters (wire shapes VERIFIED
against docs.tavily.com's OpenAPI + Brave's dashboard docs — Tavily
auth is the Bearer header, not the legacy body api_key; Brave is
X-Subscription-Token) + engine resolution per owner decisions: a key
ALONE activates its engine (no engine choice needed), explicit
agent.search.engine pins the preference (both keys: Tavily first),
a pinned engine with a missing key is honestly unavailable — no
silent fallback, no default engine.
- Curated keys catalog: GOOGLE_SEARCH_API_KEY/GOOGLE_CSE_ID retire
(CSE closed to new customers, dies Jan 2027 — stored values become
preserved unknown vars); TAVILY_API_KEY (tvly- shape) + BRAVE_API_KEY
(length guard) join. UI keys-section TOOL_IDS now derives from the
catalog — cannot drift.
- GET /api/search: {available, engine, reason} — the honest status for
the settings gray-out; researcher-disable semantics ride the same
signal (Teacher stream rewires the tool onto the port).
- agent.search settings field (schema + sanitizer + strict parser);
web.ts's WebSearchResult is now the core SearchHit (re-exported).
Owner-approved design (2026-09-20): a Keys section right after General,
two groups over the merged auth API (GET /api/keys masked statuses,
PUT/DELETE /api/keys/:id, immediate effect, shape-gated 400s):
- Model providers: OpenRouter pinned as an always-visible row (the
app's lifeline — synthesized when absent so first boot shows it),
stored provider keys render as they appear, and an Add-provider
dropdown lists every pi-ai provider that takes an API key. The
dropdown reads GET /api/keys' optional providers array — the
Platform interlude (master-routed) derives it from pi-ai's own
env-key table; until it lands the group shows a pending note
(rolePins pattern — absent field, no drift, no guessed routes).
- Tools & services: the curated rows — Deepgram (dictation) and the
Google pair (search key + CSE ID) — with description hints and docs
links (external links route through the Electron shell to the real
browser).
- Rows: always-visible paste inputs (owner choice; no reveal —
plaintext never returns from the store), masked status line
(…tail · chars · environment|saved), the shadowedByEnv explanation
when a real env var owns the name, per-row inline 400 messages, Save
on Enter/button, Delete when present (env-owned keys honestly keep
their env status after a file delete).
- Unknown auth.json vars surface as read-only dimmed rows — preserved
by the store, not editable through the curated surface.
classifyKeys/keyStatusLine pure exports drive the two-group
projection; tests: SSR loading state, first-boot synthesis, provider
row classification, addable filtering, unknown-var read-only status
line formatting. Nav grows to six sections (Keys second).
Live-verified: nav order, structure, bad-paste 400s inline, save
round-trip with env-shadow explanation, delete round-trip, env-owned
OpenRouter status stability. Gates: typecheck, lint, 748/748, build.
Provider-keys interlude (owner spec, 2026-09-19): any pi-compatible
provider's key is manageable, not just the curated set.
GET /api/keys now also returns providers: {id, envVar, label}[] — every
pi-ai provider that takes a plain api-key env var (33 today), derived
from pi-ai's own provider→env-var table. No-drift mechanism: the table
is generated from pi-ai (builtinProviders + findEnvKeys over a
truthy-for-every-var proxy env) and pinned by
tests/auth-provider-keys.test.ts, which re-derives the truth at test
time and asserts EXACT equality — a pi-ai upgrade fails the gate loudly.
Owner-spec exclusions: github-copilot (OAuth), amazon-bedrock (AWS),
google-vertex (ADC), azure-openai-responses (base URL), the cloudflare
pair; anthropic keeps ANTHROPIC_API_KEY only. OPENROUTER_API_KEY
graduates from the curated catalog to the provider table (dedupe — the
UI pins it always-visible); curated stays Deepgram + the Google search
pair. Statuses: curated + present vars + unknown file vars — absent
provider keys never spam rows; the dropdown is discovery.
Write side: PUT/DELETE accept provider env vars (generic truncation
guard — trim, no whitespace, ≥12; family checks stay on the curated
three). Present-in-env provider vars surface as status rows so
env-wins/shadow semantics stay honest.
- Toggle (owner bug report): the ON disc sat flush against the pill's
right edge — translate-x-4.5 left only a 1px sliver; now translate-x-4
for a 2px inner inset both states (off: 3px left inset; on: 3px right
inset — measured live, symmetric).
- Toggle colors (owner ask): ON is a gray track (muted-foreground) with
a WHITE disc (foreground) — the full-white track was too loud; OFF
stays the muted track with the gray disc.
- Nav spacing (owner ask): gap-1 between the section nav buttons so the
hover highlights no longer touch.
- Role dropdowns (owner ask): the menus were clipped by the dialog's
overflow frame — they now portal to document.body with fixed
positioning against their trigger (AnchoredMenu), right-aligned,
repositioned on scroll/resize, so they flow over the whole screen
outside the settings dialog. Verified: a bottom-row menu extends
137px past the dialog's bottom edge; search + pick + Default-clear
work through the portal; Esc and inside-dialog clicks close the menu
but not the dialog.
- Thinking trigger (owner ask): fixed w-20 — the width the Default
state needs — so picking levels no longer shifts the row; the model
trigger takes the same width as a minimum (its values vary in length).
- Role hints (owner ask): ALWAYS visible and naming the actual default —
'Default: <model>'. The resolved per-role pins are not client-side
yet: master routed rolePins to the Platform stream (GET /api/models
extension, standalone commit); until that merge the rows read the
'config pin' fallback and light up on rebase. rolePins also lets the
thinking list use the pinned model's real supportedLevels when it's
in the catalog.
Also: staging repair commit 270db53 — the round-1 dialog rewiring
(sidebar row, chord, redirect, keyframes) was listed in 27d4f33's
message but never staged; committed as catch-up.
Live-verified on the worktree dev server. Gates: typecheck, lint,
701/701.
Round 1 (27d4f33) listed sidebar.tsx, keyboard-shortcuts.tsx,
app/settings/page.tsx and the globals.css keyframes in its message but
they were never staged. This commits exactly that content: the sidebar
Settings row as a button calling the dialog provider, the mod+, chord
opening the dialog, /settings redirecting to /chat/new, and the
settings-pop keyframes (reduced-motion aware). No new changes —
catch-up staging only. (next-env.d.ts churn left untracked-in-commit as
dev-server noise.)
- Toggle knob (bug report): the knob span had no left anchor, so it sat
at its inline static position — right-edge in off, overflowing in on.
Now left-0 + the intended 2px/18px translate; verified live: 3px from
left when off, 1px right inset both states.
- Role model/thinking dropdowns (owner ask): the EXACT chat model
selector dropdown, not a lookalike — the fuzzy-search + arrow-walk +
Enter machine moved from model-picker.tsx into the shared
components/settings/model-menu.tsx (ModelMenuList/ThinkingMenuList),
ModelControl now renders the same bodies, and the agent roles open
them downward with a pinned Default row (clears the override). The
collapsed trigger keeps the thin select look (owner: 'the collapsed
look is good'). Esc claims and closes only the menu (the dialog
stays); a backdrop click is left to the dialog's own close.
- Sub-groups (owner ask): SettingsGroup — Models / Tools / System
prompts inside Agent, each with a separator + quiet label; section
headings more pronounced (text-sm, full-foreground).
- Graying (owner ask): graph-view render-panel convention — the WHOLE
row dims (opacity-40) and the control locks; the row owns the dim so
no double-opacity. Applied to the graph ladder, the mode row, and
prompt rows without an override file. The 'needs X on' prose is gone.
- Hints pruned (owner ask): mechanics-explaining lines removed — the
ladder mention, 'App-level behavior', 'Applied live as CSS
variables', per-row explanations. Only the keyboard storage note
stays, reworded 'Stored on this device' (desktop app — localStorage
is the Chromium profile in Application Support, not 'this browser').
Live-verified: knob geometry both states + PUT round-trip, menu
search/pick/clear through the record, thinking set/clear, Esc layering,
ladder dim 0.4 with siblings full, pruned phrases absent. Gates:
typecheck, lint, 701/701.
The dialog's content wrapper added px-6 py-5 ON TOP of SettingsSection's
own padding (48px horizontal, 81px top — measured live). The wrapper is
now bare; the section component owns its rhythm, and the loading/error
states carry their own padding. Section box now spans the scroll column
(61px from the dialog top = the 60px header band), text inset 24px.
Gates: typecheck, lint, 701/701.
Owner decisions this wave: a centered modal over everything (not a page
— a settings column in the main area next to the session list would read
as two sidebars), left section nav in the dialog, modal-only (the
/settings URL redirects to /chat/new), light mode deferred to its own
wave (the mode control stays honestly disabled). An actual OS window is
an Electron-round feature — the sections are surface-agnostic (API +
localStorage only), so the shell re-mounts there with near-zero churn.
- components/settings/settings-dialog.tsx: SettingsDialogProvider at
the AppShell level (portal-rendered dialog, z-50 over the dock/graph
chrome). ~920×620 centered frame, 60px header with the quiet CMU
title + ✕, w-44 text-only nav (session-list mono language, active =
bg-accent, no icons), one scrolling content column mounting one
section at a time. Escape / backdrop / ✕ all close. 150ms fade+2%
settle scale (settings-pop), reduced-motion honored. The record +
single write seam moved here from the thin page: one record instance
per dialog, section switches never refetch, appearance writes still
restyle the app LIVE behind the dialog.
- Entry points rewired: the sidebar Settings row is a button calling
open(); the mod+, chord opens the dialog instead of routing.
- app/settings/page.tsx: redirect to /chat/new (nothing links into a
dead page).
- SettingsDialogBody exported without the portal — the SSR-testable
frame (portals render nothing under renderToStaticMarkup).
Live-verified: exact centering, all three close paths, chord open,
appearance prose-size restyles the chat behind the open dialog
(16→20px), section switching retains the record, keyboard section
renders all 21 rows, no console errors. Gates: typecheck, lint,
701/701 (5 new dialog tests), build.
Settings interlude (owner request, 2026-09-19): the route now also returns
rolePins: Record<BackgroundModelRole, {model: {provider, id},
thinkingLevel}> — the six background roles' RESOLVED models (the user's
agent-models override falling back to the config.ts MODELS pin), so the
settings UI shows each role row's 'Default: <actual pinned model>' instead
of a generic config caption. Same resolution the agent factories use
(effectiveSettings), so the caption can never drift from what runs.
Pure projection (rolePinsFor) + the fs wrapper (catalogRolePins); pins
tested against config defaults and model/thinkingLevel-only overrides.
BACKGROUND_MODEL_PINS exported from stores.ts for the test (was local).
Settings interlude (owner request, 2026-09-19): the route now also returns
rolePins: Record<BackgroundModelRole, {model: {provider, id},
thinkingLevel}> — the six background roles' RESOLVED models (the user's
agent-models override falling back to the config.ts MODELS pin), so the
settings UI shows each role row's 'Default: <actual pinned model>' instead
of a generic config caption. Same resolution the agent factories use
(effectiveSettings), so the caption can never drift from what runs.
Pure projection (rolePinsFor) + the fs wrapper (catalogRolePins); pins
tested against config defaults and model/thinkingLevel-only overrides.
BACKGROUND_MODEL_PINS exported from stores.ts for the test (was local).
Owner report: the scrollbar pressed against the slider content. Panel
w-64 -> w-72 and the inner scroll column gains pr-2.5, so the spacing
is concentric: content -> 10px -> scrollbar -> 10px -> panel edge. The
scrollbar itself is NOT moved — it keeps its distance from the panel's
right border; the panel simply widens to give it air.
- Corner rounding back (owner, 2026-09-20): the four controls return to
rounded-xl — 16px in this theme, identical to the composer shell's
rounded-2xl (verified computed-style equal). Inner elements (search
input, import button, cost hover) stay concentric: 16 - 4px padding
= rounded-lg (12px), the composer's own concentric math.
- Equal spacing: the cluster pins 8px from BOTH edges (top-2 + right-2),
still flush with the sidebar toggle's header band (top 8px).
- Stacking: the actions row is now relative + z-20 — an open settings or
coverage dropdown paints over the cost number below it (owner report:
it layered ON TOP of the panel, still hoverable/clickable). The row is
a stacking context inside the column, so its dropdowns cover the
number and clicks land on the panel; the number resurfaces untouched
when the panel closes (verified with elementFromPoint).
- Rectangular look (owner, 2026-09-20): the four top-row controls drop
rounded-xl (16px theme) to rounded-sm (4px) — gear, coverage, search
container + input, import container + button; the cost number's hover
highlight joins the family. Dropdown panels keep their softer cards.
Owner report: the controls folded onto two rows (search+coverage /
import+gear) — the 2026-09-17 flex-wrap kicking in, plus a real bug: my
previous wave moved max-w-[calc(100%-9rem)] onto the shrink-wrapped
column wrapper, where the percentage reference broke and the wrap fired
far too early. Owner wants the controls to read as header content.
- The width cap moves to the absolute column itself (100% resolves
against the full-bleed parent, as before): max-w-[calc(100%-5.5rem)].
- One row, NEVER wraps (owner rejected the two-row fold): search is the
flexible element (w-56 + min-w-0, shrinks under the cap); the other
controls are shrink-0.
- All controls slimmed into the header band: top-2 (8px) matching the
header's py-2, 36px tall matching the toggle's h-9 — size-9 buttons,
h-7 import button, px-1 py-[3px] containers (border included = 36).
- Cost number + pipeline pills stay below the band, unchanged.
Owner-directed placement wave (2026-09-20): the bottom-left stack
overflowed the composer in narrow windows, and the pill chrome was
too prominent for a passive number.
- The cost surface is now JUST a number (cumulative dollars) top
right, below the actions row — no pill container, hover-highlight
kept, dropdown breakdown kept, viewport-capped + scrollable.
- Same dismiss pattern as the settings gear: outside click or Escape
closes (shared usePopoverDismiss; two dropdowns never open at once).
- Running-pipeline pills moved under the cost number in the same
top-right column — one right-aligned column grows downward from the
top, so no window width can push chrome over the composer.
- Cluster namer bills the money channel now: per-step usage + model
captured via onStep, persisted as NamingRunUsage records to
data/graph/naming-runs.jsonl (idempotent per startedAt; failed/aborted
runs persist too — money spent either way). callUsage promoted to
extraction.ts module scope for reuse.
- core/cost-summary.ts: the pure fold behind the pill — chat runs,
notes-source runs, and naming runs into stage totals (extraction /
audit / naming) + newest-first recent runs. Dollars INFERRED read-time
via prices.ts, never stored; unpriced models excluded-but-counted
(render '—', never a silent zero); tokens always sum.
- GET /api/graph/costs (src/server graphCosts composition, thin route).
- Graph view: bottom-left cost pill (cumulative dollars headline) +
expandable breakdown panel (stage rows with tokens secondary, recent
runs with time/title/merged/cost); fetched on mount, refetched when a
pipeline run finishes; merged into one bottom-left stack with the
running-pipeline pills.
- Tests: pure-fold suite, naming capture wiring (full importNotes ->
naming path), store idempotency + strict reads.
The auth/keys wave (2026-09-19): the server now owns the flat auth.json
map directly (LH_AUTH_FILE from main.cjs; repo-root auth.json in dev,
gitignored). The store reflects itself into the child's env at boot with
fill-gap precedence — real env (incl. .env.local in dev) always wins —
so every consumer keeps its plain process.env reads and saved keys take
effect immediately, no restart; main.cjs's spawn-time injection retired
(an env copy would shadow every settings-page change).
Curated 4-key catalog (OpenRouter, Deepgram, Google search pair) with
shape-only validation (no live pings — owner decision), 400s on bad
pastes, last-4+length masking (plaintext never leaves the store),
unknown file vars preserved + surfaced. Routes: GET /api/keys,
PUT/DELETE /api/keys/:id. Tests: catalog/store/composition, with the
env-sanitizing prologue (a dev shell may export real keys; tests use
throwaway values only).
The validation surface for the settings foundation — deliberately thin,
real read/write against the delta record, polish is a later wave.
Mount (owner decisions): dedicated page, single scroll; entry = sidebar
bottom row + ⌘/Ctrl+, (open-settings in the registry); chat defaults NOT
shown (they live on /chat/new); mode dark-only (light palette = design
wave); final tool list = research/demo/visual/pdf (master-adjudicated).
Sections (PUT /api/settings/[section], replace-whole per section):
- General: auto-update toggle.
- Agent: six background-role model+thinking selects (Default = config
pin; a stored id stays VISIBLE even when the catalog hasn't loaded or
dropped it — a select showing Default over a live override would lie),
the four tool toggles, prompt override switches (file-gated) with
source/override text editors over the segment routes.
- Appearance: applied LIVE as runtime CSS variables by an
AppearanceProvider at the root layout — proseFontSize → the one
reading-size var, fontFamily → --font-prose, background → --background
+ the derived raised/accent/edge palette (dark curve, today's exact
spacing: +8/+22/+47 per channel, clamped), sessionNameSerif →
--font-title (titles flip with ZERO chat.tsx edits), headingWeight →
new --lh-heading-weight token, bold/italic colors → the lh-ink vars.
Mode renders honestly DISABLED.
- Graph: the ladder grays a rung when any ANCESTOR is effectively off
(stored values persist, resolve inert — switch shows stored, graying
shows effective).
- Keyboard: view/rebind/reset over the registry; overrides persist in
lh:keymap and apply INSTANTLY (dispatcher reads per keydown); bare
modifier presses are ignored while armed; displayOnly actions list but
never rebind.
First-boot fix: {settings: null} is no-record, not fetch-failure.
CROSS-LANE (flagged for master): src/core/keyboard.ts gained the
open-settings action/binding and exports saveOverrides/loadOverrides
(one-liners; no existing pins); app/layout.tsx mounts the provider.
Live-verified: structure, record writes (general/tools/graph/appearance),
prose-size applying live (16→20px), rebind + chord navigation from
another page, ladder graying, no console errors. Gates: typecheck,
lint, 689/689 (28 new), build.
The other half-wired seam: Platform's settings 'agent.prompts' switches
had no consumer in the agent layer, and their effectivePromptSegments
mirrored the PRE-sources-v1 loader — the shared/ fragments dir (the
learner-files doctrine) was invisible to it, so a naive delegation would
have silently dropped the segment from both agents' prompts.
- src/core/prompt-segments.ts (NEW, pure): the mirror-layout path
grammar + segment types, defined exactly once; core stays zero-IO.
- src/agent/prompt-segments.ts (NEW, the CANONICAL discovery): base +
shared/ + per-agent fragments, override resolution, allSegmentPaths.
Composition is an agent concern; the agent layer reads its own tree
(the architecture law pins agent and store apart — the first direct
refactor attempt tripped the enforced import/no-restricted-paths
zone, hence the three-layer split).
- src/store/prompt-overrides.ts: slimmed to the override-file CRUD
behind the core port; shares the core grammar. Its doc no longer
claims to be the canonical mirror.
- teacher-agent: composeInstructions(kind, switches?) composes through
effectivePromptSegments — a segment whose switch is ON and whose
override file exists composes the override text. Switches-less calls
use the cached pure-source composition (byte-identical to the old
loader, pinned by test); AgentBuildOptions.promptSwitches threads
effective.agent.prompts per turn, composing fresh so override-file
writes flip the very next turn.
- server barrel: re-exports the agent module's resolution for the
settings routes (server→agent, the lawful direction).
Tests: byte-identical source pin, override swap-in (on/off/file-absent),
shared/ overridability in both agents, agent-construction threading,
updated segment-list pins with shared/ in composition order. This file
keeps owning PROMPTS_OVERRIDE_DIR (parallel-test discipline).
Gates: 671/671, typecheck, lint, build.
Reconciliation of the diverged tool-toggles seam (2026-09-19, master's
P2): Platform injected the resolved delta as an ad-hoc intersection on
AgentBuildOptions while the factories' enabled? param sat unread — the
seam was inert on both sides.
- teacher-agent: AgentBuildOptions gains toolToggles?: EnabledTools;
both constructors thread it to the factories (createTeacherTools /
createProberTools). An explicitly injected opts.tools registry is
never filtered — the caller owns it.
- Vocabulary ADJUDICATED with the user (2026-09-19): TOGGLEABLE_TOOLS is
the definitive list — the job tools only (research/demo/visual/pdf).
quiz/ask_user_question stay always-on forever (the prober's flow is
graded-quiz brackets -> probe_done; quiz-off collapses assessment and
teaching doctrine is built on graded verification — the wedge danger);
the learner-fs set, plan tools, and probe_done also always-on.
- settings-body (write side): unknown tool keys reject with 400 + the
supported list, mirroring the prompt-switch validation; the read-side
sanitizer stays lenient for forward-compat.
- chat-handler: the intersection is gone (field now first-class) and the
seam comment states the adjudicated vocabulary.
Gates: typecheck, 28 new/updated tests green (tool-toggles-bridge,
question-tools, settings-body), chat-flow + settings suites green.
Root cause of the live-test bugs (2026-09-19): pi passes every run's
AbortSignal to tool execute, but toPiTool dropped it — agent.abort()
only landed at the next step boundary, so a long local grep held its
turn hostage until the dev server's memory restart killed the run
mid-tool, freezing the record at its write-ahead state (the 'went
back in time' rollback).
- lh-tool: execute ctx gains signal (parent + timeout combined); every
call races a 30s system-level timeout with a 250ms cooperative grace —
abort kills a stuck tool but lets a poll-the-signal tool deliver its
partial results. Pre-aborted signals never fire listeners: checked
upfront. toolTimeoutMs is the test seam (pdfModelOverride idiom).
- fs-shared: walkFiles returns {timedOut, aborted} instead of throwing —
abort yields partial results.
- grep: the scan phase was unbounded (the walk's 10s deadline only
bounded collection) — same budget now checked per file; find/grep
check the signal and return partials with a notice.
- pending/chat: streamingToolActivity names the ACTUAL running tool —
a part sits input-streaming through its whole execution, so the old
shimmer called minutes-long greps 'Writing a question…'.
Tests: toPiTool guard (forward, abort, timeout, grace, question
bypass, ToolInputError passthrough), walk mid-abort, find/grep
pre-abort + mid-run abort, activity labels. Gates: 617/617.
Live-smoke follow-up the user approved (2026-09-19): the GEB read showed
"78 pages consulted" when the reader genuinely READ ~12 - pdf_search hit
snippets inflated the count. PdfResult now carries both:
- pagesRead: extract/render output entered the loop - the honest count
the badge and brief footer show ("read N pages", "Pages read: ...").
- pagesConsulted: every page whose content entered the loop, search-hit
context lines included - unchanged, still the citation audit set (the
reader's instructions still say "Pages consulted: N, N, ..." and the
footer still lists it when it exceeds the read set).
The unread-finish gate deliberately stays on CONSULTED: search hits are
genuine consultation (anti-fabrication duty), so a search-only brief is
honest and must deliver - pagesRead is a reporting refinement, not a
delivery gate. Pinned by the search-only faux test (read [], consulted
[1], delivered).
UI tolerates pre-split persisted records via ?? fallbacks (old steers
lack pagesRead).
User pivot (2026-09-19): no attachments UI at all. Pasting paths is native
for technical users and alien for everyone else - so the agent gets the
tools to find what the learner merely NAMES. The learner communicates in
messages; the agent locates and reads. Zero cross-stream seams: paths
already live in tool parts, so the sources "list" is the transcript.
- ls/find/grep: pi-verbatim schemas, descriptions, and output formats
(fd's glob semantics, rg's path:line: match format, pi's truncation
notices), ported to pure Node - no binaries, no shell-out, read-only by
construction. Deltas from pi: home-anchored resolution (the harness has
no cwd), .gitignore replaced by hard noise exclusions
(node_modules/.git/Library/.Trash), 10s walk timeout with partial results.
- read: description swapped to pi-verbatim (doctrine moved to the prompt);
relative paths now resolve against the learner's home like the rest.
- prompts/shared/05-learner-files.md: one minimal doctrine fragment
composed into BOTH agents (composeInstructions grew a shared/ dir,
before the agent's own fragments). teacher/30-jobs.md keeps only the
pdf-dispatch addendum.
- ToolCallCard: the generic quiet tool-call card the user specced -
collapsed one-liner (tool name + headline argument), expandable to full
input/output, errors red, image payloads never render. Registered for
read/ls/find/grep.
- ui-message.ts: TeacherUITools entries for the four tools (mechanical).
- tests: fs-tools suite (glob semantics, pi formats, exclusions, limits),
registry/card renders, shared-fragment composition pins, tool-registry
key updates, read re-anchor.
The browser e2e check on the live dispatch session found the tool-pdf
part rendered NO card: the artifact renderer registry had no pdf entry
(the doc comment literally says "add your renderer here"), and the typed
TeacherUITools union + the chat.tsx job-part enumerations (poll cadence,
dispatch nudge, settle-sync) all missed the new tool kind.
- PdfJobCard in job-card.tsx: the research JobCard idiom, kind pdf —
registered in artifacts/index.ts.
- ui-message.ts: pdf entry in TeacherUITools (fire-and-forget ack output).
- chat.tsx: two mechanical "tool-pdf" additions to the research/demo/visual
enumerations — UI-stream file, flagged for review at merge (same
treatment as the activity-dock type-forced entries).
- demos.test.tsx: live/settled dispatch-card renders + registry pin.
Live dispatch smoke against the Turbopack dev server (master's ask,
2026-09-19) caught two things unit tests cannot - they run unbundled:
- Bundling pdfjs-dist broke its node fake-worker: the chunk-relative
pdf.worker.mjs import 404s inside .next/dev/server/chunks. Fix:
serverExternalPackages + tracing includes for legacy/ + standard_fonts/
(next.config.ts - a clearly-marked seam, same precedent as bcdcd51; the
standalone output now ships the worker and font files, verified).
- Real-world PDFs warned about missing standardFontDataUrl (non-embedded
standard fonts silently fall back) and flooded the log with JBIG2
warnings on scanned files. Fix: standardFontsDir() + verbosity 0 in
both the node ops and the headless canvas shim.
Verified live end-to-end on GEB (802pp, text layer): teacher dispatch,
12-step read with vision renders, brief with accurate page citations,
wake turn folding the resolution (Chapter IX, pp. 268-270) into the
lesson. Scanned/DRM Polya correctly refuses to fabricate citations.
Learner source files, on the teacher's own terms (nothing auto-injects):
- read tool (src/agent/tools/read.ts): pi-read port — path/offset/limit,
2000-line/50KB truncation with use-offset continuation notices, image
files (jpg/png/gif/webp/bmp) returned as native image content parts
(new LhToolImageResult escape hatch in lh-tool.ts). Always-on in both
the prober and teacher registries (user-decided 2026-09).
- pdf-reader sub-agent (JobKind 'pdf', toggleable, ack-and-steer): triage
via pdf_info (pdfjs text layer: per-page text/image/math-density),
targeted pdf_extract, regex pdf_search (hits count as consultation),
and pdf_render — pages painted by pdfjs onto a canvas shim in headless
Chrome (the pdfium viewer doesn't paint headless), screenshot fed back
image-in-the-loop (visual-maker idiom, providerSafePng applied). The
unread-finish gate bounces a zero-consultation brief once. Teacher gets
a text brief with page citations only; renders never leave the loop.
- MODELS.pdfReader = qwen/qwen3.8-flash (user override 2026-09-19: the
look-at-renders workload wants the vision-proven model; catalog listed
glm-5.3-flash as image-capable but qwen is the known-good daily driver).
- UI: PdfCompleteBadge + PdfBriefCard (steer-card, job-card), dispatch
card + activity-dock kind entries (type-forced, flagged for UI review).
- Prompts: 'Learner source files' section in teacher/30-jobs.md; read
line in prober/10-probe-doctrine.md. Doctrine rides tool descriptions
per the self-contained-tools principle.
One key, master pre-approved content (2026-09 master sync): the pdf-reader
is of the teacher/researcher family — dense image→text extraction wants the
stronger multimodal; qwen/qwen3.8-flash stays specialized for visualMaker
(generation). Owner can override in one line after live testing.
Part 1 — tool availability (the settings seam, machinery generic):
- core/pending.ts: TOGGLEABLE_TOOLS (today: research, demo, visual —
the model-facing tool names), EnabledTools = the JSON-native seam
shape Partial<Record<string, boolean>> (absent key = enabled, so old
records behave exactly as today), filterEnabledTools shared helper.
quiz/ask_user_question are always-on FOR NOW (user-decided); the
filtering is generic so future toggleables (question-tool variants,
the read tool, …) need no factory change.
- createProberTools/createTeacherTools take enabled?: EnabledTools; the
composition root (chat-handler, Platform's lane this wave) passes the
resolved settings through. probe_done is re-added after the filter —
always-on by construction (it ends the phase; a prober that can never
conclude is a lockout).
- Prompts stay STATIC under toggles this wave (user-decided); standing
principle recorded: tools ship self-contained usage guidance in their
descriptions; system prompts reference only always-on tools.
Part 2 — phase-based question-writing principles (user-locked wording,
drafted with the user over three iterations):
- NEW teacher/21-question-principles.md (composes after 20-teaching):
answerable-by-reasoning-from-the-session (the fairness rule that
filters unanswerable questions without forbidding visible answers),
never-just-reciting-your-words-back, PREFER problems that apply the
knowledge (preference, not hard rule — honest recall is the fallback,
not the habit), catch-confusion-early-and-nameable (wrong options as
real misconceptions), answer-is-signal-not-verdict.
- prober/10-probe-doctrine.md: 'no rush' retired; quick-measurement
directive in — every question moves an edge (bracket, narrow, or
characterize); a bracketed strand is done.
Tests: TOGGLEABLE_TOOLS pin, prober/teacher filtering (absent = full,
false drops exactly that tool, probe_done survives), prompt pins (the
principles compose verbatim into the teacher prompt, the no-rush
framing is gone from the prober). 547/547, typecheck/lint/build green.
Owner reframe (2026-09-18): the model + thinking + context controls on
the home graph view and /chat/new are not a draft overlay on a baked-in
default — they ARE the settings page for the default model, and the
user's last choice IS the default. BYOK first boot has no keys and
possibly no OpenRouter, so there is NO default to show: the controls
render 'no model' ('—') until the first pick.
The flash was the deeper symptom: the surfaces rendered from client
state that started empty and fetched truth afterward, so every visit
flashed the config pin (GLM/low — a dev artifact) for a few frames.
Fix at the root: both pages are now force-dynamic server components
that read the record (readDefaultSettings → initialSettings) and hand
it to the client — the first frame shows truth. Dynamic routes aren't
cached client-side (staleTimes.dynamic = 0), so every navigation
re-reads the record; the useDefaultSettings hook keeps only save-side
state (optimistic set + PUT). The GET-on-mount and its touch-guard are
gone.
ModelControl gains noDefaultModel (the default surfaces only): unset
settings render no model/level, never the catalog pin; the thinking
menu no-ops until a model exists. Chat surfaces keep the catalog
fallback — the engine runs the config pin when a session record has no
override, so the control keeps showing what will actually run.
Renamed draft→default throughout: data/default-settings.json,
GET/PUT /api/settings/defaults, useDefaultSettings. New sessions
still inherit the default on creation exactly as before.
Live-verified: first-boot 'no model' with zero flash, picker +
Shift+Tab cycle, values held across session→/chat/new→home roundtrips
and a reload (10×100ms samples, never the old default), zero console
errors.
Both new-session pages (the home graph view's topic dock and /chat/new)
held their model + thinking + knowledge-context choices in plain
useState(undefined) — every navigation reset them to config defaults.
Now both surfaces read/write ONE server-side record
(data/draft-settings.json via GET/PUT /api/settings/draft, the
render-settings pattern): whatever the learner last left the controls on
is what every later visit shows. useDraftSettings loads on mount with a
touch-guard (a slow GET never clobbers a fast choice), saves
optimistically. Session creation still carries the choice into the new
chat exactly as before; per-session settings are untouched.
The PUT validation is the exact per-chat contract — parseSettingsBody
extracted verbatim from app/api/chats/[id]/settings and shared by both
routes (unknown model/level → 400 with the supported list, never a
silent clamp). 400s on garbage, {} = the clear-overrides write.
Live-verified: Cmd+K+Enter model pick, Shift+Tab thinking cycle, context
slider — all held across home → session → home → /chat/new, and carried
into a created session's record.
The wake pump fires its turn with the steer INSIDE the request body but
dequeues the queue entry only after the turn returns 200 — so the entry
is still queued when the handler claims. The record doesn't carry the
steer yet (write-ahead persist hasn't run), so claimSteers claimed it a
SECOND time and the handler appended it: outgoing = [...body, ...claimed]
held two copies of the same deterministic steer id, and the write-ahead
persist saved that for the whole wake turn. The client's adoption poll
rendered both -> React duplicate-key warning (steer_ctx_<chatId>).
withMessageIds deduped only at onFinish, so the final record looked clean.
Fix: claimSteers(chatId, incoming) — a queued steer whose id is already in
the turn's incoming list is being delivered BY this very turn: finalized
and resolved, never appended again.
The walked row's ring-1 is a box-shadow painted OUTSIDE the border box;
the list's overflow-y-auto makes overflow-x clip at the padding box too
(CSS: a non-visible axis forces the other to auto), so the 1px halo was
shaved on both sides. Replaced with the quiz rows' bg-accent/40 filled
tint and added px-1 to the list so the highlight never touches the
edges (owner round 5).
Owner polish pair before the settings milestone:
- Model menu: arrows walk the filtered results (clamped, no wrap) while
focus stays in the search field; Enter picks the walked row or, with no
walk yet, the first result; typing resets the walk; click and Enter
share one pickModel path; walked row gets a muted ring + scrollIntoView;
cheat-sheet display entries added.
- Graph: window resizes re-anchor the camera so the world point under the
pre-resize viewport center stays under the new center — the graph stays
visually still while scaling (was top-left pinned). viewW/H tracked in
syncSize; re-anchor applied through the zoom behavior (persistence and
card-dismiss unchanged); kFit refresh as before. Pixel-verified: 7/7
center samples identical across a 300x200 shrink.
Tab/arrow focus on quiz/question option buttons and the don't-know row
showed Chromium's default focus ring — the abandoned look. outline-none
on the row buttons keeps the walk ring (bg-accent/40) as the only focus
indicator, so the appearance is identical before and after Tab.
Owner live-test rounds on waves A/B:
- Alt+arrows no longer ALSO walk the question rows (dock ignores
alt/meta/ctrl combos; session cycling keeps them exclusively)
- question walk clamps at the ends — no wrap (faster to navigate)
- plain Tab toggles focus between the thinking field and the answer
rows (walked row by default); focus follows the walk while in the
rows; Shift+Tab stays the global thinking-level cycle
- Esc in the sessions search blurs back to normal (claims the key so
the window Esc chain does not fire)
- cheat sheet gains the Tab-in-question display entry
amosblomqvist