The migration note said only that `args` is partial while `status` is
"inProgress", with no before side. Read as a migration instruction it
implied the opposite of the real change: the old RN `RenderToolProps`
declared `args: T` (never partial) and `status: "executing" | "complete"`,
so the change ADDS an "inProgress" state in which `args` is `Partial<T>`
rather than narrowing a partiality that already existed.
Spell out old -> new for `status`, `args` and `result`, and name
"inProgress" as a newly-introduced status value.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The "Rendering a tool call outside the chat" snippet called the hook at
module top level, had a `return` at module scope (a syntax error), and
referenced an undefined `toolCalls` binding, so it could not be pasted.
Wrap it in a real component, source the tool calls from `useAgent()`'s
message list, and correlate each call with its tool-result message the way
the prebuilt RN chat does — without `toolMessage`, `status` stays
"inProgress" and `result` is `undefined` forever.
Hooks bypassed: this worktree has no node_modules, so the commitlint
commit-msg hook cannot resolve its binary. Subject follows the convention.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The useRenderTool page's Usage example compared `status` to the string
literal `"executing"`. `status` is typed as the `ToolCallStatus` enum
member union (`ReactToolCallRenderer["render"]` in react-core, which RN's
`RenderToolProps` derives from), so that comparison is TS2367 — the
snippet as printed does not compile.
Compare against `ToolCallStatus.Executing` and import the enum in the
snippet so the example is genuinely compilable.
Depends on `ToolCallStatus` being re-exported as a runtime VALUE from
packages/react-native/src/headless.ts (it currently sits inside an
`export type { … }` block, which strips the enum value). That export fix
is a separate change; both must land together for this snippet's import
to resolve.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The primary Usage example on the useRenderTool reference page never imported
CopilotChat, and the barrel specifier it implied resolves to the headless
component (packages/react-native/src/CopilotChat.tsx), which returns a bare
context provider around {children} and paints no message list. The page's
headline example therefore rendered nothing at all.
Import CopilotChat from @copilotkit/react-native/components -- the prebuilt UI
that calls useRenderToolCall and renders tool calls inline -- and state the
subpath requirement under the block so the distinction is not silent.
agentName is kept: it is the current, non-deprecated prop on the /components
chat (the deprecation and dev console.warn live on the headless component's
agentName), and it matches the prebuilt-UI usage on the CopilotChat page.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The deps guidance told readers that a render closure over changing values
is fixed by listing those values in deps. That remedy is inert for the
value types most likely to appear in a render closure.
react-core's useFrontendTool compares deps by serializing the whole array
(packages/react-core/src/v2/hooks/use-frontend-tool.tsx:45, via
JSON.stringify(extraDeps)), not by reference identity like useEffect. In
an array a function or symbol serializes to null, and a Map, a Set, or a
class instance holding state in private fields serializes to {} -- the
same string forever, so such a dep never re-registers the tool. A
circular dep additionally throws while the hook renders.
State the comparator's actual semantics, name the three consequences
(inert non-serializable deps, circular deps throwing, key order
counting), and document what does work: a primitive derived from the
changing value, or a ref the captured render dereferences at call time.
Docs-only. Core's comparator is deliberately unchanged -- it is shared by
every platform and is out of scope for this finding.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The documented signature dropped the hook's generic constraint and default
(`T extends Record<string, unknown> = Record<string, unknown>`) and rendered the
required `options` argument as optional.
The render-prop semantics were wrong in two ways verified against the types:
`args` is not "fully parsed" on the executing/complete arms — every arm receives
the same `partialJSONParse` of the raw argument string and the `parameters`
schema is never applied before `render`, so widening `Partial<T>` to `T` is a
type-level assertion only. And `result` is the tool result message's `content`
correlated by `toolCallId`, not the handler's return value: the complete arm is
selected because that message exists, handler returns arrive serialized
(`undefined`/`null` -> `""`, else `JSON.stringify`), a thrown handler yields the
string `Error: <message>`, a render-only tool completes with `""`, and on reload
the value replays from stored history.
Also document that the RN entry's re-exported `RenderToolInProgressProps` /
`RenderToolExecutingProps` / `RenderToolCompleteProps` are NOT arms of RN's
`RenderToolProps<T>`: they are schema-generic, `parameters`-shaped arms of
react-core's own union for the web hook. They sit next to `RenderToolProps` on
the public barrel, so the resemblance is a real trap worth naming.
Commit hook note: the commit-msg commitlint hook cannot run in this worktree
(no node_modules, `commitlint` binary unresolvable), so the message was
validated by hand against commitlint.config.js — conventional type+scope,
77-char header under the 120 limit, blank-line-separated body and footer.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Final review fix wave for the RN render-tool convergence branch.
Substantive:
- Extend packages/react-core/scripts/assert-headless-purity.mjs to also scan the
built /v2/context chunk (context.mjs/context.cjs), not just /v2/headless.
/v2/context carries CopilotKitCoreReact and is imported by react-native, so a
future shiki/mermaid/katex leak through it would bloat RN bundles (#4893) while
neither hard-fail guard fired. Comment and failure message updated to name both
RN-reachable entries. Mutation-verified against context.mjs.
- Document the closure-staleness convergence: render is now captured at
registration (passed into useFrontendTool) and only refreshed when deps change,
no longer re-read every render. Consumers whose render closes over changing
state must now pass deps. Documented in the useRenderTool JSDoc, the
useRenderTool.mdx reference, and the changeset migration notes.
Minor sweep:
- CopilotChat extraData now lists what renderItem actually reads
({ isRunning, renderToolCall, toolMessages }); drop unused executingToolCallIds.
- headless-type-exports.test-d.ts imports React explicitly instead of relying on
the ambient UMD global.
- useRenderTool.mdx migration heading no longer names the uncut 1.67.0 version.
- Changeset marks @copilotkit/react-core minor (new public type export), matching
its body.
Co-Authored-By: Claude <noreply@anthropic.com>
useRenderTool.mdx and CopilotKitProvider.mdx described the removed React
Native render-tool registry as if it still existed. Correct the three
false statements on useRenderTool.mdx (cleanup unregisters the renderer;
RenderToolProvider auto-installed; useRenderToolRegistry live Map) and the
false CopilotKitProvider bullet (wraps children in a RenderToolProvider).
Document useRenderToolCall for rendering on any surface, note that
arguments stream on status "inProgress", and add a migration section for
the removed useRenderToolRegistry. Also fix the stale Callout that listed
useRenderToolCall as not exported on React Native.
Co-Authored-By: Claude <noreply@anthropic.com>
New export from Figma: two runner paths (managed Intelligence runner or
build your own), durable-data emphasis, Any Agent framework list, and
channel platforms with the +4 more row. Used for both themes until a
dark export exists.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Note in the Channels overview and package READMEs that building your own
channel runner on the open-source SDK primitives is a supported path with
no CopilotKit Intelligence dependency; teams choosing it own their state,
persistence, concurrency, locking, retries, and race-condition handling.
Intelligence remains the managed runner, with analytics, learning, and
governance in addition.
Also updates the production self-hosting note: Enterprise Intelligence can
be fully self-hosted today, onboarding guides are still to come.
Refs FAC-155
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
## What does this PR do?
Adds the CopilotKit consumer side of ENT-1173 across Shared, Runtime,
Core, Web Inspector, and the existing Shell Docs pages.
- Defines and parses optional trusted Inspector metadata for identity,
plan, license, action, usage, and expiry. Runtime proxies it through a
private, failure-isolated route, and Core refreshes it without changing
connection state.
- Groups Inspector navigation into Threads, Agents, and Learning.
Threads renders finite, unlimited, unknown, overage, and expiring usage
states plus matching trusted plan or license actions.
- Keeps explicit `threadEndpoints` as the only authority for Thread
requests. Locked or absent capability states make no list, subscription,
detail, message, event, or state calls.
- Keeps the zero-thread video, three example Threads, detail tabs, and
guided tour in empty and locked states. General Intelligence remains the
default onboarding path; only trusted `team_self_hosted` metadata uses
self-hosted onboarding.
- Gives an active license with missing Runtime routes a short **Finish
setting up Rich Threads** state. Users can copy a safe coding-agent
prompt or open the public Runtime setup guide. The same copy control
appears in that guide, and raw Markdown/LLM views include the full
prompt.
- Keeps finite usage green below 90%, orange from 90% to the limit, and
red at or above the limit. At 90%, a trusted plan action changes from
**Manage Your Plan** to a purple **Upgrade Your Plan** without changing
its trusted URL, action kind, or telemetry contract.
- Adds a deterministic 33-state loopback lab for CopilotKit developers.
It has no production route or export, is absent from public docs and
package metadata, and is excluded from the npm tarball.
`Expiring Soon` is display-only; this PR does not enable the thread
culler. Managed Enterprise receives no manage-plan action, and Team
Self-Hosted receives no hosted plan action. Optional metadata and the
additive expiry field remain compatible across mixed producer, Runtime,
Core, and Inspector versions.
A small Channels test-only change updates fetch mocks for current
TypeScript types. It changes no Slack or Teams docs or runtime behavior.
## Related PRs and issues
- Refs
[ENT-1173](https://linear.app/copilotkit/issue/ENT-1173/ship-plg-ready-inspector-navigation-metadata-and-locked-threads)
- Producer:
[CopilotKit/Intelligence#696](https://github.com/CopilotKit/Intelligence/pull/696)
## Validation
- `@copilotkit/web-inspector`: 20 files and 372 tests passed; typecheck
and production build passed.
- Shell Docs: 57 files and 383 tests passed; lint, typecheck, and
production build passed. The build generated all 222 static pages.
- Browser checks cover the copy-prompt flow, unchanged white **Manage
Your Plan**, purple **Upgrade Your Plan**, orange 4,500/5,000 usage, and
red 5,000/5,000 usage.
- Independent review found no Critical or Important issues.
- The broader Runtime, React Native, Channels, package-quality,
compatibility, and Node-version checks from the prior pushed head remain
green.
## Checklist
- [x] I have read the [Contribution
Guide](https://github.com/copilotkit/copilotkit/blob/master/CONTRIBUTING.md)
- [x] I updated the relevant documentation
- [ ] "Allow edits by maintainers" is checked
Fixes#261 (open since March 2024). Supersedes #4622 — @ashish4143
diagnosed the same wrappers and is credited as co-author on the commit.
## The bug
`CopilotSidebar` wraps consumer content in two divs:
- `.copilotKitSidebarContentWrapper` (`Sidebar.tsx`) — only sets
`overflow`, `margin-right`, `transition`
- `.copilotKitModalChildrenWrapper` (`Modal.tsx`) — **has no CSS rule
anywhere in the repo**
Both are auto-height blocks, so a child's `height: 100%` has no definite
containing block to resolve against and collapses to content height.
## The fix
An opt-in `fullHeightChildren` prop on `CopilotSidebar` that adds a
modifier class to the content wrapper. Two deliberate choices, both from
the review on #4622:
- **Opt-in, not default.** The content wrapper wraps the *entire*
consumer app. Making it a fixed-height flex column for everyone would
reflow apps that never asked for it.
- **A viewport unit, not `height: 100%`.** `100%` only resolves if every
ancestor (`html`/`body`/`#root`) also declares a height — react-ui
neither sets that nor can guarantee it, so `100%` would silently no-op
in a stock Next.js app. `min-height: 0` on the children wrapper clears
the flex-item `min-height: auto` floor so tall content scrolls inside
the child rather than stretching the wrapper past the viewport.
```tsx
<CopilotSidebar fullHeightChildren>
<div style={{ height: "100%" }}>...</div>
</CopilotSidebar>
```
## Testing
**Unit** — `packages/react-ui/src/css/sidebar-full-height.test.ts` (4
tests), in the repo's existing CSS-contract style. Guards both halves:
the escape hatch's rules, and that the default wrapper stays
auto-height. Also asserts the height is *not* `100%`, since that's the
regression that would make the whole feature a silent no-op.
```
✓ src/css/sidebar-full-height.test.ts (4 tests)
Test Files 9 passed (9) Tests 58 passed (58) # full react-ui suite
```
`npx tsc --noEmit` → exit 0. `oxlint` on changed files → 0 warnings, 0
errors.
**Live in Chrome** — the acceptance criterion from the #4622 review: a
stock app where **nothing** declares a height on `html`/`body`/`#root`,
loading the real built `dist/index.css` (not the source CSS), standards
mode, 762px viewport. DOM per `Sidebar.tsx:92` + `Modal.tsx:143`.
| case | child `height:100%` measures |
|---|---|
| default (no opt-in) | **17px** — collapsed, i.e. behavior unchanged
for existing consumers |
| `fullHeightChildren` | **762px** — exactly the viewport |
| `fullHeightChildren`, content 3000px tall | **762px**, scrolls inside
the child (`min-height: 0` holds) |
Also confirmed on the opt-in path: `.copilotKitSidebar` stays `position:
fixed`, and the expanded push-aside `margin-right` is still `448px`
(28rem), so the sidebar's own layout is untouched.
**Docs** — `CopilotSidebar.mdx` is auto-generated from `Sidebar.tsx`;
regenerated via `scripts/docs/gen.ts` and committed only the new
`fullHeightChildren` entry (the generator also surfaces unrelated
pre-existing drift in other reference pages, left out of this PR).
## Not covered
The issue mentions a "works in Safari, not Chrome" symptom. I verified
in Chromium only — the mechanism above is spec behavior rather than a
Chrome quirk, but I haven't measured WebKit.
Fixes#5961 (OSS-609).
## The bug
Both LangGraph auth pages told self-hosted readers to wrap their graph
in `CopilotKitRemoteEndpoint`. That path is retired and fails two ways
against the stack the reporter used (`copilotkit==0.1.94`,
`ag-ui-langgraph==0.0.4x`, Python 3.12):
```
import LangGraphAgent -> ImportError: cannot import name 'LangGraphAgent' from 'copilotkit'
execute_agent -> AgentExecutionException: Agent 'sample_agent' failed to execute:
'LangGraphAGUIAgent' object has no attribute 'execute'
```
(Reproduced locally against the `langgraph-fastapi` example's venv —
output above is verbatim.)
## The fix
`showcase/shell-docs/src/content/docs/auth.mdx` (Self-hosted tab of the
`auth_pattern: langgraph` section) and
`showcase/shell-docs/src/content/docs/integrations/langgraph/auth.mdx`
now document the supported pattern: **serve the AG-UI endpoint
yourself**, validate in a FastAPI dependency (401 before the graph
runs), and bake the resolved user into a **per-request**
`LangGraphAGUIAgent(config={"configurable": {"auth_user": user}})` so
nodes read an already-verified identity off `RunnableConfig` — no raw
token in the graph, no shared agent carrying another request's identity.
The gate-only variant (`FastAPI(dependencies=[Depends(current_user)])` +
`add_langgraph_fastapi_endpoint`) is documented for readers who only
want unauthenticated traffic rejected.
Two adjacent bugs on the same pages, fixed here because they break the
same walkthrough:
- **The frontend channel was wrong.** The pages said to pass
`properties={{ authorization: userToken }}` and claimed it "is forwarded
as a Bearer token". Nothing in `packages/` converts properties into
headers — `properties` reach the agent as AG-UI `forwardedProps` (run
payload data). The v2 runtime *does* forward the inbound `authorization`
header (and custom `x-*`) onto the agent call, so `headers={{
Authorization: ... }}` is the channel that actually works, for both
Platform and self-hosted.
- **The Platform user key was wrong.**
`config["configuration"]["langgraph_auth_user"]` →
`config["configurable"]["langgraph_auth_user"]` (matches
`langgraph/pregel/main.py` and `langgraph_api/worker.py`).
## Testing
**1. Doc snippets extracted verbatim from the MDX and executed** (a
script pulls the `main.py` + node code blocks out of each page, stubs
only `validate_your_token`, and drives them with `TestClient`; run under
the `examples/integrations/langgraph-fastapi` venv — `copilotkit
0.1.94`, `ag-ui-langgraph 0.0.41`, Python 3.12):
```
# docs/auth.mdx
PASS no header -> 401 {"detail":"Missing bearer token"}
PASS bad token -> 401 {"detail":"Invalid token"}
PASS valid token -> 200
PASS no RUN_ERROR
PASS node read user_123 off RunnableConfig
PASS node read role 'member'
PASS run completed
MESSAGES_SNAPSHOT: [{"id": "None", "role": "assistant", "content": "hello user_123"}]
ALL DOC-SNIPPET CHECKS PASSED
# docs/integrations/langgraph/auth.mdx — same script, same 7 checks
ALL DOC-SNIPPET CHECKS PASSED
```
**2. Gate-only variant**
(`FastAPI(dependencies=[Depends(current_user)])` + stock
`add_langgraph_fastapi_endpoint`):
```
no token -> 401 {"detail":"Missing bearer token"}
valid token -> 200 True True
PASS gate-only pattern (401 without token, run proceeds with token; identity NOT injected)
```
The trailing `True True` is `RUN_FINISHED` present **and** the node
seeing `nobody` — i.e. the gate works but no identity lands on the
config, exactly as the docs now say.
**3. Header forwarding actually reaches a LangGraph deployment** — the
claim behind the new `headers` guidance. Pointed a real
`@ag-ui/langgraph` `LangGraphAgent` at a local stub server, set
`agent.headers` the way `configureAgentForRequest` does, and recorded
what arrived:
```
[ { "url": "/assistants/search", "auth": "Bearer end-user-token", "apiKey": "server-side-key" } ]
PASS: authorization forwarded to the deployment
```
Both the end-user token and the server-side key arrive, which is why the
"server-configured headers win on collision" note is accurate.
Runtime-side breadth is already covered by
`packages/runtime/src/v2/runtime/__tests__/agent-utils-header-forwarding.test.ts`
("authorization header IS forwarded").
**4. Docs render checks** — both pages compile as MDX (`@mdx-js/mdx`
`compile()`), and every `python` block on both pages parses
(`ast.parse`), including the ones I didn't touch.
## Follow-up
**The DIY endpoint is deliberate but temporary.**
`add_langgraph_fastapi_endpoint` exposes no per-request seam (no
`dependencies` passthrough, no config/agent factory), and `endpoint.py`
is byte-identical in 0.0.41 and 0.0.42 — so owning the route is
currently the only way to get a verified identity onto
`config["configurable"]`. Adding that seam upstream in
`ag-ui-protocol/ag-ui` is tracked as **OSS-760**; when it lands, both
pages collapse back to the helper form and the DIY route stays only as
an escape hatch.
The broader "document request-scoped auth for
`add_langgraph_fastapi_endpoint`" ask in #3177 is now substantively
answered by these pages; leaving that issue open pending a maintainer's
call on whether it wants an SDK-level hook rather than the DIY endpoint.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Novita exposes an OpenAI-compatible /openai/v1 endpoint, so it works through
the existing createOpenAI({ baseURL }) pattern documented for OpenRouter,
Ollama, Together, and Groq. Add it to the same list.
Nine /integrations/<fw>/* links were rewritten to their canonical URLs.
Checking production, they were never broken — seo-redirects.ts 301s that
whole retired surface, so a reader always landed on the right page. That
made them cosmetic, and cosmetic changes do not belong in a PR whose
value is the defects around them.
Removing them takes this from 22 files to 15, all of which are things a
reader actually hits. The canonicalization is still worth doing; the
checker now reports it as its own advisory (legacy-redirect-links) so it
is tracked rather than lost.
Twenty-four defects a reader would hit, each verified against the tree
rather than pattern-matched. Found while root-causing PDX-313.
Links written as filesystem paths instead of served URLs (9). The docs
router serves integration pages at /<framework>/<slug>; the
/integrations/ prefix is the content directory, not a route. All nine
corrected URLs were confirmed to resolve.
Tutorial cross-links to directories with no index.mdx (4). loadDoc
resolves <slug>.mdx or <slug>/index.mdx, so /tutorials/ai-todo-app was a
404 — the page is at /overview.
Snippet components used with props but never imported (7). These fall
through to stubWithPartial in the global mdx-registry, which drops props
"on the floor" by design, so framework="pydantic-ai" never reached the
partial and the shared snippet rendered untailored. Importing the
partial restores prop flow. The mastra and ag2 siblings were already
correct; the seven broken ones are all in authored trees.
Dead YouTubeVideo imports (2). The component is provided globally by
mdx-registry.tsx and four other pages render it with no import at all;
these two imported a module that has never existed in the repo.
Stale byoc-* demo ids (2). Renamed to declarative-* in 70e2fb13c8
(2026-05-10, "rename byoc-* slugs to declarative-*"); the docs were
never updated. Only the three registry ID references per page change
here — snippet_cell, InlineDemo, IntegrationGrid.
Left alone deliberately: the runtimeUrl/agent code samples on the
hashbrown and json-render pages. The API routes were renamed to
copilotkit-declarative-*, but the agent ids were not renamed
consistently — declarative-hashbrown's demo uses
agent="declarative-hashbrown-demo" while declarative-json-render's still
exports AGENT_ID = "byoc_json_render". Guessing would ship a broken
copy-paste sample, so that needs an owner.
Mechanical repairs found while auditing the pydantic-ai docs. Each was
verified against the tree; nothing here is a content rewrite.
- Delete `quickstart/pydantic-ai.mdx` + its `meta.json`. `seo-redirects.ts`
already routes `/pydantic-ai/quickstart/pydantic-ai` ->
`/pydantic-ai/quickstart` (rule F6), and adk got the same treatment (F7).
pydantic-ai was the only framework still carrying a `quickstart/`
subdirectory alongside the canonical `quickstart.mdx`.
- `human-in-the-loop/agent.mdx`: link to the canonical quickstart directly
instead of the redirected legacy path, and point the starter link at
`examples/integrations/pydantic-ai` — `examples/coagents-starter-pydantic-ai`
does not exist.
- `docs-links.json`: `subagents.shell_docs_path` was `/multi-agent/subagents`,
which has no page. The real page is `/multi-agent-flows`, which the
entry's own `og_docs_url` already pointed at.
- `headless-simple/chat.tsx`: the console tag said `langgraph-python` inside
the pydantic-ai package. This sits in an `@region` block, so it is pulled
into docs as a snippet. 11 other integrations carry the same copy-paste;
they are left for the fleet sweep.
- `examples/showcases/pydantic-ai-todos/README.md`: `uv run src/main.py` ->
`uv run main.py` (there is no `src/main.py` in that tree), and the stated
Python floor now matches `agent/pyproject.toml` (`>=3.13`).
- `examples/canvas/pydantic-ai/README.md`: Python 3.8+ was unrunnable —
`agent/agent.py` uses PEP 604 unions. Aligned to the sibling tree that
pins the same `pydantic-ai-slim==2.22.0`.
Children of `CopilotSidebar` cannot use `height: 100%`. Both wrappers the
sidebar puts around your app -- `.copilotKitSidebarContentWrapper` and
`.copilotKitModalChildrenWrapper` (which had no CSS rule at all) -- are
auto-height blocks, so a percentage height on a child has no definite
containing block and collapses to content height.
Add an opt-in `fullHeightChildren` prop that gives the content wrapper a
one-viewport height and lets the children wrapper fill it. It is opt-in
because the content wrapper wraps the entire consumer app, and giving
every react-ui sidebar user a flex column with a fixed height would
reflow apps that never asked for it.
The height is a viewport unit, not `100%`: `100%` only resolves when
every ancestor (html/body/#root) also declares a height, which react-ui
neither sets nor can guarantee, so it would silently no-op in a stock
Next.js app. `min-height: 0` on the children wrapper clears the flex-item
`min-height: auto` floor so tall content scrolls inside the child instead
of stretching the wrapper past the viewport.
Fixes#261
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Ashish Shaw <77574570+ashish4143@users.noreply.github.com>
## Summary
`mcpApps.servers` entries that carry `includeTools` or `excludeTools`
are currently accepted even though the pinned
`@ag-ui/mcp-apps-middleware` package has no option for them. The runtime
then ignores the keys, so tools an operator intended to restrict remain
available. This change rejects that configuration instead of allowing a
silent no-op.
## What CopilotKit owns
- `mcpApps.servers` configuration and `agentId` scoping.
- Projection of selected servers into `MCPAppsMiddleware`.
- Reporting unsupported configuration before middleware construction.
Discovery, model-emitted tool execution, frontend-proxied execution,
server identity, and tool provenance belong to
`@ag-ui/mcp-apps-middleware`.
## Changes
- Extract the server projection into `resolveMcpAppsServers`, which
scans all configured entries for defined policy keys, filters by
`agentId`, strips only `agentId`, and forwards other fields unchanged.
- Return a configuration error naming the unsupported key, server,
pinned middleware version, owning package, and issue when a policy key
is supplied.
- Add tests for agent scoping, field forwarding, malformed and empty
values, undefined spread values, constructor avoidance, and the existing
HTTP error path.
- Document the ownership boundary and add a runtime changeset.
## Why the filter stays external
The pinned package is version `0.0.3`. It owns the private server maps,
UI-tool discovery, model-emitted execution, and frontend proxy
execution. A CopilotKit middleware could observe only one of those paths
and would have to duplicate private server identity and tool provenance.
The complete `includeTools` and `excludeTools` implementation belongs in
the external package, where one predicate can cover discovery and both
execution paths.
## Current behavior
Plain JavaScript or JSON configuration can supply `excludeTools:
["delete_account"]` without a TypeScript excess-property check. The
runtime currently accepts the configuration, constructs
`MCPAppsMiddleware`, and leaves the tool available. The new behavior
returns an HTTP 500 through the existing runtime error path, names the
unsupported key and dependency, and does not construct the middleware.
## Follow-up
The counterpart change in `@ag-ui/mcp-apps-middleware` should add the
fields to the per-server configuration, preserve absent versus empty
include lists, resolve server identity through its existing maps, and
apply one predicate after UI-resource discovery and before model-emitted
and proxied tool execution. Once that version is released, CopilotKit
can remove the rejection and pass the fields through unchanged.
## Related issue
Refs #5930.
The cross-repository ownership split follows the proposal in
https://github.com/CopilotKit/CopilotKit/issues/5930#issuecomment-5128722524.
This PR does not close the issue.
## Test plan
- [x] `pnpm -C packages/runtime exec vitest run
src/v2/runtime/__tests__/mcp-apps-servers.test.ts
src/v2/runtime/__tests__/mcp-apps-middleware-integration.test.ts`
passed, 2 files and 20 tests
- [x] `pnpm -C packages/runtime exec vitest run` passed, 129 files and
1,836 tests
- [x] `pnpm exec nx run @copilotkit/runtime:check-types` passed
- [x] `pnpm exec oxlint` and `pnpm exec oxfmt --check` passed on changed
TypeScript files
- [x] `pnpm check:plugin-skills` passed
- [ ] `CI green for static / quality and test / unit on Node 20, 22, and
24`
## Summary
The A2UI integration docs still use helper names and wire keys from
before the Python SDK's v0.9 API. The examples now match the current
SDK, while the A2A page clearly labels its cloned starter's v0.8
compatibility contract.
## Changes
- Update the generic, DeepAgents, and LangGraph A2UI pages to current
helper names, wire keys, and operation order.
- Reconcile the A2A page to the cloned starter's v0.8 payload and defer
its v0.9 migration.
- Remove unsupported `action_handlers=` and `dataContextPath` claims
from the advanced examples.
- Use the exported `createA2UIMessageRenderer` `onAction` interceptor in
the React guides.
## Out of scope
Migrating `examples/integrations/a2a-a2ui/` from its v0.8 renderer and
operation list requires source and example changes outside this
documentation-only target.
## Related PRs and Issues
Addresses the v0.9 documentation portion of #4821.
The corrected names follow `sdk-python/copilotkit/a2ui.py`; the A2A page
follows the cloned starter's current v0.8 contract. Closed partial work
is tracked in https://github.com/CopilotKit/CopilotKit/pull/5854.
## Test plan
- [x] Documentation search passed. The v0.9 pages contain no stale
Python helper names, current wire names are present, and the A2A
compatibility page is labeled.
- [x] Diff validation passed. Only the eight named MDX files changed.
- [ ] Shell-docs typecheck, lint, and formatting were unavailable
because this worktree has no installed `node_modules`; CI will run them
on the PR.
- [ ] CI green (`static / quality`, `test / unit` on Node 20/22/24).
The self-hosted LangGraph auth guides told readers to wrap their graph in
`CopilotKitRemoteEndpoint`. That path is retired and fails two ways against
the current SDK (copilotkit 0.1.94 / ag-ui-langgraph 0.0.4x):
* `from copilotkit import ... LangGraphAgent` -> ImportError (the export is
`LangGraphAGUIAgent`)
* `CopilotKitRemoteEndpoint.execute_agent()` calls `agent.execute(...)`, but
`LangGraphAGUIAgent` only defines `run(...)` -> AgentExecutionException:
'LangGraphAGUIAgent' object has no attribute 'execute'
Replace both with the supported pattern: serve the AG-UI endpoint yourself, let
a FastAPI dependency validate the forwarded `Authorization` header (401 before
the graph runs), and bake the resolved user into a per-request
`LangGraphAGUIAgent(config={"configurable": {...}})` so nodes read an
already-verified identity off `RunnableConfig`. Also document the gate-only
variant that keeps `add_langgraph_fastapi_endpoint`.
Two adjacent fixes on the same pages:
* the frontend channel is `headers={{ Authorization }}`, not
`properties={{ authorization }}` — the runtime forwards `authorization`
(and custom `x-*`) onto the agent call, while `properties` are delivered as
AG-UI `forwardedProps` and are never turned into a Bearer credential
* the Platform user lands in `config["configurable"]["langgraph_auth_user"]`,
not `config["configuration"][...]`
Fixes#5961
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Documents the now-bounded in-memory runner for users: the maxThreads /
maxRunsPerThread / maxBytes limits and their defaults, the precise eviction
model (LRU threads, per-thread run-cap, cross-thread byte ceiling enforced at
run completion), and the onConcurrentRun throw/supersede option. Clarifies that
the store is a process-global singleton shared by every runner, that dedup
weakens past the run cap, and points at the first-party SqliteAgentRunner for
durable or multi-instance deployments. Adds a troubleshooting entry for the
in-memory eviction warning.
Co-Authored-By: Claude <noreply@anthropic.com>
Maxim