toga-ai 1.0.735 → 1.0.737

package/.claude/settings.json

@@ -9,6 +9,15 @@
             "timeout": 3000
           }
         ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/toga/plain-talk.js\"",
+            "timeout": 3000
+          }
+        ]
       }
     ],
     "PreToolUse": [

package/knowledge/sessions/2026-09-02-talos-streaming-supply-apeterson.md

@@ -0,0 +1,307 @@
+---
+type: session
+slug: talos-streaming-supply
+title: Talos streaming chat BUILT in toga25-supply + blox controlled panel
+author: apeterson
+repos: [toga25-supply, toga-blox, talos]
+framework: "2.0"
+client: shared
+status: active
+created: 2026-09-02
+updated: 2026-09-02
+---
+
+# Session: talos-streaming-supply
+**Date:** 2026-09-02
+**Project/Repo:** toga25-supply + toga-blox (2.0)
+**Task:** Build the live Aegra/LangGraph Talos chat in `toga25-supply` — app-local stream provider, controlled `TalosPanel` in blox, markdown/link rendering, dock-aware modal geometry — and align it to the backend team's implementation handoff.
+
+> **Supersedes `2026-08-28-talos-streaming-supply-apeterson`**, which was research/design only
+> ("NO application code was written"). This session wrote the code. Read that file only for the
+> original decision rationale; its status lines are stale.
+
+> **⚠ READ FIRST: `~/Desktop/toga-supply-streaming-chat-handoff.md`** (1230 lines, from
+> akhokhani/backend, contract date 2026-08-28, "implementation-ready"). It is the authoritative
+> contract for endpoints, the event/privacy boundary, progress copy, feedback, and markdown scope.
+> It was NOT in this session's context until late — it had been uploaded to a *different* Claude
+> conversation ("cont: talos-streaming-supply"), and `/session-resume` restores the saved summary,
+> not attachments. **Keep it on disk and name the path in every future session file.**
+
+---
+
+## What WORKED
+
+- **Aegra accepts a supply-issued api2 JWT — blocker (c) from the prior session is CLOSED (World A).**
+  akhokhani supplied a working `GET /assistants` call whose bearer had `aud: https://nychh.togasupply.com`
+  (a **supply** hostname), `iss/sub: http://api.beta.togahub.com`, 3600s life. No token exchange,
+  no `/auth/delegator`, no auth-exchange layer needed.
+- **`assistantId` is PER-TENANT and must be fetched at runtime.**
+  `GET /assistants?limit=100&offset=0` with the bearer. NYCHH returns one: name "TOGa Supply",
+  `graph_id: deep_agent`, `metadata.customer_facing: true`, `read_only: true`,
+  `tenant_slug: "NYC Health + Hospitals"`. Selection rule adopted: prefer
+  `metadata.customer_facing === true`, else the full list, take the first, `console.warn` when >1.
+- **CORS is NOT a blocker — blocker (a) is CLOSED.** Aegra returns
+  `access-control-allow-origin: *` on the OPTIONS preflight for **both** a local dev origin
+  (`http://nychh.dev.sandbox.togasupply:5173`) and the prod origin. The old worry about needing to
+  spoof `Origin` for the `Domains` gate is **moot for supply**: supply's real browser origin *is*
+  the registered hostname, so the browser sets it correctly for free. (talos had to spoof
+  server-side only because its origin differed.)
+- **`https://api.togaiq.com` (production Aegra) is LIVE.** `/health` 200, `/info` 200,
+  `/assistants` 401 without a token. Developer is running against it and it works end-to-end
+  (real answers about real NYCHH orders). `.env.development` now has
+  `VITE_TALOS_API = 'https://api.togaiq.com'` and `VITE_API = 'https://api.togahub.com/v2'`.
+- **The blox `TalosPanel` controlled-mode contract change is BUILT** (was only DECIDED before).
+  New optional props: `messages`, `isStreaming`, `progress`, `onSubmit`, `onStop`, `connection`,
+  `renderMarkdown`. Controlled mode keys off `messages` being **passed at all**, so BDR and
+  `createTalosStubAdapter()` are untouched. 22 blox Talos tests pass, including two that pin
+  uncontrolled behaviour as unchanged.
+- **Final-answer-only reveal implemented** per handoff §8.6/§8.8. Chunks buffer privately; the
+  assistant turn is revealed only on `talos.run.terminal.v1` with `status: "completed"`. Fails
+  closed — a run that ends with no terminal event shows approved error copy, never the partial.
+- **Progress copy** per §8.7 verbatim: `Thinking…` → `Checking your Supply information…` (narration
+  event **or** ~1500ms) → `Preparing your answer…` (first buffered chunk). Narration text is never
+  echoed, only used as proof work started. Rendered via a new blox `progress` prop with
+  `aria-live="polite"` and a `prefers-reduced-motion` guard.
+- **Markdown option (b) implemented**: blox got a `renderMarkdown?: (text) => ReactNode` slot;
+  `toga25-supply/src/components/TalosMarkdown/` fills it with `react-markdown@10.1.0` +
+  `remark-gfm@4.0.1`. Covers the full §10 list (headings, ordered/nested lists, inline+fenced code,
+  blockquotes, GFM tables). No raw HTML, links allowlisted to `http:`/`https:`/`mailto:`,
+  external → new tab, same-origin → react-router. 10 tests.
+- **Clickable links in replies.** blox `RichText` now parses `[label](url)`; same-origin links go
+  through a new `adapter.onNavigate` (supply wires it to react-router `navigate()`), cross-origin
+  open in a new tab with `rel="noopener noreferrer"`, unsafe schemes render as inert text.
+- **Record modal now responds to the docked panel.** Read the real design source rather than
+  guessing: `demo/demo-modal.jsx` binds the overlay's `right` to the dock width with
+  `260ms cubic-bezier(0.2,0.8,0.2,1)`, confirmed by `slide-up-modal-geometry.md`.
+  `AppLayout` publishes `--talos-dock-width` on `document.documentElement`; blox
+  `TableRecordModal` reads it (`.backdrop`, `.modal-bottom`, `.modal-center`, `.modal-right`).
+  Defaults to `0px` so all other blox consumers are unaffected.
+- **Reading the Claude Design project via the `DesignSync` MCP worked** without a design-login
+  prompt: `get_project` / `list_files` / `get_file` on project
+  `05d4a4a0-9062-4479-9e10-225021e45cc9` ("TOGa Supply", owner David). The self-contained HTML is
+  too large for `get_file` (256KiB cap) — read the **JSX sources** (`demo/demo-shell.jsx`,
+  `demo/demo-modal.jsx`) and the `*.md` geometry notes instead.
+- **Two real bugs caught by writing tests**, both described under *Decisions*/*Not retry* below.
+
+## What did NOT work — DO NOT RETRY THESE
+
+- **`npx tsc --noEmit` at the `toga25-supply` repo root is a SILENT NO-OP.** The root
+  `tsconfig.json` is references-only (`files: []`), so it compiles nothing and **always exits 0**.
+  It reported "clean" twice on a codebase with real type errors. **Always use
+  `npx tsc --noEmit -p tsconfig.app.json`** (or `tsc -b`). The repo architecture doc used to
+  recommend the broken command; that has been corrected in the KB this session, and the rule is
+  now in `2.0/standards/frontend.md` §2.
+- **Mapping LangGraph user turns to `TalosMessageModel.message` renders an EMPTY BUBBLE.**
+  `TalosMessage` renders `message.text` for a **user** turn and `message.message`/`paras` for a
+  **talos** turn. The mapper must emit `{role:"user", text}` vs `{role:"talos", message}`.
+- **Mapping empty AI turns to `{thinking: true}` leaves a permanent row of stuck loading dots.**
+  An empty AI turn is a **tool-call turn** — LangGraph puts the call in `tool_calls` and leaves
+  `content` blank — and a thread accumulates several. Drop every empty turn; the live thinking
+  indicator comes from `isStreaming`, rendered as ONE synthetic trailing bubble by the panel.
+- **`ln -sfn <target> node_modules/@agilant/toga-blox` does NOT replace a real directory** — it
+  creates the link *inside* it. Must `rm -rf` the directory first.
+- **"one fewer peer" was the WRONG reason to pick `@langchain/langgraph-sdk` over
+  `@langchain/react`.** The SDK (`1.10.0`) itself declares `@langchain/core: ^1.1.48` as a
+  **required, non-optional** peer. Symptom when missing: Vite/esbuild dep-optimize hard-fails with
+  `Could not resolve "@langchain/core/messages"` and the dev server exits. The decision still
+  stands (proven in-house, smaller surface) — only that rationale is wrong. Corrected in the KB.
+- **`@assistant-ui/react-markdown` cannot be used "markdown only, without the runtime."** It
+  declares a **required peer on `@assistant-ui/react` ^0.15.0`**, which pulls `zustand ^5.0.15`
+  (supply pins `5.0.14`), `radix-ui`, `assistant-cloud`, `assistant-stream`. Its actual engine is
+  `react-markdown@^10` — so if you only want markdown, use `react-markdown` + `remark-gfm`
+  directly (what this session did).
+- **`stream.stop()` does not stop the run server-side** — it only drops the client transport; the
+  run keeps executing and billing. The real stop is
+  `POST /threads/{id}/runs/{run_id}/cancel?wait=0&action=cancel`. **Still wired to `stream.stop()`
+  — this is an open defect** (see Blockers).
+- **Putting the thread id in the URL query string wiped the conversation.** Any navigation that
+  rewrote the search string — a record link in a reply (`?sales-orders=<uuid>`), a side-nav click —
+  dropped `talosThread`, remounted `useStream` with no thread, and cleared the visible chat. Do not
+  reintroduce a URL-param thread. It is now `sessionStorage`, keyed by tenant + user.
+- **Guessing at Aegra host names is a waste of time.** `api.gamma.togaiq.com`,
+  `api.prod.togaiq.com`, `api.dev.togaiq.com`, `api.sandbox.togaiq.com`, `togaiq.com` all fail to
+  connect (`000`). Only `api.beta.togaiq.com` and `api.togaiq.com` exist.
+- **`api.beta.togaiq.com` was returning 502 for most of this session** (`/health`, `/info`,
+  `/assistants`) after being healthy ~10 minutes earlier. Not a code problem. Production was used
+  instead. Also note: **Aegra sends CORS headers on the OPTIONS preflight but NOT on actual
+  responses** — reported to akhokhani, still unfixed as far as this session knows.
+- **`knowledge.js kickoff-preflight` returned `features: []`** for toga25-supply, toga-blox and
+  talos on `--q="talos streaming chat"` even though three highly relevant feature docs exist. That
+  is the **second** session in a row. Search `knowledge/2.0/apps/<repo>/features/` directly.
+
+## Not tried yet (candidates for next session)
+
+**This is the remaining build, and it is the bulk of the feature. All endpoints are already
+implemented in `src/api/talos.ts`; what is missing is the parser, the hook, and the blox views.**
+
+- **`fromTalosTranscript()` — the centralized transcript parser.** `GET /threads/{id}/transcript`
+  returns `{messages:[{id, logical_message_id, type, content, run_id, created_at, active}], next_cursor}`,
+  oldest-first. `content` is **polymorphic**: normalize a string directly; for an array of
+  LangChain content blocks concatenate only ordered `type:"text"` blocks with a string `text`;
+  ignore reasoning, tool-use/tool-result, binary and unknown block types; **do not create an empty
+  bubble** if no visible text remains. Render only **active** `human`/`ai`. Deduplicate by stable
+  `id`; for revisions use `logical_message_id` + `active`, **never content matching**. The handoff
+  requires this parser be centralized and regression-tested.
+- **Terminal-completion reconciliation (§8.8).** On `completed`: refetch the newest transcript page,
+  select the active AI message for this `run_id` (prefer `final_message_id`), replace the optimistic
+  human message with its durable record, publish in ONE update, then refetch the thread for its
+  generated title and refresh the list. **The transcript is authoritative — if buffer and transcript
+  disagree, display the transcript.** Currently the buffer is displayed on completion.
+- **`useTalosThreads` hook** — React Query list/rename/delete/select over the client functions.
+  Cache scope MUST include the authenticated subject + org identity, and must be cleared on
+  logout/account switch (§8.2). Page 20 at a time, sort by `updated_at` desc, dedupe by `thread_id`.
+- **blox view props for the history drawer**: `threads`, `activeThreadId`, `onSelectThread`,
+  `onNewChat`, `onRenameThread`, `onDeleteThread`. blox already has a history-drawer UI built for
+  its *internal* conversation list (`feat.history`, `showHistory`, `styles.history`) — make it
+  render host-supplied threads when controlled. Title = `metadata.thread_name` falling back to
+  `New conversation`.
+- **Re-enable `history` / `newChat` in controlled mode** once the host supplies threads. They are
+  currently **force-disabled** in `TalosPanel` (`isControlled ? {history:false,newChat:false} : {}`)
+  — that is why the design's chat-history and `+` buttons are missing from supply. The `+` is the
+  cheap half: the context already exposes `newThread()`; it needs an `onNewChat` prop.
+- **Message actions**: copy, plus thumbs up/down. Show actions **only for completed AI messages**.
+- **Thumbs-down dialog (§9)** — must match standalone Talos: title `What went wrong?`; multi-select
+  reasons where selecting one does not clear another; always show a comments textarea; placeholder
+  `Additional comments (optional)` until `other` is selected, then `Please describe the issue…` and
+  **required non-empty**; Submit disabled until a reason is selected (and text present for `other`);
+  Cancel submits nothing and restores focus to the thumbs-down button.
+- **Rename ETag/`If-Match` flow (§8.10).** `renameTalosThread` already sends `If-Match` when given
+  `metadataVersion`, but nothing fetches/threads the ETag yet.
+- **Reconnect/rejoin (§8.13)** — `GET /threads/{id}/runs/{run_id}/stream` on transport loss,
+  `talos.run.transport.v1` → delayed `Reconnecting…`, `talos.run.replay_gap.v1` → refetch run +
+  transcript. Also `GET /threads/{id}/runs?limit=1` to recover the latest run after reload.
+- **Wire Stop to `cancelTalosRun`** instead of `stream.stop()` — needs the `run_id`, which comes
+  from the `metadata` SSE event (§8.5, "capture run identity"). Not captured yet.
+- **Fix the pre-existing `AdvancedSelect` type error** at
+  `src/pages/TransferOrders/view/CreateTransferOrderModal/CreateTransferOrderModal.tsx:603` —
+  passes `name` to single-mode `AdvancedSelect`, which does not accept it. Predates this session
+  and is unrelated to Talos; left alone deliberately.
+- **Confirm which api2 issuer each Aegra environment trusts.** Never resolved: the demo token came
+  from `api.beta.togahub.com`, supply's envs use `api.togahub.com` / `api.gamma.togahub.com` /
+  `api.dev.sandbox.togahub.com`. Production works today, so this only matters for beta testing.
+- **Ask akhokhani to point MCP at beta** if beta testing is wanted — MCP currently targets
+  production `api.togahub.com`, so a beta/dev token cannot answer data questions like "what is the
+  last sales order?"
+- **Confirm the per-client CORS/`Domains` coverage** for the other supply hostnames (compass, quad,
+  prudential, growrk, …). Only nychh has been exercised.
+- **No test covers `TalosStreamProvider`** — `useStream` would need mocking. The mapper, the panel
+  and the markdown renderer are covered; the provider wiring is hand-verified only.
+
+## Current file state
+
+**toga25-supply** (branch `features-talos-transferorders`)
+
+| File | Status | Notes |
+|------|--------|-------|
+| `src/api/talos.ts` | CREATED | Sole `VITE_TALOS_API` chokepoint. `isTalosConfigured`, `getTalosApiUrl`, `fetchTalosAssistants`, `pickTalosAssistant`, plus **threads/transcript/feedback/cancel**: `fetchTalosThreads`, `threadTitle`, `renameTalosThread` (sends `If-Match`), `deleteTalosThread`, `fetchTalosTranscript`, `fetchTalosFeedback` (indexed by `message_id`), `putTalosFeedback`, `deleteTalosFeedback`, `cancelTalosRun`. All route through one `talosRequest` helper that logs status before throwing. **Written and typechecking; only the assistants half is exercised at runtime.** |
+| `src/utils/talosMessages.ts` | CREATED | `extractMessageText` (string-or-blocks union), `toTalosMessage`, `toTalosMessages`, `withoutTrailingAssistant`. Drops all empty turns and every non-`human`/`ai` type. Tool calls + interrupts deliberately dropped. |
+| `src/utils/talosMessages.test.ts` | CREATED | 13 tests. |
+| `src/hooks/useTalosSession.ts` | CREATED | Resolves token + assistantId → `connection: "disabled"\|"connecting"\|"ready"\|"error"`. Gates on `isAuthenticated` (the `user` key) **not** on an accessToken's presence (blox `fetchPublicToken` leaves a PUBLIC token in storage). Assistants query keyed by **user uuid, never the token** — supply persists the query cache to storage. |
+| `src/providers/TalosStreamProvider.tsx` | CREATED | Single `useStream`; outer gate + inner `TalosStreamSession` (hooks cannot be conditional). Thread in `sessionStorage` keyed by tenant+user, re-seeded when the key changes. Terminal-truth reveal gate, progress stage machine, `TERMINAL_TEXT` copy map. Exposes `messages`/`isStreaming`/`connection`/`progress`/`submit`/`stop`/`newThread`. |
+| `src/components/TalosMarkdown/{TalosMarkdown.tsx,TalosMarkdown.module.css,index.ts}` | CREATED | `react-markdown` + `remark-gfm`; no raw HTML, link scheme allowlist, external → new tab, same-origin → react-router, tables/code scroll in their own box, Supply tokens. |
+| `src/components/TalosMarkdown/TalosMarkdown.test.tsx` | CREATED | 10 tests incl. raw-HTML and `javascript:` rejection. |
+| `src/layout/AppLayout/AppLayout.tsx` | MODIFIED | Split into `AppLayoutInner` wrapped by `TalosStreamProvider`. Panel driven by controlled props + `progress` + `renderMarkdown`; adapter carries navigation only (`onOpenRecord`, `onAction`, `onNavigate`, `onDockWidthChange`). Publishes `--talos-dock-width` on `document.documentElement`. |
+| `.env.development` and 6 other non-prod env files | MODIFIED | `VITE_TALOS_API` added. `.env.development` now points at `https://api.togaiq.com` (production Aegra); the others still at `https://api.beta.togaiq.com`. `.env` (production) leaves it **commented out**. |
+| `package.json` / `package-lock.json` | MODIFIED | Added `@langchain/langgraph-sdk@1.10.0`, `@langchain/core@1.2.9`, `react-markdown@10.1.0`, `remark-gfm@4.0.1`. |
+| `src/pages/TransferOrders/.../CreateTransferOrderModal.tsx` | UNTOUCHED | Pre-existing `AdvancedSelect` `name` type error at line 603. Not mine, not fixed. |
+
+**toga-blox** (branch `features-talos-transferorders`, `origin/TRUE-80692-BDR` merged in this session)
+
+| File | Status | Notes |
+|------|--------|-------|
+| `src/components/Talos/types.ts` | MODIFIED | Added `TalosConnection`; on `TalosPanelProps`: `messages`, `isStreaming`, `progress`, `onSubmit`, `onStop`, `connection`, `renderMarkdown`. On `TalosAdapter`: `onNavigate`. On `TalosMessageModel`: `thinkingLabel`. On `TalosMessageHandlers`: `onNavigate`, `renderMarkdown`. |
+| `src/components/Talos/TalosPanel.tsx` | MODIFIED | Controlled mode keyed off `messages !== undefined`; `history`/`newChat` **force-disabled** when controlled; composer disabled unless `connection === "ready"` with staged placeholder copy; send↔stop swap; ONE synthetic trailing thinking bubble driven by `isStreaming`. Docblock added. |
+| `src/components/Talos/TalosMessage.tsx` | MODIFIED | Uses `renderMarkdown` when supplied, else built-in `TalosMarkdown`; renders `thinkingLabel`; threads `onNavigate`. |
+| `src/components/Talos/helpers.tsx` | MODIFIED | `RichText` parses `[label](url)` with a scheme allowlist + same-origin `onNavigate`; `toMarkdownBlocks` gained GFM **table** parsing; `TalosMarkdown` renders tables and takes `onNavigate`. |
+| `src/components/Talos/Talos.module.css` | MODIFIED | Added `.mdTable`, `.mdLink`, `.thinkingRow`, `.thinkingLabel`, `.mdHost` (+ reduced-motion guard). |
+| `src/components/Talos/TalosPanel.test.tsx` | CREATED | 12 tests — first tests ever for Talos. |
+| `src/components/Talos/helpers.test.tsx` | CREATED | 10 tests — table parsing + link safety. |
+| `src/components/Talos/README.md` | CREATED | 225 lines: the two modes, prop/adapter tables, `features` defaults, message model with the `text`-vs-`message` trap, markdown rules, theming + density ceiling, dock-width rule, file map, gotchas. |
+| `src/components/TableRecordModal/tableRecordModal.module.css` | MODIFIED | `.backdrop`/`.modal-right` stop at `var(--talos-dock-width, 0px)`; `.modal-bottom`/`.modal-center` re-centre via `left: calc(50% - var(--talos-dock-width,0px)/2)` and cap `max-width` to the remaining space; 260ms easing. Defaults to 0px ⇒ non-breaking. |
+| `package-lock.json` | MODIFIED | pre-existing dirty before this session. |
+
+**Test status:** blox Talos 22 pass; supply 57 pass (10 files). blox's ~40 pre-existing unrelated
+failures elsewhere in the suite still stand.
+
+## Decisions made
+
+- **Merged `origin/TRUE-80692-BDR` into `features-talos-transferorders` before implementing.**
+  Rationale: Talos exists on NO mainline blox branch; `origin/TRUE-80692` has the **narrow**
+  contract while tcox's widening landed on `TRUE-80692-BDR` — two divergent contracts. BDR
+  validated the widened one live. *Rejected:* building on `TRUE-80692` and merging tcox later.
+- **Kept blox `TalosPanel` as the conversation surface; did NOT adopt `@assistant-ui/react`.**
+  The handoff §1 recommends assistant-ui's `ExternalStoreRuntime`. Rationale for deviating: our
+  provider already implements the principle that matters (host owns message state, view is dumb);
+  the blox panel is built, themed, tested and has a **second consumer in BDR**; and David's Claude
+  Design mockup shows the blox panel, not assistant-ui. **This is a live, unratified deviation from
+  the handoff — flag it to the doc's author.**
+- **Markdown option (b): `renderMarkdown` slot in blox, `react-markdown` in the app.**
+  Rationale: blox peers do not hoist (frontend.md §13b), so a markdown dependency in blox lands on
+  all five consumer apps; the slot mirrors blox's existing `footer`/`titleIcon` pattern and is
+  reusable by desk/commerce. *Rejected:* (a) hand-extending `TalosMarkdown` with headings/ordered
+  lists/fenced code/blockquotes — exactly the edge-case work a parser exists for.
+- **Thread id in `sessionStorage`, NOT the URL.** Rationale: a thread is scoped to one user on
+  Aegra so the URL was never meaningfully shareable; it only bought reload-persistence, which
+  storage gives without the coupling that wiped the chat on every query-string rewrite. Keyed by
+  tenant+user per §18. *Rejected:* URL search param (the original design decision — reverse it
+  knowingly); `localStorage` (survives too long for "which chat is open").
+- **`--talos-dock-width` CSS custom property, not a `window` event bus.** Rationale: the design
+  prototype uses `window.__talosDockW` + `window.__talosDockSubs`, but blox deliberately removed a
+  `window.dispatchEvent` side channel during its own review; a CSS var crosses the portal boundary
+  with no global mutable state and defaults cleanly to `0px`. *Rejected:* copying the prototype's
+  subscriber set.
+- **Reveal gate keyed on the terminal event, failing closed.** Rationale: §8.6 requires
+  `messages`/`messages/partial` never be revealed and §8.8 makes the terminal authoritative. A run
+  that ends with no terminal shows approved copy rather than the buffer. *Rejected:* treating
+  `isLoading === false` as success.
+- **Progress copy comes from the host, never inferred by blox.** blox renders `thinkingLabel`; it
+  never invents a step name, percentage or ETA (§8.7 forbids those).
+- **`max-width` cap rather than the design's `width` swap for the docked modal.** The design does
+  `width: dockW ? "calc(100% - 72px)" : "90%"`; `width` here is a % of the viewport and cannot see
+  the dock, so capping `max-width` to the remaining space achieves the same visible result with a
+  `--tableRecordModal-gutter` (24px) knob.
+- **Assistant selection prefers `metadata.customer_facing`, warns when ambiguous, never throws.**
+  Matches the frontend.md §20 resolver doctrine (unknown ⇒ disabled + `console.warn`, never a
+  silent no-op or a throw).
+
+## Blockers
+
+- **Stop does not actually stop the run.** `onStop` → `stream.stop()` drops only the client
+  transport; the run continues executing and billing. Fixing it needs the `run_id` captured from
+  the `metadata` SSE event (§8.5), then `cancelTalosRun`. `cancelTalosRun` is written; the run_id
+  capture is not. **Treat as a real defect, not a nicety.**
+- **The buffer, not the transcript, is displayed on completion.** §8.8 makes the transcript
+  authoritative. Until the reconciliation is built, a divergence between buffer and durable record
+  shows the wrong text, and message ids needed for feedback are unavailable.
+- **Chat history and `+ new chat` are missing from the supply UI** because `TalosPanel`
+  force-disables them in controlled mode. This is the visible gap the developer reported against
+  the design.
+- **Aegra `api.beta.togaiq.com` was 502 throughout most of the session** and, separately, **Aegra
+  returns CORS headers on the OPTIONS preflight only, not on actual responses.** Both reported to
+  akhokhani; neither confirmed fixed. Production (`api.togaiq.com`) is healthy and is what works.
+- **Deviating from the handoff on the conversation surface (blox vs assistant-ui) is unratified.**
+  Every remaining item (history, message actions, feedback) is view work, which is exactly where
+  the two paths diverge. Get agreement before building those, or expect rework.
+- **`npm install` in `toga25-supply` destroys the blox symlink** every time, replacing it with
+  registry `1.1.1-production.139` which has **no Talos** — symptom is
+  `does not provide an export named 'TalosLauncher'`. Always follow an install with
+  `rm -rf node_modules/@agilant/toga-blox && ln -s ../../../toga-blox-npm node_modules/@agilant/toga-blox`
+  then `rm -rf node_modules/.vite`.
+- **Nothing is committed.** Both repos have substantial uncommitted work on
+  `features-talos-transferorders`. blox `dist/` is gitignored, so other consumers see none of this
+  until blox is published.
+
+## Exact next step
+
+> Decide the blox-vs-`@assistant-ui/react` question with the handoff doc's author **before**
+> building any more view code — every remaining item is view work.
+>
+> Then, assuming blox: implement `fromTalosTranscript()` in
+> `toga25-supply/src/utils/talosMessages.ts` with tests, using the shape in
+> `~/Desktop/toga-supply-streaming-chat-handoff.md` §8.11 (polymorphic `content`, active
+> `human`/`ai` only, dedupe by `id`, `logical_message_id` + `active` for revisions, no empty
+> bubbles). It is the prerequisite for terminal reconciliation, for message ids that feedback
+> needs, and for opening an existing thread from the history drawer.
+
+---
+_Saved by /session-save on 2026-09-02_

package/package.json

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

package/rules/common/communication.md

@@ -21,6 +21,12 @@ thinking, your plans, and your final answers. This is a hard team rule, not a st
 5. **Use lists.** More than two parts? Use a numbered or bulleted list, not a paragraph.
 6. **Stay technical, stay exact.** Keep the real detail — file names, error text, exact steps.
    Short does not mean vague. Be brief AND precise.
+7. **Mirror the person.** Read how each teammate writes to you — the words they use, the
+   terms they pick for things, and how long their sentences run — and answer back in that
+   same style. Reuse their own words. If they write short, you write short. This makes your
+   answers feel familiar and easy to follow.
+   - Never fake misspellings or bad grammar to "match" someone. Be natural and correct —
+     just familiar. Mirroring means their vocabulary and length, not their typos.
 
 ## When a human must do something — always use a numbered list
 
@@ -55,3 +61,14 @@ What you need to do:
 
 Wordy, jargon-heavy output is hard and slow to read — worse for non-native English readers.
 The team moves faster when you are brief and plain. Clear beats clever.
+
+## How this is enforced
+
+This rule kept drifting: it lived only here, so on long or technical sessions the model slid
+back to dense wording and teammates missed critical details. To stop that, a hook backs it up.
+
+- `scripts/hooks/plain-talk.js` runs on **every** developer turn (`UserPromptSubmit`). It
+  injects a short reminder of these rules — plus the "mirror the person" instruction — into
+  context right before each reply. So the model is reminded every turn, not just once.
+- The hook is wired in `.claude/settings.json` and ships to every repo on `npx toga-ai`.
+- It never blocks anything; it only nudges. To silence it, set `TOGA_PLAIN_TALK_DISABLED=1`.

package/scripts/hooks/plain-talk.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * plain-talk.js — EVERY-TURN enforcement of the team communication rule.
+ *
+ * Why this exists: rules/common/communication.md tells the model to write short,
+ * plain, jargon-free answers and to mirror how each teammate talks. But a rule that
+ * only lives in a file is passive — over a long or technical session the model drifts
+ * back to dense, jargon-heavy wording. Teammates (many reading English as a second
+ * language) then miss critical details and sign off on bad decisions. Prose alone did
+ * not hold; this is the mechanical backstop.
+ *
+ * How it works: registered on UserPromptSubmit. On every developer turn it prints a
+ * short <system-reminder> to stdout, which Claude Code injects into the model's context
+ * immediately before the reply is generated. So the plain-talk + mirror instruction is
+ * the last thing in context every single turn — the model cannot quietly forget it.
+ *
+ * It reads nothing and writes nothing. It never blocks (always exit 0) — a communication
+ * nudge must never stop a tool call. Fail-open on any error: a crashing nudge must never
+ * brick a session.
+ *
+ * Escape hatch: set TOGA_PLAIN_TALK_DISABLED=1 to silence the reminder.
+ */
+
+const fs = require('fs');
+
+/* Read the CC hook payload from stdin (fall back to env), so we only fire on the
+ * UserPromptSubmit event and stay quiet on anything else that reuses this script. */
+function readPayload() {
+  let raw = '';
+  try { raw = fs.readFileSync(0, 'utf8'); } catch (e) { /* no stdin */ }
+  let data = {};
+  if (raw && raw.trim()) {
+    try { data = JSON.parse(raw); } catch (e) { data = {}; }
+  }
+  if (!data.prompt && process.env.CLAUDE_USER_PROMPT) data.prompt = process.env.CLAUDE_USER_PROMPT;
+  return data;
+}
+
+function reminder() {
+  return [
+    '<system-reminder>',
+    'TEAM COMMUNICATION RULE (rules/common/communication.md) — applies to THIS reply:',
+    'Write short and plain. Many teammates read English as a second language; dense,',
+    'jargon-heavy answers make them miss critical details and accept bad decisions.',
+    '',
+    '  1. Answer first. Main point on line 1, reasons after (only if needed).',
+    '  2. Cut words. Say it, then stop. One line beats three.',
+    '  3. Common words only. No rare jargon (idempotent, cardinality, orthogonal, canonical);',
+    '     say what it means in plain words instead. Stay exact — keep file names, errors, steps.',
+    '  4. Any manual action (deploy, SQL, config, restart) goes in a numbered list under a',
+    '     "What you need to do:" heading. One action per step, in order.',
+    '',
+    'MIRROR THIS PERSON: read how the developer writes to you in this session — the words',
+    'and phrases they use, and how long their sentences run — and answer back in that same',
+    'register. Reuse their own terms for things. Match their length: if they write short,',
+    'you write short. Never fake misspellings or bad grammar; be natural, just familiar.',
+    '',
+    'Before you send: could you cut half the words and keep the meaning? Is any word too',
+    'rare for a non-native reader? Is the main point on the first line?',
+    '</system-reminder>',
+  ].join('\n');
+}
+
+function main() {
+  if (process.env.TOGA_PLAIN_TALK_DISABLED === '1') process.exit(0);
+
+  const data = readPayload();
+
+  // Only fire on a real user turn. UserPromptSubmit carries a prompt and no tool_name.
+  const isPromptEvent =
+    data.hook_event_name === 'UserPromptSubmit' ||
+    (typeof data.prompt === 'string' && !data.tool_name);
+
+  if (isPromptEvent) {
+    // stdout from a UserPromptSubmit hook is injected into the model's context.
+    console.log(reminder());
+  }
+  process.exit(0);
+}
+
+try { main(); } catch (e) { process.exit(0); } // fail-open: never brick a session