toga-ai 1.0.679 → 1.0.680

package/knowledge/2.0/apps/talos/INDEX.md

@@ -4,6 +4,7 @@
 |-----|---------|-------|
 | [TOGa IQ (talos) Architecture](architecture.md) | **TOGa IQ** is TOGA Technology's AI agent platform. | talos/libs/aegra-api/src/aegra_api/main.py, talos/libs/aegra-api/src/aegra_api/settings.py, talos/libs/aegra-api/src/aegra_api/config.py, talos/libs/aegra-api/src/aegra_api/core/tenant_router.py, talos/libs/aegra-api/src/aegra_api/core/control_plane_db.py, talos/libs/aegra-api/src/aegra_api/core/auth_middleware.py, talos/libs/aegra-api/src/aegra_api/services/run_executor.py, talos/libs/aegra-api/src/aegra_api/services/langgraph_service.py, talos/libs/aegra-api/src/aegra_api/services/graph_factory.py, talos/libs/aegra-api/src/aegra_api/services/streaming_service.py, talos/agents/talos_agent/graph.py, talos/docker-compose.yml, talos/deployments/docker/Dockerfile |
 | [aegra-api — Agent Protocol HTTP + Execution Pipeline](features/aegra-api.md) | `aegra-api` is the **FastAPI Agent Protocol server** at the heart of TOGa IQ. | talos/libs/aegra-api/src/aegra_api/main.py, talos/libs/aegra-api/src/aegra_api/settings.py, talos/libs/aegra-api/src/aegra_api/config.py, talos/libs/aegra-api/src/aegra_api/api/assistants.py, talos/libs/aegra-api/src/aegra_api/api/threads.py, talos/libs/aegra-api/src/aegra_api/api/runs.py, talos/libs/aegra-api/src/aegra_api/api/store.py, talos/libs/aegra-api/src/aegra_api/api/mcp.py, talos/libs/aegra-api/src/aegra_api/api/knowledge_bases.py, talos/libs/aegra-api/src/aegra_api/core/auth_middleware.py, talos/libs/aegra-api/src/aegra_api/core/auth_deps.py, talos/libs/aegra-api/src/aegra_api/core/tenant_router.py, talos/libs/aegra-api/src/aegra_api/core/control_plane_db.py, talos/libs/aegra-api/src/aegra_api/core/redis_manager.py, talos/libs/aegra-api/src/aegra_api/core/encryption.py, talos/libs/aegra-api/src/aegra_api/middleware/content_type_fix.py, talos/libs/aegra-api/src/aegra_api/middleware/rate_limiter.py, talos/libs/aegra-api/src/aegra_api/middleware/logger_middleware.py, talos/libs/aegra-api/src/aegra_api/services/broker.py, talos/libs/aegra-api/src/aegra_api/services/redis_broker.py, talos/libs/aegra-api/src/aegra_api/services/executor.py, talos/libs/aegra-api/src/aegra_api/services/local_executor.py, talos/libs/aegra-api/src/aegra_api/services/worker_executor.py, talos/libs/aegra-api/src/aegra_api/services/run_executor.py, talos/libs/aegra-api/src/aegra_api/services/langgraph_service.py, talos/libs/aegra-api/src/aegra_api/services/graph_factory.py, talos/libs/aegra-api/src/aegra_api/services/graph_streaming.py, talos/libs/aegra-api/src/aegra_api/services/streaming_service.py, talos/libs/aegra-api/src/aegra_api/services/event_store.py, talos/libs/aegra-api/alembic/env.py |
