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>
## Summary
- add env-gated CopilotKitIntelligence runtime wiring to
langgraph-fastapi while preserving the FastAPI-specific
LangGraphHttpAgent path
- add the shared Threads drawer/locked panel UI and threadId wiring for
the canvas/chat demo
- bump langgraph-fastapi CopilotKit deps to 1.59.1, add its
package-lock, and document local Intelligence env vars
- remove the temporary langgraph-fastapi parity allowances for
now-verbatim Threads/page/next files
- add a focused batch-2 migration contract test for langgraph-fastapi
## Verification
- confirmed the new migration test failed before implementation
- pnpm exec vitest run
scripts/__tests__/integration-intelligence-migration.test.ts
- pnpm parity:verify --target=langgraph-fastapi (90 ok, 1 existing
next-env.d.ts warning, 0 errors)
- npm run build (in examples/integrations/langgraph-fastapi)
- pnpm exec oxfmt --check <touched TS/TSX/JSON files>
- git diff --check
- commit hook: check-binaries, sync-lockfile, lint-fix,
test-and-check-packages, commitlint
- manual licensed Threads smoke test with local Intelligence composite:
- copied /Users/mothra/Projects/test-signups4/.env into the example .env
and supplied a valid local OPENAI_API_KEY
- docker compose up -d --wait from /Users/mothra/Projects/test-signups4
- seeded demo-user / 1_demo-user in cpki.users
- started dev with exported .env: set -a; . ./.env; set +a; npm run dev
- /api/copilotkit/info returned mode=intelligence, licenseStatus=valid,
version=1.59.1
- /api/copilotkit/threads?agentId=default returned 200
- licensed Threads UI visible
- selected/restored persisted thread
- created a fresh thread, sent a todo request, agent response rendered,
todo state updated
- refreshed and selected the named thread again; chat history, tool
calls, assistant response, and todo state restored
## Notes
- Targets the PR #5151 lineage branch because batch-2 depends on the
Intelligence foundation from ENT-679.
- The first manual smoke attempt failed because the copied local env had
an empty OPENAI_API_KEY; after replacing it in the ignored example .env
and restarting, the fresh smoke passed.
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>
## Summary
- migrate the pydantic-ai example to the Intelligence-ready v2
CopilotKit setup
- add the shared Threads drawer with REST transport, env-gated
Intelligence runtime, and local env docs
- pin the example to CopilotKit 1.59.1 and add a migration contract test
## Verification
- pnpm exec vitest run
scripts/__tests__/integration-intelligence-migration.test.ts
- pnpm exec oxfmt --check
scripts/__tests__/integration-intelligence-migration.test.ts
examples/integrations/pydantic-ai/src/app/page.tsx
- git diff --check
- npm run build (examples/integrations/pydantic-ai)
- pre-commit hook: package tests plus publint/attw passed
- manual smoke: started local pydantic-ai app with Intelligence env,
loaded http://localhost:3000, verified Threads drawer, sent Read Agent
State, selected persisted thread, and confirmed the
prompt/tool/assistant exchange hydrated from the thread
## Notes
- Targets ben1/ent-679-intelligence-ready-north-star to stack on the PR
5151 Intelligence-ready baseline.
- The local smoke logs include a non-fatal initial THREAD_NOT_FOUND
lookup for a newly minted thread before it is created; the thread is
then created, listed, and hydrates successfully.
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>
## Summary
- Migrates the LlamaIndex example onto the Intelligence/Threads path
from the PR 5151 golden pattern.
- Pins the example to CopilotKit `1.59.1`, switches to the v2
chat/runtime wiring, and adds the shared mobile floating Threads drawer
experience.
- Adds optional Intelligence env wiring with an in-memory fallback when
no license token is configured.
- Adds a contract test covering the LlamaIndex migration surface so
future example migrations can stay red/green.
## Verification
- `pnpm exec vitest run
scripts/__tests__/integration-intelligence-migration.test.ts`
- `pnpm exec oxfmt --check
examples/integrations/llamaindex/src/app/page.tsx
examples/integrations/llamaindex/src/app/layout.tsx
examples/integrations/llamaindex/src/app/api/copilotkit/[[...slug]]/route.ts
examples/integrations/llamaindex/src/components/threads-drawer
examples/integrations/llamaindex/src/components/ui
examples/integrations/llamaindex/src/lib/utils.ts
scripts/__tests__/integration-intelligence-migration.test.ts`
- `git diff --check`
- `npm run build` from `examples/integrations/llamaindex`
- Pre-commit `test-and-check-packages` passed on commit.
## Manual smoke
- Started local Intelligence stack and LlamaIndex example with licensed
env.
- Confirmed Threads drawer loads via `/api/copilotkit/threads` and
persisted threads render/select correctly.
- Verified a backend-tool conversation: “Get the weather in San
Francisco.” created/named a persisted thread, rendered the weather card,
and hydrated correctly after refresh/reselect.
## Notes
- Observed the same non-fatal initial `THREAD_NOT_FOUND` lookup pattern
before thread creation that appears in other migrated examples.
- The LlamaIndex frontend-tool path (`add_proverb`) exposes an
adapter-specific streamed tool-argument issue where two JSON argument
payloads arrive concatenated. I did not address that in this migration;
the backend-tool path and Threads persistence smoke cleanly.
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>
Render the `a2ui_recovery` activity the middleware emits — as a pure DATA
CONTRACT, no @ag-ui/a2ui-toolkit dependency on the React client (mirrors how
a2ui-surface / a2ui_operations are consumed by activityType + content keys):
- createA2UIRecoveryRenderer() -> ReactActivityMessageRenderer for
activityType "a2ui_recovery":
- "retrying": a non-disruptive, collapsed "Retrying UI generation…" hint that
only appears once perceptible (after showAfterMs, or once attempts cross
showAfterAttempts) so a fast first retry never flashes; never replaces the
surface, never shows noisy errors inline.
- "failed": a clean, tasteful hard-failure message for end users, with the
structured developer detail tucked into an expandable <details>.
- "resolved"/unknown: renders nothing (the surface renderer owns the UI).
- Timing + debugExposure are client-configurable (A2UIRecoveryRendererOptions),
surfaced via CopilotKitProvider's `a2ui.recovery`.
- Registered as a built-in renderer when runtime A2UI is enabled; exported.
7 renderer unit tests green (jsdom).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Quick-win fixes for the **Build with agents** page from Sam's review.
Stacked on #5187 (retarget to `main` once it lands).
## Changes
- **Skills now shown on every page** — previously only the top-level
`/build-with-agents` (and `built-in-agent`) rendered the Skills section;
every framework integration page used the MCP-only snippet, hiding
Skills. The shared `coding-agents.mdx` now renders the full Skills + MCP
guide, so all 11 build-with-agents pages show Skills (the recommended
path).
- **Skills section** — added a top-three table (`copilotkit-setup`,
`copilotkit-develop`, `copilotkit-integrations`) and a note that
`copilotkit-contribute` is for contributing to CopilotKit, not building
with it.
- **Install step** — clarified to run `npx skills add` from the project
root; any agent there (Claude Code, Codex, Cursor, Gemini CLI) discovers
the skills automatically.
- **MCP headings** — demoted per-tool headers (Cursor, Claude Code, …)
from H2 → H3 so they nest under "MCP Docs Server" in the TOC; "Other"
subsections H3 → H4.
## Screenshots
Skills section + top-three table:
Install step:
Skills now rendering on a framework page (Mastra) that was previously
MCP-only:
TOC nesting (tools now under MCP Docs Server):
## Files
-
`showcase/shell-docs/src/content/snippets/shared/guides/build-with-agents.mdx`
-
`showcase/shell-docs/src/content/snippets/shared/guides/mcp-server-setup.mdx`
- `showcase/shell-docs/src/content/snippets/shared/coding-agents.mdx`
-
`showcase/shell-docs/src/content/docs/integrations/langgraph/build-with-agents.mdx`
## Summary
- add env-gated CopilotKitIntelligence runtime wiring to crewai-flows
- add Threads drawer/locked panel UI and shared threadId wiring for the
CopilotSidebar demo
- bump crewai-flows CopilotKit deps to 1.59.1 and add local Intelligence
env docs
- add a focused batch-2 migration contract test for crewai-flows
- fix two manual-smoke regressions found during the licensed Threads
pass: stale sidebar props and circular frontend-tool deps
## Verification
- confirmed the new migration test failed before implementation
- pnpm exec vitest run
scripts/__tests__/integration-intelligence-migration.test.ts
- npm run build (in examples/integrations/crewai-flows)
- pnpm exec oxfmt --check <touched files>
- git diff --check
- commit hook: check-binaries, sync-lockfile, lint-fix,
test-and-check-packages, commitlint
- manual licensed Threads smoke test with local Intelligence composite:
- Threads licensed UI loads and thread list returns 200
- creating/selecting a thread no longer crashes
- suggestion message runs through the CrewAI agent with a valid OpenAI
key
- agent response renders in chat
- persisted thread appears in the drawer and receives an updated title
## Notes
- Targets the PR #5151 lineage branch because batch-2 depends on the
Intelligence foundation from ENT-679.
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>
## What
Two unrelated cleanups:
### 1. Move internal-only skills out of the public repo
Three staff-only skills lived under `.claude/skills/` and
`.agents/skills/`, so `npx skills add CopilotKit/CopilotKit` swept them
into end-user installs. This PR deletes them here; they now live in the
internal-skills plugin (**CopilotKit/internal-skills#108**):
- `copilotkit-demo-parity`
- `git-hooks`
- `showcase-demo-debugging`
### 2. Recommend a cleaner skills install command
The **Build with agents** guide now recommends:
```bash
npx skills add CopilotKit/CopilotKit/skills -y
```
- `/skills` subpath installs only the published skills under `skills/`
(the repo root also picks up internal skills).
- `-y` skips the interactive prompts.
A Callout documents the interactive variant and `-g` for a global
install.
On consecutive interrupts, pressing Enter for the second turn (turn-2) while
the resumed run from turn-1 was still in flight routed the keystroke to the
STOP action, aborting the in-flight resume instead of sending the new message.
The fix gates the Enter handler on `canSend` so a pending/running state no
longer maps Enter to STOP, and `onSubmitInput` now awaits the in-flight run's
completion before dispatching the queued message — the message is sent after
the current run finishes rather than aborting it.
Also hardens the queuing and attachment tests to cover the consecutive-
interrupt path and the send-after-run-completes behavior.
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>
the per-service promote loop ran under `set -euo pipefail`, so the first failing
service aborted the whole `all` fleet promote; extracted to promote-fleet.sh
which attempts every service, accumulates succeeded/failed sets, exits non-zero
only after attempting all, and exports succeeded_csv. verify-prod now runs
`if: !cancelled()` and scopes --services to the succeeded set; the staging
precondition is advisory (promote runs even when it reports red — bin/railway
enforces staging-green per-service); notify success keys on PROMOTE && PROD.
Adds a shell-script-tests CI job (bats + shellcheck) and input-validation
hardening (fail-loud on empty/all-empty CSV, RAILWAY_BIN check, whitespace trim).
`from __future__ import annotations` turned the set_steps tool's
`context_variables: ContextVariables` param into an unresolved ForwardRef at
AG2 tool-schema-generation time, raising PydanticUserError on import and failing
the showcase-ag2 staging healthcheck since 2026-05-31. Removing it matches the
working sibling agents. Adds a regression test that statically asserts the
future-import stays absent (version-independent) plus a live import check.
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>
Previously only the top-level /build-with-agents and built-in-agent pages
rendered the Skills section (via <BuildWithAgents />). Every framework
integration page used the MCP-only <CodingAgents /> snippet (or, for
langgraph, <MCPSetup /> directly), so Skills — the recommended path — was
hidden there.
Point the shared coding-agents.mdx snippet at <BuildWithAgents /> so all
pages that reference CodingAgents now render Skills + MCP, and switch the
langgraph page from <MCPSetup /> to <BuildWithAgents />. The snippet inliner
recurses with cycle protection, so no duplication is needed.
## Summary
Two body links on the **Self-Hosting Intelligence** page
(`/<framework>/premium/self-hosting`, rendered from the shared snippet
`docs/snippets/shared/premium/self-hosting.mdx`) were broken in
production:
- **"How the Intelligence Platform Works"** (Prerequisites + Next steps)
linked `/learn/intelligence-platform`. The `NavigationLink` rewriter
(`docs/components/react/subdocs-menu.tsx`) makes absolute links
section-relative, so under each framework it became
`/<framework>/learn/intelligence-platform` → **404**. The page is served
at `/premium/intelligence-platform` in every section (verified live
across built-in-agent, langgraph, mastra, crewai, agno, and root).
Changed both occurrences to `/premium/intelligence-platform`, matching
the sibling premium links (`/premium/overview`).
- **"chart releases" (GHCR)** used the repo-scoped package URL for the
private `CopilotKit/Intelligence` repo → **404** for public readers.
Switched to the public org-scoped package URL
`github.com/orgs/CopilotKit/packages/container/package/charts%2Fintelligence`
(200). The `oci://ghcr.io/...` pull itself was already fine — only the
web link was broken.
The other two body links (`/premium/overview`, `/threads`) and all
in-page anchors were already valid.
## Why this shipped broken
`scripts/check-broken-links.js` only scans `content/docs` and
`components` — it never looks at `snippets/`, so links in shared
snippets are completely unvalidated. Extending the checker to cover
`snippets/` (and to model the section-relative rewriting) would catch
this class of bug. Not included here to keep this PR focused — happy to
follow up.
## Test plan
- [x] `/built-in-agent/premium/intelligence-platform` returns 200
(verified across built-in-agent, langgraph, mastra, crewai, agno, and
root prefixes)
- [x] Org-scoped GHCR package URL returns 200
- [x] Pre-commit hooks pass (`test-and-check-packages`, `commitlint`)
- [ ] Confirm on docs preview deploy that both links resolve from the
rendered page
The shared self-hosting snippet renders under every framework section
(built-in-agent, langgraph, ...), and the NavigationLink rewriter makes
absolute links section-relative.
- "Intelligence Platform Works" linked /learn/intelligence-platform,
which became /<framework>/learn/intelligence-platform (404). The page
is served at /premium/intelligence-platform in every section.
- The GHCR chart-releases link used the repo-scoped URL for the private
Intelligence repo (404 for public readers); switched to the public
org-scoped package URL.
Addresses review feedback on the Build with agents page:
- Add a top-three skills table (copilotkit-setup / -develop / -integrations)
and call out that copilotkit-contribute is for working on CopilotKit
itself, not building with it, so the skills directory's build-vs-contribute
split is clear from the docs page.
- Clarify where to run `npx skills add`: from the project root, where any
coding agent (Claude Code, Codex, Cursor, Gemini CLI) discovers the skills
automatically — answering 'in your agent environment'.
- Demote the MCP per-tool section headers (Cursor, Claude Web, Claude Code,
...) from H2 to H3 so they nest under 'MCP Docs Server' in the on-this-page
TOC instead of sitting as flat siblings; demote the 'Other' subsections to
H4 accordingly.
The static/quality format job runs in check mode on push and was failing
on main: `ruff format --check .` flagged 5 unformatted Python files under
examples/showcases/a2ui-pdf-analyst/agent (main.py, src/dynamic_agent.py,
src/fixed_agent.py, src/multimodal_middleware.py, src/pdf_tools.py). The
oxfmt JS/TS check already passes, so this is ruff-only drift. Applied
`ruff format` (pinned 0.15.13, matching CI); diff is formatting-only.
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 starter smoke-test Slack alert had no indication of where it came
from, which is ambiguous when the same workflow runs across multiple
repos (e.g. the public CopilotKit/CopilotKit repo vs the internal
testybara fork). Prepend a `[ci:<owner/repo>]` tag derived from
github.repository so triage is unambiguous about the source. These CI
alerts test example source and carry no staging/production dimension,
so [ci] is the meaningful source axis. Existing message format is
otherwise preserved.
Prefix every harness-dispatched alert with a `[staging]`/`[production]`/
`[unknown]` source-env tag so operators triaging a red probe know which
deploy environment is affected. The label is derived in the orchestrator
from SHOWCASE_ENV ?? RAILWAY_ENVIRONMENT_NAME ?? "unknown" and applied at
the single renderer chokepoint (covering per-key, cron, and on-error
dispatch) plus the aggregation flush path that bypasses the renderer, via
a shared sourceEnvPrefix helper so the two paths never drift. A missing
env var surfaces as a visible [unknown] rather than a silent un-prefixed
alert.
Benjamin Taylor
