toga-ai 1.0.749 → 1.0.750

package/knowledge/sessions/2026-09-02-talos-surface-layer-apeterson.md

@@ -0,0 +1,110 @@
+---
+type: session
+slug: talos-surface-layer
+title: Talos moved onto the surface layer; chat history, titles, launcher dim
+author: apeterson
+repos: [toga25-supply, toga-blox, dbchanges2]
+framework: "2.0"
+client: nychh
+status: active
+created: 2026-09-02
+updated: 2026-09-02
+---
+
+# Session: talos-surface-layer
+**Date:** 2026-09-02
+**Project/Repo:** toga25-supply + toga-blox + dbchanges2 (2.0)
+**Task:** Move the Talos AI assistant (feature gate + suggestion chips) off hardcoded frontend config onto the backend surface layer — off for all clients in Core, granted only to NYCHH — and finish the chat history / auto-title / launcher work started earlier in the same thread.
+
+---
+
+## What WORKED
+
+- **Loading bubble restored in host-render mode.** `toga-blox src/components/Talos/TalosPanel.tsx` now renders the synthetic thinking bubble in BOTH modes, because it is chrome derived from `isStreaming`/`progress`, not a message. Evidence: 2 new regression tests; blox Talos suite 31 passing.
+- **Chat history drawer + new chat, data-driven.** New controlled props `threads`, `activeThreadId`, `onSelectThread`, `onNewChat`, `threadsStatus`. `history` re-enables only when `threads` AND `onSelectThread` are both given; `newChat` only when `onNewChat` is. The panel sorts rows newest-first. Evidence: tests incl. ordering and "host content replaces the list".
+- **Opening an existing thread needs no transcript parser.** Verified in `node_modules/@langchain/langgraph-sdk/dist/ui/orchestrator.js` — `setThreadId` calls `#fetchHistoryForThread` and clears the stream when `fetchStateHistory: true`. Selecting a row is just "set threadId"; the existing LangGraph→blox mapper handles the rest.
+- **Auto-title polling.** `toga25-supply src/hooks/useTalosThreads.ts` `titlePollInterval` — 4s `refetchInterval` while any recent thread is unnamed, `false` otherwise, with a 2-minute age window. Evidence: 7 tests incl. server-clock-ahead and the never-named case.
+- **"Couldn't load your chats." over a full list fixed.** `threadsStatusFrom` returns "error" only when there is no data; blox gates all three drawer notes on `histRows.length === 0`. Evidence: regression test in each repo.
+- **Talos on the surface layer, RUN AND VERIFIED ON LOCAL.** `dbchanges2 Core/2026-09-02a - TalosAssistantSurfaceSeed.sql` → 2 elements, both `isVisible = 0`, suggestions row `itemCount = 4`. `dbchanges2 Client_Nychh/2026-09-02a - TalosAssistantEnable.sql` Section A → 3 rows: two `IS_VISIBLE='1'` + one `CONFIG` with `itemCount = 3` and `roleRestated = 'suggestion'`. Three NYCHH chips render in the browser. Developer confirmed: "that workds".
+- **Fail-closed FE gate.** `src/hooks/useTalosSurface.ts` — missing bundle, failed fetch, absent marker, or still-loading all resolve to disabled. `TalosStreamProvider` gained an `enabled` prop so a tenant without Talos never calls `/assistants`. 14 tests.
+- **Launcher dims under a modal.** `toga-blox TableRecordModal.tsx` sets `data-blox-modal-open` on `<html>` (a counter); `Talos.module.css` dims `.launcher` and stops the orbit ring under `:root[data-blox-modal-open]`.
+- **Surface bundle no longer cached to disk.** `src/App.tsx` `shouldDehydrateQuery` excludes the `talos`, `surface-meta` and `surface-meta-group` namespaces.
+- **End state:** toga25-supply 87 tests / 12 files passing; `npx tsc --noEmit -p tsconfig.app.json` clean apart from one pre-existing error; toga-blox 31 Talos + TableRecordModal tests passing; blox `dist/` rebuilt.
+
+## What did NOT work — DO NOT RETRY THESE
+
+- **A host-render branch that bypasses the panel's own message list.** The first `renderMessages` implementation replaced `msgs` entirely, which took the synthetic thinking bubble with it. Symptom: submit a question and get **zero** feedback until the answer appears — no loading UI, no streaming. The bubble is chrome, not conversation; never let a host slot remove it.
+- **Trusting supply's typecheck to prove a blox change reached the browser.** `npx tsc --noEmit -p tsconfig.app.json` resolves blox **types from source** through the `node_modules/@agilant/toga-blox` symlink, but Vite loads the package at **runtime from `dist/`**. Typecheck was clean while the browser ran stale blox code. Always `npm run build` in blox + `rm -rf node_modules/.vite` in supply.
+- **The earlier note that blox `npm run build` fails on a missing `tsconfig.app.json` is WRONG.** It builds fine (`tsc && copyfiles … && fix-esm-imports && fix-asset-imports`). Do not route around it.
+- **`status: isError ? "error" : …` for a React Query list.** React Query sets `isError` when a **background** refetch fails while KEEPING the data it already had. With the 4s title poll running, one failed poll printed "Couldn't load your chats." above a full, usable list. Report error only when there is no data.
+- **A drawer error message with no empty-list guard.** It rendered *alongside* the rows, producing a screen that says loading failed while showing the loaded data.
+- **Building the title polling before checking that ANY thread had a title.** Every NYCHH thread reads "New conversation", including ones days old and far outside any poll window — so this was never a client timing bug. Naming is a per-assistant setting (`thread_name_generation_enabled`, default `true`, plus `thread_name_model`) on `GET`/`PATCH /api/assistants/{assistant_id}/config`. The polling is correct and will work the moment the server writes a name, but it could not fix this.
+- **A cross-schema `JOIN Core.SurfaceElements` in a `Client_*` file.** Works on local/beta, **fails in production** — Core and Client_* are on separate clusters. Error there: `Table 'Core.Surfaces' doesn't exist`. Prod needs the read-ids-on-Core → insert-literals-on-client two-step.
+- **Schema-qualifying a Core-only migration (`Core.Messages`, `Core.Surfaces`).** api2 can rename the Core DB via `[database] core_dbname`, so qualifying breaks exactly the environment that renamed it. Core-only files must use UNQUALIFIED names and be run while connected to Core.
+- **Running an unqualified `SurfaceElements` query while connected to `Client_Nychh`.** Error: `Table 'Client_Nychh.SurfaceElements' doesn't exist`. `SurfaceElements`/`Surfaces`/`Messages` are **Core-only**; a cross-schema verify must qualify every Core table.
+- **Assuming the launcher-not-dimmed bug was z-index.** It was not. `.launcher` has no z-index, blox `.header` has no z-index or position, supply's `.headerActions` has neither, and `.backdrop` is `position: fixed; z-index: 40` — so the launcher was already painted under the backdrop and its clicks already swallowed. The real cause: `.backdrop-right`/`.backdrop-left` is only `rgba(0, 0, 0, 0.2)`, and a 20% black wash over a **white** button still reads as active. Do not go looking for a z-index.
+- **One surface element per suggestion chip.** Replaced before it shipped past local. A tenant could only switch on questions **Core had already seeded**, so changing a tenant's wording needed a new Core migration for every phrasing.
+- **A bare JSON array as a `CONFIG` override value.** A `CONFIG` override **replaces** `config` wholesale — `_underscore Model/Core/Surface.php:839` assigns, it does not `array_merge`. A bare array passes the `is_array()` check and wipes `config.role`, so the frontend stops recognising the element and the chips **silently disappear with no error anywhere**. The override must restate `"role":"suggestion"`.
+- **Putting override JSON in `SurfaceOverrides.value`.** It is `varchar(255)`; any real chip set overflows it. Use `c_longValue` — the resolver falls back to it when `value` is NULL/'' (`Surface.php:907`).
+
+## Not tried yet (candidates for next session)
+
+- **Run the SQL on beta and prod.** Local only so far. Prod = Section B (read ids on the Core cluster) then Section C (literal-id insert on the client cluster). **Never Section A in prod.**
+- **Wire Stop to `cancelTalosRun`** instead of `stream.stop()`. This is a **real defect**: `stream.stop()` only drops the client transport while the run keeps executing and billing. Needs `run_id` from the `metadata` SSE event (handoff §8.5).
+- **`fromTalosTranscript()` + terminal-completion reconciliation** (handoff §8.11 / §8.8). Message ids in `src/providers/TalosRuntimeProvider.tsx` are `talos-${index}` placeholders; feedback needs a durable server `message_id` + `run_id`.
+- **Message actions** (copy, thumbs up/down) via `ActionBarPrimitive`, and the thumbs-down dialog (handoff §9). Blocked on the durable ids above; copy alone is doable now.
+- **Rename / delete thread UI.** `renameTalosThread` / `deleteTalosThread` already exist in `src/api/talos.ts` and are unused. Both endpoints are real (`PATCH`/`DELETE /threads/{thread_id}`). Decide the `If-Match` question first: the handoff doc shows it quoted, the live spec types it as a plain optional string, and our client sends it bare — recommendation was to **drop the header** rather than guess.
+- **Make supply's header `inert` while a modal is open.** The launcher is still keyboard-reachable behind a modal; `pointer-events: none` stops the mouse only. Affects all header controls, so it is a deliberate supply-wide change.
+- **Rule on reserved-literal ids vs `AUTO_INCREMENT`** for Core surface seeds. `knowledge/2.0/apps/dbchanges2/features/surface-layer-schema.md` currently documents BOTH branches. Note the shipped `Core/2026-08-12a` navigation seed already uses `AUTO_INCREMENT`, so the "never AUTO_INCREMENT" rule was already contradicted by merged code.
+- **Per-role Talos gating / per-role chip sets.** Current grants are client-wide (`roleId` NULL) — every NYCHH user incl. devteam gets Talos. Two role-scoped `CONFIG` rows would resolve by `ORDER BY (roleId IS NULL) DESC, (personaId IS NULL) DESC, id ASC`, so the **higher id wins arbitrarily** for a multi-role user.
+
+## Current file state
+
+| File | Status | Notes |
+|------|--------|-------|
+| `dbchanges2 Core/2026-09-02a - TalosAssistantSurfaceSeed.sql` | new, uncommitted, RUN ON LOCAL | Surface `talos-assistant` (DRAWER, not record-bound), 2 elements both `isVisible=0`; suggestions element holds Core's default 4 items. Unqualified table names. Teardown in footer. |
+| `dbchanges2 Client_Nychh/2026-09-02a - TalosAssistantEnable.sql` | new, uncommitted, RUN ON LOCAL (Section A only) | 3 sections: A single-cluster, B read ids on Core, C literal insert on client. Writes 2 `IS_VISIBLE` grants + 1 `CONFIG` with NYCHH's 3 questions. |
+| `toga25-supply db-migrations/PLAYBOOK.md` | modified | 2026-09-02 change-log entry incl. prod cross-cluster procedure and the `SurfaceOverrides` NULL-unique-key gotcha. |
+| `toga25-supply src/hooks/useTalosSurface.ts` (+ `.test.ts`) | new | Fail-closed gate + tolerant `readItems` parser. 14 tests. |
+| `toga25-supply src/hooks/useTalosThreads.ts` (+ `.test.ts`) | new | Thread list, `titlePollInterval`, `threadsStatusFrom`, `toThreadSummary`. 12 tests. |
+| `toga25-supply src/providers/TalosStreamProvider.tsx` | modified | `enabled` prop; threads/selectThread/activeThreadId in context; refresh on threadId assignment + run-end. |
+| `toga25-supply src/providers/TalosRuntimeProvider.tsx` | new (earlier in thread) | assistant-ui `ExternalStoreRuntime` bridge. Message ids are index placeholders. |
+| `toga25-supply src/components/TalosThread/` | new (earlier in thread) | assistant-ui thread + safe markdown components. |
+| `toga25-supply src/hooks/useTalosSession.ts` | modified | Takes `enabled`; returns `disabled` when gated off. |
+| `toga25-supply src/layout/AppLayout/AppLayout.tsx` | modified | Gates launcher + panel on `useTalosSurface().isEnabled`; passes surface suggestions, threads, history handlers. |
+| `toga25-supply src/App.tsx` | modified | `shouldDehydrateQuery` excludes `talos`, `surface-meta`, `surface-meta-group`. |
+| `toga-blox src/components/Talos/TalosPanel.tsx` | modified | `renderMessages`, thread-list props, loading bubble in both modes, `NO_SUGGESTIONS` default (DEFAULT_SUGGESTIONS deleted). |
+| `toga-blox src/components/Talos/types.ts` | modified | `TalosThreadSummary`, thread props, `renderMessages`. |
+| `toga-blox src/components/Talos/Talos.module.css` | modified | `.historyNote`; launcher dim under `:root[data-blox-modal-open]`. |
+| `toga-blox src/components/Talos/README.md` | modified | Suggestions are host-supplied; chat-history section. |
+| `toga-blox src/components/TableRecordModal/TableRecordModal.tsx` | modified | `data-blox-modal-open` counter on `<html>`. |
+| `toga-blox src/components/TableRecordModal/tableRecordModal.module.css` | modified (earlier in thread) | `--talos-dock-width` awareness. |
+| `toga-blox dist/` | rebuilt | Required for the browser; gitignored. |
+
+**Nothing is committed in any of the three repos.**
+
+## Decisions made
+
+- **Talos is gated by the surface layer, OFF for every client in Core.** Rationale: Talos answers questions from a tenant's live Supply data through an external AI service; a tenant must not inherit that from a migration. Rejected: a build-time env flag (not per-tenant) and defaulting ON (a data-exposure decision made by a file instead of a person).
+- **The feature switch is a marker element, not `Surfaces.isVisible`.** The override cascade is keyed by `surfaceElementId` and is never applied to a Surfaces row's own `isVisible`, so overriding the surface row silently does nothing. Same trick as the `config.role='sectionVisibility'` markers.
+- **Chips are ONE element with a `config.items` array of `{label, prompt, icon}`.** Rationale: per-chip elements let a tenant only enable questions Core had already seeded. Rejected: one element per chip (needs a Core migration per phrasing) and an array of bare strings (collapses label/prompt/icon and loses the icons). Trades accepted: labels are not `Messages` keys so `MessageTranslations` cannot translate them; and chip SETS are per-scope rather than per-chip.
+- **The chip payload lives in `config`, not an `Actions` row with `type='RUN_TALOS'`.** `RUN_TALOS` is in the enum but **no `Actions` row has ever been seeded in dbchanges2** and there is no FE action-registry entry for it. `config` is emitted verbatim into the bundle. Same trade `Core/2026-08-12a` made choosing `config.path` over `Actions`/`NAVIGATE`.
+- **`AUTO_INCREMENT` + `NOT EXISTS` guards on natural keys, not a reserved literal id block.** Reserving requires verifying `MAX(id)` against every environment first; these files are purely additive and id-agnostic. Matches the `navigation` seed. Rejected: reserved literals (unverifiable without DB access, and the ids are read off Core at run time in Section B anyway).
+- **The per-client file keeps `Client_Nychh.` qualification while the Core file drops `Core.`.** Run against the wrong cluster the qualified one fails loudly on a missing schema instead of silently granting the feature to another tenant; the Core schema name is not guaranteed.
+- **The `NOT EXISTS` guard is load-bearing, not decoration.** `SurfaceOverrides`' unique key is `(surfaceElementId, surfaceId, personaId, roleId, languageId, attribute)` and MySQL treats NULLs in a unique key as **distinct** — client-wide grants have persona/role/language all NULL, so the index accepts duplicates.
+- **Permission/feature surfaces are not persisted to localStorage.** `surface-meta` is fetched with `staleTime: Infinity`, so a persisted copy is never refetched and a grant — or a **revoke** — would not reach a browser for up to the persister's 24h default `maxAge`.
+- **The modal-open marker is a root-element attribute and a counter.** An attribute because the launcher renders outside the modal's portal so no React state reaches it (same boundary-crossing trick as `--talos-dock-width`); a counter because modals stack and the marker must survive the inner one closing. Rejected: threading a prop from every modal layout.
+- **`config.items` parsing is tolerant, not strict.** `config` is a hand-edited JSON column that differs per tenant, so one bad item costs one chip rather than every chip or a render crash.
+
+## Blockers
+
+- **Thread auto-titles are broken server-side.** Every NYCHH thread reads "New conversation". Naming is per-assistant: `thread_name_generation_enabled` (default `true`) + `thread_name_model` on `GET`/`PATCH /api/assistants/{assistant_id}/config`. Either it is `false` on the `TOGa Supply` assistant or the Bedrock naming model is unreachable in that deployment. **A consumer app cannot fix this.** Open with `akhokhani`; NYCHH `assistant_id` `c7981164-1fe9-5878-b115-85c38dadad43`.
+- **Nothing is committed in toga25-supply, toga-blox or dbchanges2.** blox `dist/` is gitignored, so no other consumer sees any of this until blox publishes.
+- **Beta and prod SQL not run** — the feature is invisible in those environments (the fail-closed gate working, not a regression).
+
+## Exact next step
+
+> Wire Stop to `cancelTalosRun` in `toga25-supply src/providers/TalosStreamProvider.tsx` — replace `stream.stop()` in the `stop` callback. It is a real defect: `stream.stop()` drops only the client transport while the run keeps executing and billing on Aegra. You need the `run_id` from the `metadata` SSE event (handoff §8.5), so capture it in the `useStream` `onCustomEvent`/metadata handler first, then call the existing `cancelTalosRun(token, { threadId, runId })` from `src/api/talos.ts`.
+
+---
+_Saved by /session-save on 2026-09-02_

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.749",
+  "version": "1.0.750",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",