+| [TOGa IQ Chat Frontend (Next.js) — streaming stack & Aegra wiring](features/chat-frontend.md) | The repo **`agilantsolutions/talos`** is the TOGa IQ **chat front-end** — the browser client that talks to the Aegra Agent-Protocol backend. | talos/package.json, talos/next.config.mjs, talos/src/providers/Stream.tsx, talos/src/modules/chat/viewmodel/use-chat-viewmodel.tsx, talos/src/lib/api-url.ts, talos/src/lib/env.ts, talos/src/lib/api/client.ts, talos/src/app/api/[..._path]/route.ts, talos/.env.development, talos/.env.beta, talos/.env.gamma, talos/.env.production |
 | [Deployment — Docker, Compose, Entrypoint, External PG/Redis](features/deployment.md) | TOGa IQ ships as a **single container** (`aegra` service) wrapping the `aegra-api` FastAPI server. | talos/docker-compose.yml, talos/deployments/docker/Dockerfile, talos/deployments/docker/entrypoint.sh |
 | [MCP Servers — clickup-mcp and toga-db-mcp](features/mcp-servers.md) | Two internal **FastMCP** servers exposed over **HTTP** with API-key auth and PM2 process management: - **`clickup-mcp`** — ClickUp workspace surface (spaces / f | talos/mcp-servers/clickup-mcp/src, talos/mcp-servers/clickup-mcp/ecosystem.config.js, talos/mcp-servers/clickup-mcp/ecosystem.dev.config.js, talos/mcp-servers/clickup-mcp/pyproject.toml, talos/mcp-servers/clickup-mcp/.env.example, talos/mcp-servers/toga-db-mcp/src, talos/mcp-servers/toga-db-mcp/clusters.yaml, talos/mcp-servers/toga-db-mcp/ecosystem.config.js, talos/mcp-servers/toga-db-mcp/pyproject.toml, talos/mcp-servers/toga-db-mcp/.env.example |
 | [Observability — Langfuse, OTEL, Prometheus, OneUptime](features/observability.md) | TOGa IQ uses **two complementary tracing planes** plus optional Prometheus metrics and external uptime monitoring: - **Langfuse (native v3 SDK)** — LLM-shaped t | talos/libs/aegra-api/src/aegra_api/observability/__init__.py, talos/libs/aegra-api/src/aegra_api/observability/setup.py, talos/libs/aegra-api/src/aegra_api/observability/base.py, talos/libs/aegra-api/src/aegra_api/observability/langfuse_provider.py, talos/libs/aegra-api/src/aegra_api/observability/langfuse_client.py, talos/libs/aegra-api/src/aegra_api/observability/otel.py, talos/libs/aegra-api/src/aegra_api/observability/metrics.py, talos/libs/aegra-api/src/aegra_api/observability/span_enrichment.py, talos/libs/aegra-api/src/aegra_api/observability/targets |

package/knowledge/2.0/apps/talos/architecture.md

@@ -45,6 +45,22 @@ dependency** — it is a self-contained Python product that consumes TOGa data
 read-only via the `toga-db-mcp` server. It lives under `2.0/apps/talos/` because
 its consumers are 2.0-era TOGa apps (TOGa Hub, TOGa View) and TogaHub auth.
 
+> **Repo scope — this doc covers the BACKEND ONLY, which is not in the `talos` repo.**
+> Verified 2026-08-28 (`git ls-tree` across all 16 `origin/*` refs): no branch of
+> `agilantsolutions/talos` contains `libs/aegra-api`, `agents/`, `mcp-servers/`, or
+> `docker-compose.yml` — every branch is the chat **front-end**, documented in
+> [features/chat-frontend.md](features/chat-frontend.md). The Aegra backend described below lives
+> in a separate, currently unregistered repo, so the `files:` paths above do not resolve.
+
+**Critical rules:** Clients speak the **Agent Protocol** — never invent a custom wire shape; SDK and
+LangGraph-Studio compatibility depend on it. **Tenant provisioning is explicit with no auto-create**,
+so an unregistered `org_id` gets a clean **403 on every call even with a valid token** — provision
+the tenant before debugging the caller. `AUTH_TYPE` ∈ {`togahub`, `entra`, `noop`} and **`noop` must
+never ship to prod**. `toga-db-mcp` is the **only** sanctioned path into TOGa MySQL (read-only,
+`LIMIT` 1–1000, enforced inside the MCP rather than the agent), and the Fernet `MCP_ENCRYPTION_KEY`
+is a single **global** key shared by every tenant — not per-tenant — so treat rotating it as a
+cross-tenant event.
+
 ## Top-level layout
 
 ```
@@ -194,4 +210,11 @@ Always use Langfuse's cache-corrected cost (it undercounts cache badly).
   inside the MCP, not the agent.
 
 ## Change history
+- 2026-08-28 — Scoped this doc to the Aegra backend and recorded that it is **not** the `talos` repo
+  (verified across all 16 origin refs); the `talos` repo is the chat front-end, now documented in
+  `features/chat-frontend.md`. Dropped `"language": "python"` from the `talos` `registry.json` entry
+  so the front-end repo stops loading `2.0/standards/python.md`. **Deferred half — once the Aegra
+  backend repo's name is known, register it and set `"language": "python"` on THAT entry**; until
+  then no repo loads the Python standard. Added a backend-scoped `Critical rules:` line to the
+  Summary (the pre-existing one under Talos Pricing Platform covers pricing only). (apeterson)
 - 2026-06-16 — Initial architecture doc for talos / TOGa IQ under 2.0/apps. (akhokhani)

package/knowledge/2.0/apps/talos/features/chat-frontend.md

@@ -0,0 +1,172 @@
+---
+title: TOGa IQ Chat Frontend (Next.js) — streaming stack & Aegra wiring
+framework: "2.0"
+repo: talos
+project: TOGa IQ
+client: shared
+type: feature
+status: active
+updated: 2026-08-28
+owners: [apeterson]
+files:
+  - talos/package.json
+  - talos/next.config.mjs
+  - talos/src/providers/Stream.tsx
+  - talos/src/modules/chat/viewmodel/use-chat-viewmodel.tsx
+  - talos/src/lib/api-url.ts
+  - talos/src/lib/env.ts
+  - talos/src/lib/api/client.ts
+  - talos/src/app/api/[..._path]/route.ts
+  - talos/.env.development
+  - talos/.env.beta
+  - talos/.env.gamma
+  - talos/.env.production
+related:
+  - ../architecture.md
+  - aegra-api.md
+  - ../../toga-blox/features/talos-assistant.md
+  - ../../toga25-supply/features/talos-integration.md
+---
+
+## Summary
+
+The repo **`agilantsolutions/talos`** is the TOGa IQ **chat front-end** — the browser client that
+talks to the Aegra Agent-Protocol backend. It is the reference implementation of **token-streaming
+chat** in-house, so it is what any other app (toga25-supply, toga2-desk, toga2-commerce) should copy
+when wiring a real Talos backend.
+
+This doc exists because the front-end half of TOGa IQ was previously undocumented: anyone told
+*"look at how talos does streaming"* landed on
+[`../architecture.md`](../architecture.md), which describes only the Python/FastAPI backend.
+
+## Repo identity — read this before trusting `architecture.md`
+
+**Verified 2026-08-28 (`git ls-tree` across all 16 `origin/*` refs): no branch of
+`agilantsolutions/talos` contains `libs/aegra-api`, `agents/`, `mcp-servers/`, or
+`docker-compose.yml`.** Every branch is a front-end app. The Python/Aegra backend that
+`2.0/apps/talos/architecture.md` documents (and lists under `files: talos/libs/aegra-api/…`) lives
+in a **different repo** that is not yet in `registry.json`.
+
+Two live consequences until that is reconciled:
+
+- `registry.json` marks `talos` as `"language": "python"`, so `/kickoff` loads
+  `2.0/standards/python.md` for a **TypeScript/Next.js** repo — and does *not* load
+  `2.0/standards/frontend.md`. Pull the front-end standard in manually when working here.
+- The `files:` list on the architecture doc does not resolve against this repo, so file-based
+  knowledge search (`search --file=`) cannot bridge from Aegra code to that doc.
+
+## Two generations of the app live side by side
+
+| Branches | Stack | Build / deploy |
+|---|---|---|
+| `_production` (and older: `ai-model-cache-fix`, `previous-version`, `talos-golive`, `version2-api`) | **Vite** SPA (`vite.config.js`, `index.html`) | `buildspec.yml` + `.platform/` → Elastic Beanstalk |
+| `_beta`, `_next`, `TRUE-77539`, `TRUE-77871` | **Next.js 15** App Router, React 19 | `amplify.yml` → Amplify |
+
+So the Next.js rewrite described below is **not yet in `_production`** — production still serves the
+older Vite SPA. Check which branch you are reading before drawing conclusions.
+
+## The streaming stack
+
+- **`useStream` from `@langchain/langgraph-sdk/react`** — *not* `@langchain/react`. This is the
+  LangGraph SDK's own React binding.
+- Wrapped in an **app-owned** context (`StreamProvider` → `StreamSession` →
+  `StreamContext.Provider`, consumed via `useStreamContext()`), not the library's provider. That is
+  what lets app-specific auth/tenant/thread values be injected.
+- Generative-UI messages come from a second subpath, `@langchain/langgraph-sdk/react-ui`
+  (`uiMessageReducer`, `isUIMessage`, `isRemoveUIMessage`), folded into stream state via
+  `onCustomEvent`.
+
+Versions (`package.json`): `@langchain/core ^1.0.2`, `@langchain/langgraph ^1.0.1`,
+`@langchain/langgraph-sdk ^1.0.0`, `langgraph-nextjs-api-passthrough ^0.0.4`, `next ^15.4.10`,
+`react ^19.0.0`, `nuqs ^2.4.1`.
+
+The `useStream` config actually used (`src/providers/Stream.tsx`):
+
+```ts
+useTypedStream({
+  apiUrl,                       // absolute Aegra host — see below
+  apiKey: apiKey ?? undefined,  // X-Api-Key (LangSmith-style), separate from the bearer
+  assistantId,                  // URL query state, defaults to env.assistantId ("agent")
+  threadId: threadId ?? null,   // URL query state via nuqs
+  fetchStateHistory: true,
+  defaultHeaders: bearerToken ? { Authorization: `Bearer ${bearerToken}` } : undefined,
+  onCustomEvent: …,             // reduces UIMessage events into state.ui
+  onThreadId: …,                // writes the new threadId to the URL, then refetches the thread list
+});
+```
+
+Two independent credentials ride along: an **API key** (`apiKey`) and a **user bearer token**
+(`defaultHeaders`). The bearer is an **api2** JWT — `NEXT_PUBLIC_AUTH_API_URL` is
+`https://api.togahub.com/v2` (prod/gamma) or `https://api.beta.togahub.com/v2` (dev/beta) — issued
+for the **TogaHub** client, matching Aegra's `AUTH_TYPE=togahub`.
+
+**Readiness probe:** `checkGraphStatus()` `fetch`es `${apiUrl}/info` on mount and toasts on failure.
+A cheap, copyable way to derive a real "connected / not connected" state.
+
+**`threadId` and `assistantId` live in the URL** via `useQueryState` from **`nuqs`**, which is
+Next-only. A Vite/react-router app must use `useSearchParams` instead — do not lift this part
+verbatim.
+
+## The browser calls Aegra DIRECTLY; the Next.js proxy route is vestigial
+
+This is the load-bearing finding for anyone reusing the pattern.
+
+`getApiUrl()` returns `env.apiUrl` = `NEXT_PUBLIC_API_URL` = an **absolute external host**
+(`https://api.beta.togaiq.com`), and that same absolute URL is handed to `useStream({ apiUrl })`.
+Nothing routes through `src/app/api/[..._path]/route.ts`. The passthrough route is dead code:
+
+- It reads a **server-only** `LANGGRAPH_API_URL`, which **`.env.beta` does not define at all** — the
+  route would 500 there.
+- `env.ts`'s own doc comment on `apiUrl` still says *"proxied via /api"*. **That comment is stale**
+  and contradicts the value it annotates.
+
+**Consequence 1 (enabling):** Aegra already serves CORS to a browser on a different origin.
+A **static SPA with no server route handler** — e.g. toga25-supply on Amplify — *can* call Aegra
+directly. An earlier assumption that a server-side proxy was structurally required is **wrong**.
+
+**Consequence 2 (constraining):** the dead proxy pins the request origin:
+
+```ts
+// The backend validates the requesting domain against its Domains table.
+// Always send Origin: http://talos so the backend recognizes us.
+headers["Origin"] = "http://talos";
+```
+
+`Origin` is a **forbidden header** — a browser cannot set it from JS. So if that `Domains`-table
+gate is real, a new consumer origin needs **its own `Domains` row**; it cannot spoof its way in the
+way this server-side route did.
+
+## Environment config — every environment points at BETA
+
+Verified 2026-08-28:
+
+| File | `NEXT_PUBLIC_API_URL` | `LANGGRAPH_API_URL` (server-only, unused) |
+|---|---|---|
+| `.env.development` | `api.beta.togaiq.com` | `api.beta.togaiq.com` |
+| `.env.beta` | `api.beta.togaiq.com` | **not defined** |
+| `.env.gamma` | `api.beta.togaiq.com` | not defined |
+| `.env.production` | `api.beta.togaiq.com` | `api.beta.togaiq.com` — commented *"Currently not live with new version of ACL"* |
+
+**No environment in this repo is configured against a production Aegra host.** Treat "is there a
+live prod Aegra?" as an open question to confirm with the backend owners (`akhokhani`, `jcardinal`)
+rather than an assumption.
+
+## Gotchas
+
+- **`@langchain/react` is a different package** from what this app uses. It is a newer wrapper
+  (v1.0.33) over the same `@langchain/langgraph-sdk`, and it adds a `@langchain/core ^1.1.48` peer
+  plus media hooks/players. Do not assume talos validates it — talos uses the SDK's own
+  `/react` subpath.
+- **Do not copy `nuqs`** into a non-Next app (see above).
+- **`env.ts` is the only sanctioned env read** ("never access `process.env` directly elsewhere") and
+  `validateEnv()` throws at startup on missing vars. Keep new env reads inside it — but note its
+  comments have already drifted from its values once.
+
+## Change history
+- 2026-08-28 — Documented the previously-undocumented TOGa IQ chat front-end: `useStream` from
+  `@langchain/langgraph-sdk/react` wrapped in an app-owned context, the browser's **direct
+  cross-origin call to Aegra** (proving a static SPA needs no server proxy) and the vestigial
+  Next.js passthrough route with its unspoofable pinned `Origin`, the Vite `_production` vs Next.js
+  `_beta`/`_next` split, all-environments-point-at-beta env config, and the finding that no `talos`
+  branch contains the Python backend that `architecture.md` describes. Research only — no code
+  changed. (apeterson)

package/knowledge/2.0/apps/toga-blox/features/talos-assistant.md

@@ -25,6 +25,7 @@ related:
   - ../workflows/local-link-into-a-consumer-app.md
   - ../../toga25-supply/features/talos-integration.md
   - ../../ai-bdr/features/landing-chat-drawer.md
+  - ../../talos/features/chat-frontend.md
 ---
 
 ## Summary
@@ -140,8 +141,52 @@ Open questions were handed to the UX/UI team.
   same 40 fail with the Talos changes stashed. Do not read them as a regression from this work.
 - The drawer variant itself was **uncommitted working tree** at capture (2026-08-27).
 
+## The contract cannot express streaming — a real backend REQUIRES a contract change
+
+Reviewed 2026-08-28 against `TRUE-80692`. The 08-27 drawer-variant work widened `TalosResponse`
+(added `message`, `suggestions`, `cta`; made `paras` optional), but **every one of those is still a
+field on a single resolved value** — the contract remains **one-shot**:
+
+```ts
+onSend: (text: string) => Promise<TalosResponse>   // resolves ONCE, with the finished answer
+```
+
+`TalosMessageModel` / `TalosConversation` are documented "in-memory only". There is **no token
+delta, no `threadId`, no tool-call surface, and no interrupt representation** anywhere in
+`types.ts`.
+
+**So token streaming is NOT an adapter-implementation detail.** No adapter, however clever, can
+stream through a `Promise<TalosResponse>` — the promise resolves once. Wiring the live
+Aegra/LangGraph backend (which streams tokens, emits tool calls, and surfaces HITL interrupts —
+see [TOGa IQ chat frontend](../../talos/features/chat-frontend.md)) means changing this component's
+props. That was accepted deliberately rather than shipping a non-streaming v1.
+
+**Agreed direction (DECIDED 2026-08-28, NOT yet implemented):** make `TalosPanel` **controlled** —
+the host passes `messages` / `isStreaming` / `onSubmit` / `onStop` — plus an optional
+`connection?: "connecting" | "ready" | "error"` defaulting to `"ready"`.
+
+Two properties make this safe for a published package:
+
+- **Non-breaking.** `connection` defaults to `"ready"`, so existing consumers and
+  `createTalosStubAdapter()` keep working untouched.
+- **Consistent with what is already here.** `open` / `expanded` / `width` are *already* controlled
+  props owned by the host; moving `messages` to the host is the same pattern, not a new one.
+
+The panel also needs real **"connecting" / "failed to connect"** states: today a thrown `onSend` is
+its *only* failure path, which cannot represent "we never got a token to begin with."
+
+**The stream itself does NOT belong in blox.** Per
+[frontend.md §21](../../../standards/frontend.md) (promote only after a 2nd consumer validates the
+contract — Talos streaming is n=1) and **§13(b)** (blox peers do not hoist, so a `@langchain/core`
+peer would force all five consumer apps to install it, and a barrel import can surface that as a
+Rollup *"failed to resolve import"* for a component they never referenced). blox keeps
+`TalosLauncher` / `TalosPanel` as pure UI; the LangChain client stays app-local. blox's unbundled
+`tsc` + `fix-esm-imports` build is also fragile against a dep with subpath exports.
+
 ## Gotchas
 
+- **`onSend` cannot stream** — see the section above. A live streaming backend needs the
+  `TRUE-80692` contract change, not just an adapter.
 - The real chat backend is a later blox ticket — `onSend` is stubbed here; do not assume live
   responses from blox alone. **A working implementation exists outside blox and is now wired to
   this component:** `bdr/src/lib/talosChat.ts` implements the same
@@ -167,6 +212,13 @@ Open questions were handed to the UX/UI team.
   currently consumes it via a local symlink.
 
 ## Change history
+- 2026-08-28 — Review only (no blox code change): established that the `onSend(text) =>
+  Promise<TalosResponse>` contract **cannot express token streaming** — the 08-27 `message`/
+  `suggestions`/`cta` additions widen the *payload* but it still resolves once — so a live
+  streaming backend requires a `TRUE-80692` props change. Decided on a **controlled** `TalosPanel`
+  (`messages`/`isStreaming`/`onSubmit`/`onStop`) plus an optional `connection` prop defaulting to
+  `"ready"` so the change stays non-breaking. Also decided the LangChain client stays **app-local,
+  never a blox peer** (frontend.md §13b/§21). (apeterson)
 - 2026-08-27 — BUILT the **`drawer` variant** on `TRUE-80692` (uncommitted at capture): scrim +
   slide-in aside that stays mounted while closed, title bar, greeting-as-first-bubble
   (`welcome`), quick-reply chips, single-line composer, host `footer` slot, and a `features`

package/knowledge/2.0/apps/toga25-supply/features/talos-integration.md

@@ -6,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-08-20
+updated: 2026-08-28
 owners: [apeterson]
 files:
   - toga25-supply/src/layout/AppLayout/AppLayout.tsx
@@ -16,6 +16,8 @@ files:
   - toga25-supply/src/assets/talos-owl.png
 related:
   - ../../toga-blox/features/talos-assistant.md
+  - ../../talos/features/chat-frontend.md
+  - ../../../standards/frontend.md
 ---
 
 ## Summary
@@ -29,7 +31,8 @@ state and injects the adapter; the launcher renders in the header, the panel at
 
 - **AppLayout owns the state** — `open` / `expanded` / `width` / `dockWidth` — and injects the
   adapter:
-  - `onSend`: stub (real backend is a later blox ticket).
+  - `onSend`: **still the stub.** The live streaming backend is designed but unbuilt — see
+    *Real streaming backend* below.
   - `onOpenRecord(id)` → navigate `/sales-orders?sales-orders=<id>`.
   - `onAction("approvals")` → navigate `/sales-orders`.
   - `onDockWidthChange(px)` → reserve layout width for the docked panel.
@@ -48,5 +51,103 @@ header's right edge sitting **under** the panel, hiding the launcher + avatar. *
 the reserved dock width (`marginRight` = the `onDockWidthChange` value) to the **outer app
 wrapper** so the header shifts along with the content.
 
+## Real streaming backend — design (DECIDED 2026-08-28, NOT yet implemented)
+
+`onSend` is still the stub. The plan below replaces it with the live Aegra/LangGraph backend,
+copying the proven approach in [TOGa IQ's chat front-end](../../talos/features/chat-frontend.md).
+No code has been written yet.
+
+### Package choice: `@langchain/langgraph-sdk/react`, app-local
+
+- **Use `useStream` from `@langchain/langgraph-sdk/react`** — the same import talos uses — **not
+  `@langchain/react`.** Reasons: one fewer peer (`@langchain/react` additionally needs
+  `@langchain/core ^1.1.48`); the path is already proven in-house so
+  `talos/src/providers/Stream.tsx` can be lifted nearly verbatim; and `@langchain/react`'s extra
+  surface is largely **media hooks/players** that blox has no components to render.
+- **Take only `useStream` for v1.** Add `useToolCalls` when tool activity is actually shown, and the
+  headless interrupt helpers when doing human-in-the-loop — *that* is where `@langchain/react` earns
+  its keep, so revisit it then, not now.
+- **Write our own context provider** (as talos does) rather than the library's `StreamProvider` —
+  supply-specific token / tenant / `threadId` / Aegra URL must be injected.
+- **It stays in supply, never in blox.** Per [frontend.md §21](../../../standards/frontend.md) this
+  is n=1, and per §13(b) a blox peer would force `@langchain/core` on all five consumer apps. blox
+  keeps `TalosPanel` as pure UI.
+
+### Why a provider at all — three jobs
+
+1. **Singleton.** `useStream` is stateful; two call sites = two independent conversations.
+2. **Survive route changes.** The panel is docked in `AppLayout` while the user navigates. If the
+   stream lived inside the panel, any unmount would kill an in-flight response and lose history — so
+   it must sit **above the router outlet**.
+3. **Be the app↔blox boundary.** Supply's token/tenant/`threadId`/Aegra URL enter here and LangGraph
+   message shapes are translated here, keeping `TalosPanel` app-agnostic and reusable by desk and
+   commerce later.
+
+### Planned shape
+
+```
+src/api/talos.ts                                    — sole VITE_TALOS_API read chokepoint + token exchange
+src/providers/TalosStreamProvider.tsx               — the single useStream call, exposed via context
+src/layout/AppLayout/viewModel/useTalosViewModel.ts — flat shape for the panel
+```
+
+- **The mapper is where the estimate lives.** LangGraph `Message[]` → blox `TalosMessageModel[]` do
+  **not** line up: `type: "ai" | "human"` vs `role: "talos" | "user"`; streamed content blocks vs a
+  finished `paras: string[]`; and tool calls and interrupts have **no representation at all** in
+  blox's model. This is the same gap that forces the `TRUE-80692` contract change.
+- **`threadId` in URL search params via react-router 7 `useSearchParams`** — **not `nuqs`**, which is
+  Next-only. Do not copy that part of talos's provider (§5, URL as source of truth).
+- **Token held in React Query** per [frontend.md §3](../../../standards/frontend.md) — fetched server
+  state, never Zustand.
+- **Tear down token + `threadId` + conversation on logout and tenant switch** per §18.
+
+### Async auth gating — and the anti-pattern
+
+`useStream` takes the token as a **value** (`defaultHeaders`), not a promise, so you **cannot await
+it inside the hook**. That single constraint decides the design:
+
+- Awaiting the token inside `onSend` (via `queryClient.ensureQueryData`, reusing the panel's existing
+  thinking/error states, lazily fetching on first send) works **only** for the non-streaming one-shot
+  contract.
+- For **streaming**, the gate must sit **above** the hook — do not mount the stream until the token
+  query resolves. This is exactly why the panel's `connection` prop stops being optional polish and
+  becomes required.
+
+**Anti-pattern — do not use `useSuspenseQuery`/Suspense for this gate.** It suspends the subtree, so
+the panel **unmounts and remounts** — flashing and dropping whatever the user typed in the composer —
+and in a shared library the thrown promise surfaces in host apps that never opted into a boundary.
+Keep it a plain query.
+
+**Open product decision:** mid-stream 401 behavior — silent refresh and resume, vs. surface an error
+and let the user resend. Decide deliberately rather than discovering it in QA.
+
+## Aegra-side blockers — backend config, zero front-end code
+
+Each of these masquerades as a front-end bug. **Confirm them with the Aegra owners
+(`akhokhani`, `jcardinal`) BEFORE building the provider** — answer (c) especially decides whether the
+auth/loading layer gets built at all.
+
+- **(a) CORS allowlist** must include supply's **per-client hostnames** (nychh, compass, quad, …).
+  The symptom is a request that never leaves the browser — no response to debug. Note the browser
+  calls Aegra **directly** cross-origin (proven by talos), and a static Amplify SPA has no server
+  route handler to proxy through, so this is unavoidable. Related: Aegra also validates the
+  requesting domain against a `Domains` table, and `Origin` is a forbidden header a browser cannot
+  set — so a new origin needs its **own `Domains` row**.
+- **(b) Tenant provisioning is explicit, with no auto-create.** An unregistered org gets a clean
+  **403 on every call even with a valid token** (control-plane DB / `tenant_router` LRU — see
+  [talos architecture](../../talos/architecture.md)).
+- **(c) Token audience.** Aegra `AUTH_TYPE=togahub` validates api2 JWTs, but supply's token is issued
+  for the **supply** client, not TogaHub. Either Aegra accepts it (trivial) or supply needs a
+  handoff — api2 already exposes `/auth/delegator`, `/auth/encrypted`, and
+  `/auth/encrypted-user-uuid` for exactly this cross-app identity pass.
+
 ## Change history
+- 2026-08-28 — Design/research only, no code: chose `useStream` from
+  `@langchain/langgraph-sdk/react` (not `@langchain/react`), kept **app-local** rather than in blox
+  (frontend.md §13b/§21), and designed a route-surviving singleton `TalosStreamProvider` above the
+  router outlet plus a LangGraph→blox message mapper. Recorded that the token cannot be awaited
+  inside `useStream`, so streaming must gate **above** the hook (and **not** via
+  `useSuspenseQuery`, which remounts the panel and drops composer text), and logged three
+  Aegra-side blockers (per-client CORS hostnames, explicit tenant provisioning → 403, supply-vs-
+  TogaHub token audience) to confirm with the backend owners first. (apeterson)
 - 2026-08-20 — Wired the shared blox Talos assistant into supply for all clients: AppLayout hosts state + injects the adapter (stub `onSend`; `onOpenRecord`/`onAction` navigate to sales orders; `onDockWidthChange` reserves layout width), launcher in a new header `talosLauncher` slot, panel at app root, owl avatar + Plus Jakarta Sans loaded locally. Fixed the docked panel hiding the header launcher by reserving dock width on the outer wrapper (apeterson).

package/knowledge/INDEX.md

@@ -26,7 +26,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **saml** (SAML SSO Gateway) — 5 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
 - **toga2-view** (TOGa View Frontend) — 12 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)
 - **toga2-hub** (TOGa Hub) — 2 doc(s) → [2.0/apps/toga2-hub/INDEX.md](2.0/apps/toga2-hub/INDEX.md)
-- **talos** (TOGa IQ) — 7 doc(s) → [2.0/apps/talos/INDEX.md](2.0/apps/talos/INDEX.md)
+- **talos** (TOGa IQ) — 8 doc(s) → [2.0/apps/talos/INDEX.md](2.0/apps/talos/INDEX.md)
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)
 - **ai-bdr** (AI-BDR) — 13 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
 - **toga2-commerce** (TOGa Commerce) — 20 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)

package/knowledge/registry.json

@@ -145,8 +145,7 @@
     "project": "TOGa IQ",
     "framework": "2.0",
     "role": "app",
-    "dependsOn": [],
-    "language": "python"
+    "dependsOn": []
   },
   {
     "repo": "test",

package/package.json

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