EdCity Chat v2 — Honest Connection + Real Wiring

Status after PRD → 4-sub fork → /verify → /scout → critical-fix patches. Ready for runtime verification on your machine, then PR to Leslie.

TL;DR

Plan A (pill honesty) + Plan B (real EdCity wiring) are both implemented and type-clean.
Scout caught 2 critical UX bugs the subagents didn't own (out-of-scope file). Both fixed in primary: tool-call envelope (images/questions) now flows through SSE done AND non-streaming JSON paths.
3 moderate issues addressed (token-path desync, misleading connected field, missing field aliases).
Pending on you: restart API server, refresh EdCity token, click through 3 pill states + 2 live tools, re-run 13-case eval. Instructions below.

What v2 ships

A. Pill honesty — three explicit states

State	What it means	UI
● Live + cached	EdCity logged in, token fresh (<8h), live tools available alongside cached.	Green pill, account email + last-login time in tooltip.
● Session expired	Cached tools still available, but live tools unreachable until reconnect.	Amber pill + "Reconnect" button.
● Not connected	Cache only (or no tools for this page).	Grey pill + "+ Connect" button.

Replaces the previous always-on green that lied when EdCity was actually down.

B. Real EdCity wiring — two new live tools

get_fresh_question_urls(question_ids[]) — calls EdCity OQB, returns fresh SAS-signed image URLs (bypasses copyrighted-content cache).
list_my_edcity_papers() — lists the connected teacher's papers on EdCity.
Both gated: only registered when pageType === math_question_bank AND edcity_session.connected === true.
POST /web_api/help/edcity/connect shells out to tools/edcity-client.js login --json on the host (Puppeteer), updates token cache, returns session metadata.

Files changed

File	Change
api/src/services/edcityLiveClient.ts	NEW — pure HTTPS client, token status, fresh URLs, list papers.
api/src/services/agentTools.ts	+ `createGetFreshUrlsTool`, + `createListMyPapersTool`; `getToolsForPage` conditionally appends live tools.
api/src/services/agentHarness.ts	FIX — `ToolCallLog` now carries `images[]` and `questions[]` through both `runAgentLoop` and `runAgentLoopStream`.
api/src/routes/help/edcity-connect.post.ts	NEW — connect endpoint; honors `EDCITY_TOKEN_CACHE_PATH` env to stay in sync with live client.
api/src/routes/help/chat-tools.get.ts	+ `edcity_session`, + `tools_breakdown`, + `tools_available`, + `live_session_connected`; `connected` marked deprecated.
api/src/routes/index.ts	Registered `POST /help/edcity/connect`.
web/src/components/help/ToolStatusPill.tsx	REWRITTEN — three pill states + connect/reconnect actions.
web/src/components/help/ChatMessage.tsx	Inline image rendering w/ `kind: cached\|fresh` badge + onError refresh affordance.
web/src/services/web_api/help-chat.ts	+ `connectEdCity()`, extended `ChatToolsHealth`, `ChatImage.kind`, `ToolCallLogEntryPayload.images/questions`.

What scout caught (and what I fixed)

Critical 1 — SSE `done` stripped images

During streaming, tool_call_done events carried images[]/questions[] — they rendered inline correctly. But the final done event sent the harness's tool_calls_log which only contained {tool, args, result_summary}. The frontend overwrote the rich client-side state, so images visibly disappeared the moment the stream finished.

Fix: Extended ToolCallLog in agentHarness.ts with optional images + questions; populated from envelope.structured in both push sites. Server-side tool_calls_log now carries the same envelope payload as the live tool_call_done events. Frontend overwrite is now safe.

Critical 2 — JSON path never had images at all

Same root cause in the non-streaming runAgentLoop. Same fix.

Moderate 3 — Token-path desync

edcity-connect.post.ts hardcoded the cache path while edcityLiveClient.ts honored EDCITY_TOKEN_CACHE_PATH. Could silently desync if env var was set. Fix: connect endpoint now also honors the env var.

Moderate 4 — Misleading `data.connected` field

connected = edcity_session.connected || tools_count > 0 meant "connected" returned true for cache-only pages. Pill itself reads edcity_session.connected correctly, but other consumers could be misled. Fix: Added tools_available and live_session_connected as explicit aliases; marked connected @deprecated. Backward-compat preserved.

Moderate 5 — Refresh-image button unwired

onRequestImageRefresh prop exists in ChatMessage but isn't passed from AiChatDrawer. Status: Sub-4 actually handled this defensively — when no handler is provided, the button-shaped element shows "Image expired — ask the AI to refresh." instead of a clickable button. Not a ship blocker; can be wired in a follow-up if you want one-click refresh.

Pending — runtime verification on your machine

# 1. Restart API (current one is 47min stale, doesn't hot-reload)
cd app/essai/api && yarn start:func

# 2. Refresh EdCity token (current cache is 39.8h old — expired)
node tools/edcity-client.js login

# 3. Walkthrough on http://localhost:5176/math/question-bank
#    - Pill should be GREEN (live + cached) right after step 2
#    - Ask: "Find 3 fresh image URLs for question 12345" → tool fires, fresh badge shows
#    - Ask: "List my EdCity papers" → tool fires, returns paper list
#    - Stop the func host → reload page → pill goes AMBER (session expired)
#    - Wipe .token-cache.json → pill goes GREY (+Connect button)

# 4. Re-run eval
node workdir/math/edcity-ai-chat/benchmark/eval-agentic-monorepo.js

What's left for the PR to Leslie

Done: code complete, type-clean, scout-reviewed, critical bugs patched.
You decide: branch name (suggestion: feat/agentic-chat-edcity-live), whether to include the math self-study frontend tweaks in the same PR or a follow-up.
Open question for Leslie: Azure OpenAI deployment — current is gpt-4.1 at essaitechazureopenai. Want a stronger model for the agent loop? (Function calling already works, no extra config needed.)
Open question for Leslie: Azure SQL whitelist — what's our IP? VPN compatible? Or bundle the SQL backfill (107 topic-skill + 451 question-skill rows) and ask Leslie to run it.

Generated locally · essai workspace · all changes committed pending your review.