The starter had two App Router dirs: a stale top-level app/ containing only
an /api/copilotkit route (with a wrong graphId "starterAgent") and the real
src/app/ with page.tsx + layout.tsx. At copilotkit 1.59.3 the build silently
dropped the / route from src/app (masked by next.config ignoreBuildErrors),
producing only /api/copilotkit/[[...slug]]. The app served GET / as 404, so the
docker healthcheck (GET / === 200) never passed and the smoke leg failed with
the app container unhealthy before tests ran.
Removing the duplicate top-level app/ lets Next build src/app unambiguously,
restoring the / route. Local docker-compose.test.yml smoke: app healthy in ~5s,
4 passed (@health, @agent, @chat, @interaction).
The v2 migration renamed the Mastra agent key to `default` and updated
page.tsx/index.ts, but layout.tsx was missed: it still pinned
`agent="weatherAgent"` (now non-existent) and lacked
`useSingleEndpoint={false}`. The single-endpoint auto-detect races the
lazily-compiled API route, producing a 404 console error on page load
that fails the @interaction smoke leg's zero-console-error assertion.
Match the passing sibling starters (pydantic-ai/adk/ms-agent-framework-python).
Migrate adk, agno, crewai-crews, crewai-flows, mastra, pydantic-ai, ms-agent-framework-dotnet, ms-agent-framework-python, and llamaindex starters to the CopilotKit v2 `@chat` API and float them to 1.59.3 (package.json, runtime route, layout/page source, lockfiles).
## Summary
- add env-gated CopilotKit Intelligence Threads support to the
`mcp-apps` integration
- move the runtime route to `[[...slug]]` with GET/POST/PATCH/DELETE for
thread REST routes
- wire the Threads drawer + locked gate into the existing MCP apps chat
surface
- align CopilotKit/AG-UI versions and commit npm lockfiles for the app
and Three.js MCP server
- extend the Intelligence migration contract to include `mcp-apps`,
including the app-router path differences
## Verification
- `npm run build` from `examples/integrations/mcp-apps`
- `pnpm exec vitest run
scripts/__tests__/integration-intelligence-migration.test.ts`
- `pnpm exec oxfmt --check
scripts/__tests__/integration-intelligence-migration.test.ts
examples/integrations/mcp-apps/app/page.tsx
examples/integrations/mcp-apps/app/components/threads-drawer/threads-drawer.tsx`
## Licensed smoke
With local Intelligence services from
`/Users/mothra/Projects/test-signups4` and the example `.env` exported:
- `docker compose up -d --wait` reported postgres, redis, and
intelligence healthy
- demo users `1_demo-user` and `demo-user` were seeded/no-op present
- `GET /api/copilotkit/info` returned `mode: intelligence`,
`licenseStatus: valid`, and agent `default`
- `GET /api/copilotkit/threads?agentId=default&limit=20` returned 200
and the Threads drawer rendered persisted threads
- started `npm run dev:mcp` and `next dev --turbopack -p 3024`
- created a new thread, sent “Say hello briefly for the smoke test.”,
`/agent/default/run` returned 200, and the assistant rendered “Hello!”
- after restarting the dev servers, selected the persisted “Quick
Greetings for Testing” thread; the prior user prompt and assistant
response restored, with `/agent/default/connect` returning 200
## Notes
- `3000` was occupied by another local example, so smoke used `3024` for
the Next UI.
- The local thread list contained older experimental thread names from
previous mcp-apps smoke runs; this PR now clears the client thread id
for “New thread” instead of minting a random UUID, so new thread
creation/replay works through the runtime.
Post-merge fix: add the missing examples/integrations/mcp-apps/.env.example
(+ .gitignore negation, crewai-flows precedent) — the contract test
'mcp-apps documents the local Intelligence environment' was failing
because the file was never added. 37/37 passing on the merged tree.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Rename the registered agent key from each starter's bespoke name
(my_agent / agno_agent / starterAgent / sample_agent) to "default" so the
7 single-agent sidebar starters match the passing langgraph/strands
starters' config exactly: drop the frontend `agent=` prop on <CopilotKit>
(falls back to "default") and update the runtime route registration plus
every agentId reference in page.tsx (ThreadsDrawer,
CopilotChatConfigurationProvider, useAgent/useCoAgent).
The functional `useSingleEndpoint={false}` fix that makes starter chat
reach the agent already landed on main; this change brings the agent-key
config in line with the passing set. mastra is intentionally left on its
framework-derived key (MastraAgent.getLocalAgents) — its keys are not
literals and cannot be forced to "default" without diverging from Mastra.
Verified locally via agno docker-compose.test.yml smoke (aimock): @chat
round-trip passes (assistant streams in ~1.0s) with the standardized
"default" key; removing useSingleEndpoint={false} reproduces the documented
404 / "no assistant response" failure (chat degrades to ~1.1m, @interaction
fails on single-endpoint 404s).
Conflict resolution: take main's 4-entry migratedIntegrations array and
keep the a2a-middleware-specific contract tests + helper (a2a-middleware
uses app/ root + custom chat, so it doesn't fit the parameterized
src/app contract). 31/31 passing.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Conflict + post-merge resolutions:
- integration test (add/add): fold into the parameterized batch-2 contract
test; migratedIntegrations now includes langgraph-fastapi (24/24 pass).
- _parity/manifest.json: keep her langgraph-fastapi allowance removals
(threads-drawer/page.tsx/next.config now fully tracked), but drop the
stale strands-python shielding her branch added (example-layout +
docker-route-override divergence, @copilotkit 1.56.5 packageJsonOverrides)
— strands is already parity-synced at 1.59.1 on main; those overrides
would have made the next parity:sync rewrite it back to 1.56.5.
- parity verify on the merged tree: langgraph-js 82 ok / langgraph-fastapi
91 ok / strands-python 83 ok, zero drift.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Conflict resolutions:
- page.tsx: keep the threads layout; swap the dead v1 sidebar labels
(title/initial) for the v2 keys (modalHeaderTitle 'Popup Assistant' +
welcomeMessageText) the starter smoke asserts, and carry over main's
disableSystemMessage + clickOutsideToClose. Keep her useRenderTool
render({ parameters }) — that is the actual v2 RenderToolProps shape;
main's render({ args }) was a latent runtime bug (args is not a prop).
- package.json: keep the drawer UI deps (class-variance-authority, clsx).
- integration test: fold into the parameterized batch-2 contract test;
migratedIntegrations now crewai-flows + llamaindex + pydantic-ai (18/18).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Conflict resolutions:
- page.tsx: keep the threads layout (drawer + gate + provider) and restore
the v2 sidebar labels (modalHeaderTitle 'Popup Assistant' +
welcomeMessageText) the starter smoke asserts, plus clickOutsideToClose.
- layout.tsx: keep the REST-transport explainer comment.
- integration test: keep the parameterized batch-2 contract test from
crewai-flows and add llamaindex to migratedIntegrations (12/12 pass).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
labels.title/initial are dead v1 keys in the v2 CopilotSidebar — the header
rendered the default 'CopilotKit Chat' instead of 'Popup Assistant' and the
greeting never showed. Map to the v2 CopilotChatLabels keys
(modalHeaderTitle / welcomeMessageText), matching every other migrated
starter.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Brings in the base-branch fixes (main merge, v2 label keys, parity sync,
starter heals) so this PR's CI reflects its own change rather than the
pre-fix base. No conflicts.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Same dead-v1-labels bug as the batch-1 starters: labels.title/initial are
ignored by the v2 CopilotSidebar, so the header rendered the default
'CopilotKit Chat' and the starter smoke's text=Popup Assistant wait timed
out (crewai-crews @interaction). Map to the v2 keys (modalHeaderTitle /
welcomeMessageText) in the two v2-migrated starters that were missed in the
earlier pass.
Verified with the exact CI compose for crewai-crews: 4 passed, exit 0.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
These three starters were migrated to the v2 API surface (23af69041c, already
on main) but never got the matching @copilotkit version bump or provider
config, so their starter smoke is red ON MAIN today (main's latest run is red
for 9 starters) — not a regression from this PR. Healing them here to green
the required check:
- bump @copilotkit/react-core + runtime to 1.59.1 (the v2 pages don't work
against the 1.55.2 pair — same failure mastra had pre-bump; runs 404/hang)
- add useSingleEndpoint={false} to the CopilotKit provider, matching every
batch-1 example: without it the v2 client's endpoint-detection probe GETs
the bare /api/copilotkit, which 404s on the multi-route endpoint and trips
the smoke's zero-console-errors assertion
Verified with the exact CI command (docker compose -f docker-compose.test.yml
up --exit-code-from tests) for llamaindex: 4 passed, exit 0.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Addresses the blocking review on #5151:
1. Starter smoke 'Popup Assistant' timeouts (adk, agno, mastra,
ms-agent-framework-python/dotnet): the pages passed the dead v1 label keys
(labels.title / labels.initial), which v2 CopilotSidebar ignores — the
header rendered the default 'CopilotKit Chat' so the smoke's
text=Popup Assistant wait timed out. Map to the v2 CopilotChatLabels keys:
title -> modalHeaderTitle, initial -> welcomeMessageText. Verified live:
SSR now renders 'Popup Assistant'.
2. llamaindex TypeError (reading 'proverbs'): the page still used the v1
useAgent API ({ state, setState } = useAgent({ name, initialState })) —
v2 returns { agent }, so state was undefined at render. Migrate to the v2
pattern (agent.state with a guarded default + agent.setState + one-time
seed effect), and fix its dead v1 label keys too. Verified: next build
prerenders all pages cleanly.
3. parity-check drift: ran _parity/sync.ts --all — syncs example-layout
(mobile-header fix), layout.tsx, docker-route-override.ts to the
north-star, and bumps @copilotkit/* to 1.59.1 in langgraph-fastapi and
strands-python. parity verify: 0 errors across all instances.
(next-env.d.ts is gitignored repo-wide; verify warns-and-skips it in a
clean checkout, so it is intentionally not committed.)
4. Trailing-whitespace diff-check failure (showcase google-adk agent): already
resolved by the merge of main (the file matches main; diff --check clean).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Resolves 5 conflicts from main's e793257650 (v2 frontend tool parameters
array -> Zod) overlapping the threads-wired examples:
- adk/mastra/ms-agent-framework-{dotnet,python} page.tsx: keep the branch
versions — they already use Zod parameters and add the threads drawer
wiring + the reviewed v2 restructure on top of what main converted.
- adk/package.json: union — keep the branch's threads-drawer deps +
@copilotkit 1.59.1 bump, and take main's zod dependency (which our adk
page imports but the branch never declared — main's line fixes that gap).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The langgraph-js agent `dev` script ran `npx @langchain/langgraph-cli@1.2.1`,
which resolves its own isolated dependency tree. That tree pulled a 1.2.x
`@langchain/langgraph` to satisfy the `@langchain/langgraph-api` peer
dependency, but the API hard-imports `STREAM_EVENTS_V3_MODES` from
`@langchain/langgraph/web` — a symbol only present in langgraph 1.3.0+ —
crashing the agent at startup with a SyntaxError.
Install `@langchain/langgraph-cli@1.2.4` as a devDependency and invoke the
local `langgraphjs` binary so the `@langchain/langgraph` peer resolves from
the agent's own pinned 1.3.0, which exports the symbol. Verified the agent
boots cleanly (graph registered, API on :8123, no SyntaxError).
The v1→v2 migration left tool `parameters` in the old v1 array shape
(`[{ name, type, description, required }]`), which does not satisfy the
v2 `FrontendTool.parameters?: StandardSchemaV1` contract. This produced a
`Property '"~standard"' is missing` TypeScript error, failing the
Next.js build for starters whose Docker smoke build typechecks (mastra,
ms-agent-framework-python, adk).
Convert each tool's parameters to a `z.object({...})` schema so typed
`args`/handler arguments resolve correctly. Add `zod` as a dependency to
the two starters (adk, a2a-middleware) that lacked it.
Affected starters: adk, agno, llamaindex, mastra, pydantic-ai,
ms-agent-framework-dotnet, ms-agent-framework-python, a2a-middleware.
The .NET example's page.tsx pointed its Shared State and Generative UI doc
links at /pydantic-ai/ (copy-paste leftovers) instead of
/microsoft-agent-framework/. Also fix the threads-drawer CSS header comment
that still referenced 'mastra's CopilotSidebar'.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The no-license locked panel is a fixed-width (w-80 / 18-20rem) block. In the
single-column mobile grid it left a dead background strip beside it and pushed
the app content down. Hide it below 1024px (max-lg:hidden / .lockedPanel
display:none) — consistent with the real drawer + first-paint placeholder,
which also reserve no column on mobile. Content now gets the full width.
Applied across all 7 migrated examples.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
On the no-license locked threads panel:
- widen the panel slightly (w-72 -> w-80 / lockedPanel 18rem -> 20rem) and
add white-space: nowrap so `copilotkit add-intelligence` stays on one line
instead of wrapping mid-command
- add a 'with:' lead-in above the command box so it reads as a runnable command
rather than loose text
Applied across all 7 migrated examples (Card-based locked state in adk/agno/
langgraph-js/langgraph-python; themed .lockedPanel in mastra/ms-agent-*).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The disabled-state ThreadsPanelGate (shown when no Intelligence license is
present) rendered its locked card in a bare `w-72` container with no
background, so the threads column showed the page background (a black column in
dark-themed examples, white in light) instead of the drawer surface.
Give that container the drawer surface (bg + hairline right border) so the
locked card sits in a panel that matches the drawer, consistent with the
already-surfaced .lockedPanel examples (mastra, ms-agent-framework-*).
Affects adk, agno, langgraph-js, langgraph-python (the Card-based locked state).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The ThreadsPanelGate renders a first-paint placeholder while the client-only
drawer mounts. It was either a bare `w-72` div (no surface → a black/white
column flash in the page bg) or a fixed 18rem inline-styled div (correct color
but, on mobile where the mounted drawer floats, the reserved 18rem collapsed on
mount → content shifted left).
Replace both with a shared `.drawerPlaceholder` class that matches the open
drawer's footprint + surface (18rem, drawer bg, hairline border) on desktop and
`display: none` below 1024px (the mobile drawer floats, so reserve no column).
Result: no color flash and no content shift on load. Applied across all 7
migrated examples (themed vs raw surface tokens per example).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Port the langgraph-python mobile-header fix to langgraph-js (same shared
canvas/header demo). Below 1024px the threads drawer's floating launcher is
fixed top-left and collided with the top-left CopilotKit header:
- max-lg:pl-24 on the header so the logo clears the launcher pill
- max-lg:pt-2.5 + pb-0 (and drop the logo span's pb-1.5 on mobile) so the
logo is vertically centered with the launcher + the Chat/App toggle
- trim the collapsed launcher's icon buttons (2rem -> 1.75rem) + tighter
padding so the pill height lines up with the toggle
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Jordan Ritter