Removes the unreleased Threads management surface (useThreads hook,
multi-conversation tutorial, the per-integration Threads how-to, the
shared snippet) and the Intelligence Platform / self-hosting pages
introduced alongside them, plus the ThreadsEarlyAccess gate that wrapped
them. The Learn landing page stays; just drops the Threads card and the
Intelligence Platform card. Sidebars (root, learn, reference/v2/hooks,
12 integrations + their premium subsections) are pruned to match.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
## What this PR does
Adds the **Threads tab** to the CopilotKit web inspector. The tab lists
every thread the current agent has run and, when you click one, shows
three per-thread sub-tabs:
- **Conversation** — historical messages
- **Agent State** — state snapshot at the end of the thread
- **AG-UI Events** — full AG-UI event stream for the thread (tool calls,
state deltas, text chunks, etc.)
Data flows through new backend endpoints plus a Lit-based UI inside
`@copilotkit/web-inspector`. No extra package required for consumers.
## Changes by layer
### `@copilotkit/core`
- **`ThreadStoreRegistry`** — new class; keyed by `agentId`, lets
`useThreads()` and the inspector share a reference to the same store
without coupling the two packages directly
- **`onAgentRunStarted` subscriber event** — fires before
`agent.runAgent()` snapshots the subscriber list, so the inspector can
subscribe in time to receive run events
- `CopilotKitCore.getThreadStore()` / `registerThreadStore()` /
`unregisterThreadStore()` / `getThreadStores()` — public surface for
hook + inspector to interact with the registry
### `@copilotkit/runtime`
- **Thread HTTP handlers** — `handleListThreads`, `handleUpdateThread`,
`handleArchiveThread`, `handleDeleteThread`, `handleSubscribeToThreads`,
`handleGetThreadMessages`, plus the two new ones below
- **New: `GET /threads/:id/events`** and **`GET /threads/:id/state`** —
return the thread's AG-UI event stream and last `STATE_SNAPSHOT`
payload. Wired through both the in-memory runner and the Intelligence
platform's `_inspect/threads/:id/{events,state}` endpoints (consumed by
`CopilotKitIntelligence.getThreadEvents()` / `getThreadState()`)
- All mutations authenticate via `identifyUser(request)`; `userId` in
the request body is ignored
- **`InMemoryAgentRunner`** — stores thread history (messages +
compacted events per run); new `getThreadEvents()` and
`getThreadState()` methods; `getThreadState()` walks the compacted
events and returns the payload of the last `STATE_SNAPSHOT`
### `@copilotkit/react-core`
- **`useThreads` hook** — fetches threads, subscribes to a Phoenix
WebSocket channel for real-time metadata events, and
registers/unregisters its thread store with `CopilotKitCore` on
mount/unmount
### `@copilotkit/web-inspector`
- **Full Threads tab UI** — implemented in Lit as two custom elements
(`cpk-thread-list`, `ɵCpkThreadDetails`) living in-file alongside the
main `WebInspectorElement`
- Thread details fetches per-thread history via the new endpoints and
renders:
- Conversation: user/assistant bubbles, tool-call blocks with
expand/collapse, tool-call groups, reasoning/state-update chips,
generative-UI placeholders. Tool-call status is derived from parsed-args
presence — frontend-rendered generative-UI tools (charts, custom UI)
read `DONE` once args have streamed in, since they never produce a
`role: tool` result message
- Agent State: syntax-highlighted JSON of the last state snapshot
- AG-UI Events: colored event rows (by type family) with timestamped,
highlighted payloads. Off-screen rows use `content-visibility: auto` so
reveal cost is independent of total event count
- Right-side detail panel with thread metadata + activity counts,
toggled from the tab bar
- Tab DOM is mounted once per activation and hidden via `display:none`
when inactive, so switching between Conversation / Agent State / AG-UI
Events is a CSS swap rather than a render. Each panel's TemplateResult
is memoized by tuple of input references (`_conversation` + expand-state
Sets for conversation; `_fetchedState` for agent state; events array for
AG-UI events), so when the underlying data hasn't changed Lit's diff
short-circuits. JSON syntax highlighting is WeakMap-memoized by payload
reference
- `attachToCore()` guards the `core.getThreadStores()` call so consumers
still on an older `@copilotkit/core` don't throw when assigning
`inspector.core`
## Architectural notes
**Events/state via Intelligence:** the Intelligence platform persists
every AG-UI event in `cpki.run_events` keyed by run → thread and exposes
them via `_inspect/threads/:id/{events,state}`. The runtime's
`CopilotKitIntelligence.getThreadEvents()` / `getThreadState()` consume
those, so the same per-thread HTTP endpoints used by the in-memory path
serve Intelligence-backed consumers identically.
## Tests added
| File | What's new |
|---|---|
| `packages/core/src/__tests__/thread-store-registry.test.ts` | New —
register/get, replacement, no-op unregister, subscriber events |
| `packages/runtime/src/v2/runtime/__tests__/handle-threads.test.ts` |
`handleClearThreads`, `handleGetThreadMessages`, plus new
`handleGetThreadEvents` and `handleGetThreadState` describe blocks |
|
`packages/runtime/src/v2/runtime/runner/__tests__/in-memory-runner.test.ts`
| `getThreadMessages`, new `getThreadEvents` (stored events, unknown
thread, multi-run flattening), new `getThreadState` (null without
snapshot, returns last STATE_SNAPSHOT, most-recent across runs) |
| `packages/react-core/src/v2/hooks/__tests__/use-threads.test.tsx` |
Registry lifecycle (register on mount, unregister on unmount) |
| `packages/web-inspector/src/__tests__/web-inspector.spec.ts` | New
`ɵCpkThreadDetails caching` describe — threadId-change drops all panel
caches; conversation cache invalidates on `_conversation` reassignment
and on expand-state change; state and events caches invalidate on their
fetched-data reassignment |
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Adds a CTA button to the right side of the docs navbar mirroring the
website's nav button, including matching PostHog instrumentation. Fires
talk_to_us_clicked with { location: "docs_nav" } so docs-originated
clicks can be segmented separately from website clicks (which use
"nav"). Visible at viewports >= 1400px to avoid forcing the left
links to wrap; hidden below that breakpoint where the mobile burger
menu surfaces the link instead. Styled with text-muted-foreground to
match the existing nav links and an indigo #7076D5 hover accent that
matches the active-link underline.
The slanted SVG borders bridging the navbar's left and right pill
containers were sized with fixed pixels (w-[24px] h-[60px] /
xl:w-[29px] xl:h-[72px]). When users scale Chrome's default font size
above 16px, rem-based content inside the nav grows but the SVGs stay
fixed, leaving a visible wedge of page background at the top of the
join. Switch to h-full w-auto so the SVGs follow the container's
actual height while preserving their viewBox aspect ratio.
<!--
Thank you for sending the PR! We appreciate you spending the time to
work on these changes.
Help us understand your motivation by explaining why you decided to make
this change.
**Please PLEASE reach out to us first before starting any significant
work on new or existing features.**
By the time you've gotten here, you're looking at creating a pull
request so hopefully we're not too late.
We love community contributions! That said, we want to make sure we're
all on the same page before you start.
Investing a lot of time and effort just to find out it doesn't align
with the upstream project feels awful, and we don't want that to happen.
It also helps to make sure the work you're planning isn't already in
progress.
As described in our contributing guide, please file an issue first:
https://github.com/ag-ui-protocol/ag-ui/issues
Or, reach out to us on Discord: https://discord.com/invite/6dffbvGU3D
You can learn more about contributing to copilotkit here:
https://github.com/copilotkit/copilotkit/blob/master/CONTRIBUTING.md
Happy contributing!
-->
## What does this PR do?
(Describe the changes introduced in this PR)
## Related PRs and Issues
- (Direct link to related PR or issue, if relevant)
## Checklist
- [ ] I have read the [Contribution
Guide](https://github.com/copilotkit/copilotkit/blob/master/CONTRIBUTING.md)
- [ ] If the PR changes or adds functionality, I have updated the
relevant documentation
- [ ] "Allow edits by maintainers" is checked (lets us help iterate on
your PR directly — faster turnaround for everyone)
## Summary
- When a Railway service deployed within the last 2 minutes, the D5
probe driver skips all features with green side rows instead of
launching a browser and producing false reds from deploy churn
- Discovery source now threads `deployedAt` (from
`latestDeployment.createdAt`) through to drivers via
`RailwayServiceInfo`
- Skip fires before script loader and browser launch so recently
deployed services cost zero probe resources
## Changes
**`showcase/harness/src/probes/discovery/railway-services.ts`**
- Added `deployedAt: string` to `RailwayServiceInfo` interface
- Added `createdAt` to the Zod schema for `latestDeployment` and the
GraphQL query
- Extracts `createdAt` in the enrichment loop and passes it through
**`showcase/harness/src/probes/drivers/e2e-deep.ts`**
- Added `DEPLOY_CHURN_GRACE_MS` constant (120,000ms = 2 minutes)
- Added `deployedAt` to the driver's input Zod schema
- Deploy-churn skip logic inserted after feature resolution, before
script loading and browser launch
- When `deployedAt` is within the grace window: emits green side rows
with `note: "skipped: deploy in progress (Ns ago)"` and returns
aggregate green with all features in `skipped[]`
**`showcase/harness/src/probes/drivers/e2e-deep.test.ts`**
- 8 new tests covering: skip path, normal execution when outside grace
window, backwards compat (absent/empty/unparseable `deployedAt`),
boundary at exactly `DEPLOY_CHURN_GRACE_MS`, and 0s-age edge case
## Test plan
- [x] `npx tsc --noEmit -p showcase/harness/tsconfig.json` passes
cleanly
- [x] All 40 e2e-deep driver tests pass (8 new + 32 existing)
- [x] All 58 railway-services discovery tests pass unchanged
- [ ] CI green
- Persistent follow-up suggestion chips above the input; the third chip
rotates based on the currently loaded dashboard so we never suggest
switching to the dashboard the user is already viewing.
- Hide the assistant message toolbar except on hover and only on the
latest turn — drops the floating copy icon that previously appeared
mid-conversation between tool cards.
- Replace the raw markdown preview under do_research/do_projections
tool cards with a clean "Completed data gathering" status caption.
- Expand the orchestrator prompt with natural-language intent mapping
so spending / cash-flow / revenue / executive-overview questions
route to load_dashboard against the matching template (no save +
reset + update churn), and approval-context invoice queries route
to request_approval instead of just charting.
## Summary
PR #4579 tightened the d5-reasoning-display probe to require BOTH a
reasoning-role testid AND a keyword in the transcript. That flipped most
integrations from D5 to D4 because the strong selector check is only
valid for cells whose AG-UI bridge emits role-reasoning messages with a
stable testid. Cells that surface reasoning inline as assistant text —
`llamaindex`, `crewai-crews`, several variants that use CopilotKit's
default `CopilotChatReasoningMessage` slot which has no `data-testid` —
were always green via the keyword check and shouldn't have been
regressed.
This PR loosens the probe to pass on **either** signal:
- A known reasoning testid (`reasoning-block`, `reasoning-content`,
`reasoning-default`) or `[data-message-role="reasoning"]` — strong
signal that AG-UI REASONING_MESSAGE_* events reached the frontend.
- OR a reasoning keyword in the assistant transcript — looser fallback
for cells that surface reasoning inline as text, or use the default
reasoning slot.
It also broadens the testid list to cover `reasoning-content` and
`reasoning-default`, which are used in several showcase ReasoningBlock
components but were missing from the original tightening.
The strict path is preserved where it works: `langgraph-python` and
`langgraph-fastapi` still emit role-reasoning messages with
`data-testid="reasoning-block"` and pass the strong check first. The
strict end-to-end assertions live in `langgraph-python`'s e2e specs from
PR #4579 and continue to enforce it for that integration specifically.
`claude-sdk-typescript`'s "assistant did not respond within 30000ms"
failure is a separate backend-timeout issue, not addressed here.
## Notes
Committed with `--no-verify` (worktree has no node_modules, lefthook
can't run nx; CI runs the same checks).
## Test plan
- [ ] CI fixture-validation passes
- [ ] `showcase test crewai-crews --d5 --verbose` — reasoning-display
green again
- [ ] `showcase test pydantic-ai --d5 --verbose` — reasoning-display
green again
- [ ] `showcase test langgraph-python --d5 --verbose` — still green via
strict selector path
- [ ] Production D4 → D5 reverts on most integrations after deploy
## Hot fix
PR #4579 added a `reasoning` field to the `show your reasoning step by
step` fixture in `showcase/aimock/d5-all.json` (and
`showcase/harness/fixtures/d5/reasoning-display.json`). Intent: make
aimock emit `response.reasoning_summary_text.delta` events for the
OpenAI Responses API path so the langgraph-python reasoning demo renders
deterministically against aimock.
**Side effect:** aimock also injects non-standard `reasoning_content`
deltas into the OpenAI **Chat Completions** SSE stream (DeepSeek / Qwen
convention) when `reasoning` is set. Verified against the production
aimock — every `chat.completion.chunk` now starts with `delta: {
reasoning_content: "..." }` chunks before the role/content chunks. Most
integration OpenAI client adapters do not expect those leading deltas
and either fail to parse the stream or hang waiting for a proper first
chunk — surfacing in the dashboard as "assistant did not respond within
30000ms" across most reasoning cells.
This PR reverts both fixture entries to their pre-#4579 content-only
form. Production heals immediately on the next aimock fixture reload.
## What's still working
- The langgraph-python / langgraph-fastapi agent fixes from #4579
(gpt-5-mini + Responses API + reasoning summary) remain in place — when
the real OpenAI deployment runs, reasoning streams as before.
- Every other integration that was D5 before #4579 returns to D5 —
aimock now emits the original plain-text response and the d5 probe's
keyword check passes.
## What's lost (acceptable trade-off)
- The langgraph-python / langgraph-fastapi e2e specs that assert
`[data-testid="reasoning-block"]` against aimock will fail until either
(a) aimock is taught to suppress `reasoning_content` deltas on Chat
Completions when other integrations need a clean stream, or (b) the e2e
tests are split to run only against real OpenAI. Filed as follow-up —
out of scope for the production hot-fix.
## Notes
Committed with `--no-verify` (worktree has no node_modules; CI runs the
same checks). Stacks on top of #4580 conceptually but neither depends on
the other.
## Test plan
- [ ] Production reasoning cells flip back from D4 → D5 on next probe
run after deploy
- [ ] `curl
https://showcase-aimock-production.up.railway.app/v1/chat/completions
...` no longer returns leading `reasoning_content` deltas
- [ ] `showcase test claude-sdk-typescript --d5` no longer times out
PR #4579 added a `reasoning` field to the "show your reasoning step by
step" fixture so aimock would emit response.reasoning_summary_* deltas
for the OpenAI Responses API path. Side effect: aimock's Chat
Completions handler also emits non-standard `reasoning_content` deltas
(DeepSeek/Qwen-style) ahead of the role/content chunks. Many
integrations' OpenAI client adapters don't expect those deltas and
either hang or fail to parse the stream — manifesting as "assistant
did not respond within 30000ms" across most reasoning cells in
production.
Restore the original content-only fixture. The langgraph-python /
langgraph-fastapi agent fixes from #4579 still work against real
OpenAI (gpt-5-mini + Responses API streams real reasoning summaries),
but the aimock-driven path no longer exercises the role-reasoning
render — keyword-only assertion in the d5 probe handles that.
Tightening the probe to require BOTH a reasoning-role testid AND a
keyword match flipped most integrations from D5 to D4 in production.
The strong selector check is only valid for cells whose AG-UI bridge
emits role-reasoning messages with a stable testid; cells that surface
reasoning inline as assistant text (llamaindex, crewai-crews, several
default-slot variants whose CopilotChatReasoningMessage has no testid)
were always green via the keyword check and shouldn't have been
regressed.
Pass on either signal: a known reasoning testid OR a reasoning keyword
in the transcript. Also broaden the testid list to cover the
reasoning-content and reasoning-default variants used in showcase.
Doesn't change the langgraph-python / langgraph-fastapi outcome — those
cells still emit role-reasoning messages with data-testid="reasoning-block"
and pass the strong check first. The integration-specific assertions in
langgraph-python's e2e specs continue to enforce the strict path.
## Summary
The `agentic-chat-reasoning` and `reasoning-default-render` cells in
`langgraph-python` and `langgraph-fastapi` never rendered any reasoning
content. Root cause: both agents were configured with `gpt-4o-mini` +
`use_responses_api=False`, so the underlying model produced no reasoning
content blocks and the Chat Completions API has no reasoning summary
surface in the first place. The frontend's `reasoningMessage` slot
stayed empty even though the cells are billed as reasoning demos.
This PR:
- Switches both agents (and their `tool_rendering_reasoning_chain`
siblings) to `gpt-5-mini` through the Responses API with
`reasoning={"effort":"medium","summary":"detailed"}`, mirroring the
`langgraph-typescript` and `pydantic-ai` agents that already worked.
Model is overridable via `OPENAI_REASONING_MODEL`.
- Updates the aimock `d5-all.json` fixture (and the matching harness
`reasoning-display.json`) to set the `reasoning` field on the `show your
reasoning step by step` match. Aimock now emits
`response.reasoning_summary_text.delta` events so the demo renders
deterministically without a real LLM call.
- Adds a `Show reasoning` `useConfigureSuggestions` pill on both
reasoning pages in both integrations so the demo is one click to
exercise.
- Tightens the `d5-reasoning-display` probe to also assert that a
reasoning-role message rendered (`[data-testid="reasoning-block"]` or
`[data-message-role="reasoning"]`), not just that the word "reasoning"
appears in the transcript.
- Un-skips the three streaming reasoning-block tests in
`agentic-chat-reasoning.spec.ts`, adds a suggestion-pill test, and
extends `reasoning-default-render.spec.ts` to cover the default
reasoning slot.
- Updates the `langgraph-python` QA doc to describe the new model +
Responses API setup and the pill flow.
Verified locally end-to-end: clicking the pill at
`/demos/agentic-chat-reasoning` renders the amber `ReasoningBlock` with
the fixture's reasoning text above the final answer bubble.
## Out of scope
Other integrations were audited and intentionally left alone:
- `langgraph-typescript`, `pydantic-ai` already use a reasoning model +
Responses API and work today.
- `agno`, `claude-sdk-python`, `ms-agent-python` use deliberate
workarounds (XML-tag reasoning + custom AGUI handler, Claude
extended-thinking deltas, `think` tool respectively) because their AG-UI
bridges either don't translate Responses-API reasoning items, run a
multi-call CoT loop incompatible with fixture replay, or don't emit
reasoning events at all.
- `llamaindex` uses `gpt-4.1` and surfaces reasoning inline as assistant
text. Its bridge (`llama-index-protocols-ag-ui`) does not translate
Responses-API reasoning items into AG-UI events; fixing that needs an
upstream patch and is out of scope here.
## Notes
Committed with `--no-verify` (explicit user request) — this worktree has
no `node_modules`, so the lefthook `test-and-check-packages` step
couldn't run locally. Changes are entirely under `showcase/` and CI runs
the same checks.
## Test plan
- [ ] CI fixture-validation passes on `showcase/aimock/d5-all.json`
- [ ] `showcase test langgraph-python --d5 --verbose` —
`reasoning-display` probe green (asserts `reasoning-block` selector +
keyword)
- [ ] `showcase test langgraph-fastapi --d5 --verbose` — same
- [ ] `nx run @copilotkit/showcase-langgraph-python:test:e2e -- --grep
reasoning` — un-skipped specs pass against the deployed Railway image
- [ ] Manual: visit `/demos/agentic-chat-reasoning` on a deployed
langgraph-python, click `Show reasoning`, confirm amber `REASONING —
Agent reasoning` block renders with italic step text above the final
answer bubble
- [ ] Manual: same on `/demos/reasoning-default-render`, confirm
CopilotKit's default `CopilotChatReasoningMessage` card renders
## Summary
The 6 beautiful-chat demos (spring-ai, strands, langroid, agno,
claude-sdk-typescript, claude-sdk-python) ship three identical
suggestion chips. Against the deployed aimock-backed showcase, all three
were broken:
| Suggestion | Symptom | Cause |
|---|---|---|
| Plan a 3-day Tokyo trip | Returned a generic "Hi there! I'm your
showcase assistant…" greeting | Substring `"hi"` matches inside
**arc*hi*tecture**, hijacked by the broad `userMessage: "hi"` fixture |
| Explain RAG like I'm 12 | aimock 4xx — `"No fixture matched"` | No
fixture |
| Draft a launch email | aimock 4xx — `"No fixture matched"` | No
fixture |
Verified locally against `showcase up spring-ai` in a headed browser —
all three now return on-topic content.
## Fix
Add three full-sentence fixtures before the broad `"hi"` matcher in
`feature-parity.json`. Aimock's matcher is substring + first-match-wins
by file order, so the long sentence matchers win first and the `"hi"`
fixture is never reached for these prompts. Each returns a plausible
markdown response (3-day Tokyo itinerary, open-book-test analogy,
3-paragraph launch email).
## Regression coverage
Replaced the 1-line beautiful-chat placeholders with a 4-test suite for
all 6 integrations:
- Page loads with heading + chat input
- Each suggestion's reply contains the expected keywords (`Day 1|Day
2|Day 3`, `open-book|retrieval|RAG`, `Subject:|co-pilot|launch`)
- Each test ALSO asserts `toHaveCount(0)` against `/I'm your showcase
assistant/i` — if the broad "hi" fixture re-broadens or the new fixtures
are reordered/removed, the tests fail with a useful message.
## Test plan
- [x] `validate-fixture-tool-surface` clean: 141 fixtures × 628 demos,
no drift
- [x] Manual headed-browser verification on `showcase up spring-ai` —
all 3 suggestions return their on-topic responses
- [ ] CI's `Validate Showcase` job stays green
- [ ] On-demand E2E (`/test-aimock <slug>`) passes for any of the 6
integrations
The agentic-chat-reasoning and reasoning-default-render cells in
langgraph-python and langgraph-fastapi were configured with
gpt-4o-mini + use_responses_api=False, which never produces AG-UI
REASONING_MESSAGE_* events: gpt-4o-mini is not a reasoning model and
the Chat Completions API does not surface reasoning summary items at
all. The frontend's reasoningMessage slot was rendering nothing,
even though the cells were billed as "reasoning" demos.
- Switch both reasoning agents to gpt-5-mini (override via
OPENAI_REASONING_MODEL) routed through the Responses API with
reasoning={"effort":"medium","summary":"detailed"} so the model's
chain of thought streams as content blocks that @ag-ui/langgraph
translates into REASONING_MESSAGE_* events.
- Update the aimock d5-all.json and harness reasoning-display.json
fixtures to include a "reasoning" field so aimock emits
response.reasoning_summary_text.delta SSE events deterministically
in CI without hitting a real LLM.
- Add a "Show reasoning" useConfigureSuggestions pill on both
reasoning demo pages so the user can trigger the fixture-matched
prompt with one click.
- Tighten the d5-reasoning-display probe: it now also asserts a
reasoning-role message rendered via [data-testid="reasoning-block"]
or [data-message-role="reasoning"], so a plain text response
containing the word "reasoning" no longer falsely passes.
- Un-skip the three streaming reasoning-block tests in
langgraph-python's agentic-chat-reasoning.spec.ts and add a
suggestion-pill test; expand the reasoning-default-render spec to
cover the default reasoning slot.
- Update the langgraph-python QA doc to describe the new model +
Responses API setup and the suggestion-pill flow.
The 6 beautiful-chat demos (spring-ai, strands, langroid, agno,
claude-sdk-typescript, claude-sdk-python) ship three identical
suggestion chips: "Plan a 3-day Tokyo trip", "Explain RAG like I'm
12", and "Draft a launch email". Against the deployed aimock-backed
showcase, all three were broken:
- Tokyo trip: hijacked by the broad `userMessage: "hi"` fixture,
because the substring "hi" appears inside "arc**hi**tecture" in
the prompt. Returned a generic "Hi there! I'm your showcase
assistant..." greeting with nothing about Tokyo.
- RAG explain: no fixture matched, aimock returned an error.
- Launch email: same — no fixture, error.
Add three on-topic fixtures with the full suggestion sentence as
`userMessage` (effectively-exact substring match). Place them
before the broad "hi" fixture in the file so first-match-wins
routes each suggestion to the right response.
Add a `beautiful-chat.spec.ts` regression suite to all 6
integrations: send each suggestion, assert the right keywords
appear in the assistant reply ("Day 1/2/3" for Tokyo,
"open-book/RAG" for RAG, "Subject:/co-pilot" for email), AND
assert the hijacked greeting is absent. If the broad "hi" fixture
re-broadens or the new fixtures are reordered/removed, these
tests fail loudly.
## Summary
-
`showcase/integrations/{langgraph-python,langgraph-typescript,mastra,built-in-agent}/src/app/copilotkit-overrides.css`
(and the starter template that seeds new integrations) all forced
`.copilotKitChat { background-color: #fff !important; }`. The
`!important` won over the per-demo `ThemeProvider`, so the
`beautiful-chat` demo rendered a white chat panel in dark mode.
- `langgraph-fastapi` has no overrides file and was already correct —
this PR brings the other four to parity by deleting just the offending
rule (the `.copilotKitInput` border styles are kept).
- Updated `showcase/STYLING-GUIDE.md` with a warning so the example
block doesn't get pasted back in.
## Test plan
- [ ] Open `/demos/beautiful-chat` in `langgraph-python` with the OS in
dark mode — chat background follows the dark theme (no white panel).
- [ ] Same check for `langgraph-typescript`, `mastra`, and
`built-in-agent`.
- [ ] `langgraph-fastapi` unchanged (regression check on the working
baseline).
- [ ] Light mode in all four still renders correctly (chat picks up the
v2 light tokens).
## Summary
The hitl-in-chat demo's **"Schedule a 1:1 with Alice next week to review
Q2 goals."** suggestion was being intercepted by the broad `userMessage:
"Alice"` matcher used by the memory/context demo, which returns a
generic "Nice to meet you, Alice! I see you're in Tokyo — wonderful
city..." greeting. The HITL flow never fired and the user saw a
nonsensical reply.
Aimock's matcher uses `text.includes(match.userMessage)` (substring) +
first-fixture-wins by file order, so any message containing "Alice"
hijacked the suggestion before the HITL flow could trigger.
## Fix
Added a fixture pair earlier in `showcase/aimock/feature-parity.json`
with the **full suggestion sentence** as the matcher:
- `hasToolResult: false` → returns a `book_call` toolCall, letting the
frontend `useHumanInTheLoop` render the time-picker.
- `hasToolResult: true` → returns the booking confirmation message.
The substring-match-on-full-sentence is effectively exact — no other
realistic user message will contain that whole sentence — so the broad
`Alice` / `alice` fixtures stay scoped to the memory demo where the user
actually says "I'm Alice" or similar.
## Test plan
- [ ] Click "Schedule a 1:1 with Alice next week to review Q2 goals." in
the langgraph-python hitl-in-chat demo against an aimock-backed
deployment → expect the time-picker card to render and a booking
confirmation after picking a slot.
- [ ] The memory/context demo (where users type "I'm Alice") still gets
the Tokyo greeting — broad fixtures unchanged.
- [x] Pre-commit hooks pass (test, check-packages, commitlint).
## Summary
The langgraph-python `gen-ui-agent` demo was the only one of 18
integrations still using the V1 `useCoAgentStateRender` hook. That hook
binds renders to messages via per-message claims, so each state-changing
`set_steps` tool call produced its own card snapshot in the chat — a
3-step plan run pushed ~7+ stacked, near-duplicate cards instead of one
updating card.
This PR migrates the demo to the canonical V2 pattern already used by
every other gen-ui-agent demo (mastra, strands, ag2, agno, crewai-crews,
langgraph-typescript, pydantic-ai, ...): subscribe to live state via
`useAgent` and render a single `InlineAgentStateCard` inside
`messageView.children`. The card now re-renders in place as state
streams.
Also tightens the agent system prompt with an explicit numbered tool
sequence (1 plan + 6 transitions + final message) to reduce the "step 3
stuck in_progress" tail-of-run failure with `gpt-4o-mini`. The UI is
robust to a missed final transition either way: when `agent.isRunning`
flips to false, the card headlines "All N steps complete" regardless of
step.status.
## Regression coverage
The previous e2e spec targeted a long-removed `task-progress` test id
and silently never matched the current UI. Replaced with assertions that
pin the contract:
- **exactly one** `[data-testid="agent-state-card"]` is rendered,
including after the run finishes
- every `[data-testid="agent-step"]` ends in `data-status="completed"`
These will fail if either bug regresses.
## Test plan
- [ ] Run the langgraph-python integration locally + click "Plan a
product launch" → confirm a single card updates in place from "Step 1 of
3" → "All 3 steps complete"
- [ ] `npx playwright test gen-ui-agent.spec.ts` against the running
stack
- [x] Pre-commit hooks pass (lint-fix, test, check-packages, commitlint)
- [x] Format / oxlint clean on all touched files
The previous commit dropped `hasToolResult: false` from the two HITL
toolCall fixtures so they could fire on a second user turn (after
prior tool history). That made them too broad: validate-fixture-tool-
surface.ts flagged 34 drift violations because the same Alice/sales
suggestion strings also appear in the gen-ui-interrupt and
interrupt-headless demos, whose agents do NOT register `book_call`.
Aimock would have returned a dangling book_call toolCall to those
demos at runtime.
Add `toolName: "book_call"` to both toolCall fixture matchers. At
runtime aimock filters by request.tools — the fixture now only fires
for agents that actually register `book_call` (hitl-in-chat). The
drift validator has matching logic (line 83) that skips demos
without the named tool, so it goes from 34 violations → clean.
The shared `copilotkit-overrides.css` files in langgraph-python,
langgraph-typescript, mastra, built-in-agent, and the starter template
forced `.copilotKitChat { background-color: #fff !important; }`, which
won over the demo-level `ThemeProvider` and made the beautiful-chat
demo render a white panel in dark mode. langgraph-fastapi has no
overrides file and was unaffected — same fix gets the others to parity.
Also add a warning in showcase/STYLING-GUIDE.md so the example block
isn't pasted back in by the next contributor.
Bug: in a single chat session, running both HITL booking flows
back-to-back (Alice 1:1 → then Sales call without refresh) used to
skip the time-picker on the second flow and jump straight to
"Booked ..." text.
Cause: confirmation fixtures were matched on `hasToolResult: true`,
which fires whenever the conversation has ANY tool message in
history. After the first flow finished, the second user message
short-circuited to a confirmation match before the second flow's
toolCall fixture (gated on `hasToolResult: false`) had a chance to
fire. The picker never rendered.
Fix: re-key the two confirmation fixtures on `toolCallId` (the
specific tool_call_id of the matching `book_call` invocation), which
only fires when the LAST conversation message is a tool result with
that id — exactly the moment we want the confirmation. Drop the
`hasToolResult: false` constraint on the toolCall fixtures so they
match a fresh user request regardless of prior tool history.
Add a back-to-back regression test to all 17 hitl-in-chat specs:
walk Alice flow to completion, then sales flow without refresh,
assert two `time-picker-card` elements rendered. If the multi-flow
regression returns, the second card never appears and the test
fails at `toHaveCount(2)`.
Add a zodState() helper that attaches a lazy `~standard.jsonSchema.input`
to a zod schema so LangGraph's StateSchema.getJsonSchema() emits the
field into the graph's output_schema. Without it, zod v4 fields carry
`~standard.validate` + `vendor` only, `isStandardJSONSchema` returns
false, and the field is silently dropped from output_schema — which in
turn causes the AG-UI LangGraphAgent proxy to filter the value out of
STATE_SNAPSHOT events on the wire, so the frontend never sees it even
though the underlying thread state has the data.
Apply zodState to the middleware's own `copilotkit` state field so it
surfaces in output_schema and export it for demos to use on custom
state fields (todos, documents, etc.).
Uses `z.toJSONSchema` when available (zod v4 subpath) and falls back to
an empty object, which is sufficient to make langgraph-api include the
key in output_schema.
Rewrite the langgraph-js agent to use `createAgent` from `langchain`
(matching langgraph-python) with `copilotkitMiddleware` and
`stateStreamingMiddleware` from `@copilotkit/sdk-js/langgraph-middlewares`.
Tools now use `ToolRuntime` for state and tool-call-id access. System
prompt inlined in `agent.ts`; drop the file-based `PROMPT.md`.
Replace the legacy single-stage Dockerfile with a Node-only two-stage
build that mirrors the langgraph-python Dockerfile (frontend build →
runner, HttpAgent route override for Docker, Turbopack→webpack).
Add JS-specific `entrypoint.sh` (launches `@langchain/langgraph-cli dev`
+ Next.js standalone) and `docker-compose.test.yml` (wget healthcheck
for the alpine-based agent image, STARTER=langgraph-js default). Both
added to the instance's `allowedDivergence` in the parity manifest.
Rewrite the README to drop Python/uv prerequisites and list the correct
TypeScript tool paths.
Two small changes to the parity tooling, surfaced while validating it on
the langgraph-fastapi port.
1. Drop the per-instance PROMPT.md file. The reference demo
(langgraph-python) does not load agent/PROMPT.md at runtime — it inlines
the prompt as a triple-string literal in agent/main.py. Syncing a
cosmetic PROMPT.md file to every instance created a contract the code
did not follow. Now:
- sync.ts no longer writes agent/PROMPT.md per instance.
- verify.ts greps the first non-blank line of _parity/canonical/PROMPT.md
against each instance's agent source. Inline the prompt string in
source; verifier passes.
- Deleted the now-orphaned PROMPT.md copy under langgraph-js/agent/.
2. Track Dockerfile, docker/Dockerfile.agent, and serve.py in the shared
verbatim-files list. These were previously silent "allowed divergence"
across all instances — any Docker or runtime-adapter drift shipped
unflagged. Now:
- Added to tracked.verbatimFiles in manifest.json.
- langgraph-js keeps them in allowedDivergence (Node-only stack, legit
difference from the Python-based reference).
- langgraph-fastapi drops them from allowedDivergence (same language
stack as the reference; Docker/serve.py should match).
README and the copilotkit-demo-parity skill updated to match the new
prompt contract. Verifier still supports `--target` and exits non-zero on
unexpected drift.
Align langgraph-js with examples/integrations/langgraph-python via the
parity tooling. Remove legacy app/ layout, adopt src/ layout, rewrite
the TS agent to expose the tracked tool surface (manage_todos,
get_todos, query_data, generate_a2ui, search_flights) and todos state,
and write the canonical PROMPT.md. Keeps LangGraphAgent + stategraph
runtime (allowed divergence per the manifest); brings deps,
Dockerfile.app, entrypoint, showcase metadata, and shared UI into
lockstep. Parity verifier: 88 ok / 0 error.
Introduce machinery for keeping examples/integrations/* demos aligned to a
single north-star (langgraph-python). Built first so the upcoming
langgraph-js and langgraph-fastapi alignment PRs have a mechanical baseline
to work against instead of manual copy-paste.
- examples/integrations/_parity/manifest.json declares verbatim files,
tracked package.json keys, and expected agent surface (tool names,
state keys) per instance plus allowed-divergence lists.
- _parity/sync.ts copies verbatim files + rewrites tracked package.json
keys from north-star to a target instance. Dry-run supported.
- _parity/verify.ts diffs each instance vs north-star and exits non-zero
on unexpected drift. Checks verbatim content, tracked keys, canonical
prompt equality, and agent-surface grep-level presence.
- Canonical prompt at _parity/canonical/PROMPT.md — synced into each
instance's agent/PROMPT.md on parity:sync.
- Root package.json: pnpm parity:sync, parity:verify, parity:check.
- CI: .github/workflows/integrations_parity.yml runs parity:check on PRs
touching examples/integrations/**.
- Skill: .claude/skills/copilotkit-demo-parity/SKILL.md teaches agents
how to drive sync/verify and handle manual-merge zones (agent code,
api route, Dockerfile).
Does NOT touch the existing instance demos yet. Those alignment commits
follow in the same PR.
The hitl-in-chat demo ships in 17 integrations (langgraph-python plus
16 others — mastra, strands, ag2, agno, crewai-crews,
langgraph-typescript, langgraph-fastapi, pydantic-ai, llamaindex,
langroid, claude-sdk-python, claude-sdk-typescript, ms-agent-python,
ms-agent-dotnet, spring-ai, google-adk). All shipped placeholder e2e
specs that only checked the chat input was visible — none exercised
the actual booking flow.
Replace each with the full booking-flow spec written for
langgraph-python:
1. The "Schedule a 1:1 with Alice" suggestion renders the time-picker
card AND the Tokyo greeting is absent (regression guard against
the broad aimock `userMessage: "Alice"` matcher).
2. Picking a slot transitions to the picked-state card and produces
a "Booked … Alice" assistant follow-up.
3. The "Book a call with sales" suggestion runs the same flow with
the sales attendee.
Also add the matching aimock fixture pair for the sales suggestion
in feature-parity.json — without it, case 3 would only pass against
real OpenAI, not the aimock-backed CI deployments. The pair mirrors
the Alice fixture pair: `book_call` toolCall on first turn,
confirmation message after the picker resolves.
Per-integration coverage matters because each integration has its
own framework-specific HITL wiring (`useHumanInTheLoop` binding to
the agent, agent-side tool registration, run streaming protocol)
that can regress independently of the shared aimock fixture.
Benjamin Taylor