The verify-image-refs gate (verify-railway-image-refs.ts) failed because the
live Railway service `showcase-crewai-conversational-flows` had no entry in the
SERVICES map, tripping the Railway->SSOT drift check (1 untracked service).
Add the service as a STAGING-ONLY entry: the live Railway service currently has
a serviceInstance in staging only (no prod instance is provisioned), so the
env-map schema declares only the env that exists. All values (serviceId,
staging instanceId, domain, healthcheckPath) are read verbatim from the live
Railway API, not guessed. ciBuilt:false because the integration is wired only
into the PR-check build (showcase_build_check.yml), not showcase_build.yml's
ALL_SERVICES matrix, so it stays out of CI_BUILT_SERVICES.
Regenerate railway-envs.generated.json and update the count/coverage
assertions in the affected tests (SSOT now has 42 services; findMissingServices
is intentionally asymmetric for the staging-only entry: 41 prod, 42 staging).
## What
Adds a **LangSmith Platform** deploy guide to the CopilotKit docs,
modeled after the existing AWS AgentCore deploy page.
It's a self-contained, agent-side guide: deploy a **LangGraph** or
**Google ADK** agent to the LangSmith Platform, then point the
CopilotKit Runtime at it. LangSmith has no frontend-hosting offering, so
the guide covers only the agent side plus wiring the runtime.
## Pages
- **Canonical:** `deploy/langsmith.mdx` — renders in the Overview →
Deploy sidebar.
- **Per-framework wrappers** (thin, like AgentCore):
- `integrations/langgraph/deploy-langsmith.mdx` → `<Content
framework="langgraph" .../>`
- `integrations/adk/deploy-langsmith.mdx` → `<Content framework="adk"
.../>`
- Both registered in their `meta.json` under a new `---Deploy---`
section.
- **Shared walkthrough snippet:**
`snippets/integrations/langsmith/index.mdx` — single source of truth for
all three pages; framework-aware via the `Content` loader scope. Reuses
the existing `langgraph-platform-deployment-tabs` snippet for the "grab
your deployment URL" step.
## Structure (mirrors agentcore.mdx)
Intro → How it works (ASCII flow `Browser → CopilotKit Runtime →
LangSmith deployment → your agent`) → What you get → Quickstart
`<Steps>` inside a `<TailoredContent>` (deploy-new vs already-deployed)
→ `<Callout>`s for the API key/URL and the LangSmith docs authority →
framework tabs (LangGraph / Google ADK) for the deployable-app step →
Troubleshooting `<Accordions>` → What's next `<Cards>`.
## Registry glue
- Generalized the `Content` MDX component to accept an optional
`partial` prop (defaults to the AgentCore partial; existing AgentCore
wrappers unchanged).
- Registered a `LangGraphPlatformDeploymentTabs` stub so the existing
deployment-tabs snippet is reusable.
## Verification
- Commands/flags (`uv tool install langgraph-cli`, `langgraph new
--template new-langgraph-project-python`, `langgraph deploy
--name/--deployment-type dedicated`, deployment API URL) verified
against the live LangChain quickstart.
- ADK path (`pip install "deployments-wrap-sdk[google-adk]"`,
`saf_sdk.adk` `wrap()` + `LangsmithSessionService`, `langgraph.json`
export) verified against the live [Deploy Google ADK
agents](https://docs.langchain.com/langsmith/deploy-google-adk) guide.
- Runtime wiring (`LangGraphAgent` from `@copilotkit/runtime/langgraph`
with `deploymentUrl` / `graphId` / `langsmithApiKey`) matches the repo's
LangGraph quickstart.
- `oxfmt` (format) clean, `oxlint` exits 0, `tsc` clean; registry /
search-href / link-rewrite tests pass. (Pre-existing failures in this
worktree from an uninstalled `react-icons` and unfetched git-LFS assets
are unrelated.)
## Note (small extra)
The LangGraph `deploy-agentcore.mdx` wrapper already existed but was
orphaned (not in any `meta.json`). The new `---Deploy---` section
surfaces it alongside `deploy-langsmith`, matching how AWS Strands
already exposes it.
Ticket: GROW-540
Use AsyncOpenAI so cancellation reaches the in-flight GenerateA2UI request while retaining the thread fallback for synchronous backend tools.
Preserve cancelled versus resolved-null interrupts across pinned ag-ui-crewai 0.3.0 by encoding only resolved null as JSON null and failing loudly on version drift.
Reuse the canonical shared render_a2ui schema so the secondary request remains aligned with the shared tool contract.
Ports `showcase/integrations/pydantic-ai` — the last pydantic-ai surface
still on v1 — to Pydantic AI v2. Refs #6364.
Three commits plus a bot formatting fix, best reviewed separately.
## 1. `chore(showcase): port pydantic-ai integration to Pydantic AI v2`
- **`requirements.txt`** → `pydantic-ai-slim[ag-ui,openai]==2.22.0`,
`ag-ui-protocol==0.1.19`. Drops the `opentelemetry-api<1.44` ceiling
from #6374; v2 resolves cleanly against otel 1.44.0, so the workaround
is no longer needed. `starlette<1.0.0` is unchanged and satisfies v2's
`>=0.46.2`.
- **9 `StateDeps` imports** move from `pydantic_ai.ag_ui` (removed in
v2) to `pydantic_ai.ui`.
- **`agent_server.py`** — `Agent.to_ag_ui()` was removed in 2.0.0, so a
`mount_agent()` helper builds the equivalent Starlette sub-app and
mounts it. The shape is deliberately identical to what v1's `AGUIApp`
produced — a Starlette app whose only route is `POST /`, named
`run_agent` — so **all 19 mount paths behave exactly as before, trailing
slashes included, and no TypeScript route file changes**.
`deps` is constructed **per request**. v1's `run_ag_ui` did `deps =
replace(deps, state=state)`, handing each run its own object; v2's
adapter does `deps.state = state`, mutating what it is given. A single
shared instance under v2 therefore lets concurrent runs overwrite each
other's state mid-run.
## 2. `fix(showcase): apply the multimodal provider gate to v2 native
content`
v2's `AGUIAdapter.load_messages` converts AG-UI attachments to native
content types *before* the model boundary; v1 delivered the raw AG-UI
part dicts. `_NATIVE_CONTENT` listed `BinaryContent` as a flatten
fixpoint, so under v2 inline attachments were waved straight through and
the entire provider gate was skipped:
- inline PDFs were no longer text-extracted, so raw bytes went to OpenAI
- unsupported image subtypes (HEIC/SVG/TIFF) were no longer degraded and
reached the provider as images, which fails the turn
- missing-mime magic-byte sniffing never ran
- `AudioUrl`/`VideoUrl` were neither fixpoints nor classifiable, so they
hit the fail-loud raise
`BinaryContent` is no longer a fixpoint. `_classify_native_content` maps
native content onto the same `(kind, scheme, mime, value)` tuple the
AG-UI classifier already produces, so **every existing gate applies
unchanged** — no gate logic was rewritten. `audio/*` and `video/*` are
named explicitly because `_kind_for` routes them to `"other"`, and a
missing mime defaults to `"image"` so the sniffer runs.
Net behaviour matches v1: a supported inline image still flattens to an
`ImageUrl` data URI, which is why most of the suite went green without
touching assertions.
Five assertions did change. They checked that state-backing content was
still AG-UI `InputContent`, which encoded v1's bridging. They now assert
the flatten's output (`ImageUrl`) never appears in state — the leak they
were written to guard. The adjacent identity and snapshot checks that
prove non-mutation are untouched.
## 3. `fix(showcase): gate url-source content and correct the v1-parity
claim`
Adversarial review of the first two commits found the gate was only half
fixed. `_NATIVE_CONTENT` still short-circuited `ImageUrl` and
`DocumentUrl`, which v2 builds from unvetted client input, so url-source
attachments bypassed the gate where v1 routed them through it:
- an `image/heic` or `image/svg+xml` url reached the provider as
`input_image`, which the Responses API rejects — failing the turn
- an `audio/mpeg` document url reached it as `input_file`
- a blank-mime inline PDF went to the image sniffer instead of text
extraction, because `load_messages` collapses `ImageInputContent` and
`DocumentInputContent` to the same bare `BinaryContent` and erases the
modality v1 defaulted on
Native content is now gated **before** the fixpoint check rather than
instead of it. `_classify_native_content` returns a tuple only when the
gate must act; `None` means provider-safe and falls through to the
fixpoint, preserving object identity. `ImageUrl` is gated rather than
rerouted so a provider-safe one keeps its identity and any explicit
`_media_type`.
It also corrected a false claim. The `mount_agent` docstring said
routing *and* behaviour were unchanged. Routing is; model input is not.
v2 defaults `manage_system_prompt='server'`, so each agent's
`system_prompt=` now reaches the model. On v1 it never did —
`_agent_graph` emitted system parts only `if not messages` and the AG-UI
bridge always supplied history — so **18 of 19 agents had silently dead
system prompts on main**. A/B on both versions with the same agent and
request: v1 sends 0 system-prompt parts, v2 sends 1. The new behaviour
is correct and kept; the docstring now says so.
## Verification
Against pydantic-ai 2.22.0, in a venv built from this branch's
`requirements.txt`:
- **52/52 Python tests pass**, up from 42/52.
`test_multimodal_content_mapping.py`'s `importorskip` pointed at the
removed `pydantic_ai.ag_ui`, which would have skipped all 43 of its
tests **green** under v2; it now targets `pydantic_ai.ui.ag_ui` and uses
the public `AGUIAdapter.load_messages` in place of the v1 private
helper.
- **16/19 mounts** return `200 text/event-stream` with `RUN_STARTED …
RUN_FINISHED` and no `RUN_ERROR`, driven through the real app with
`TestClient` using trailing-slash URLs as the TS routes do. The other
three (`/a2ui_dynamic`, `/beautiful_chat`, `/`) reach tool execution and
then fail on a raw `OpenAI()` client constructed inside a tool, which
the harness cannot intercept and aimock handles in CI.
- **Per-request deps isolation** confirmed on
`/shared_state_read_write`: state sent by one request does not appear in
the next.
`build-check (pydantic-ai)` is green on this branch, and because
`requirements.txt` changed, the cached pip layer was invalidated — so
that was a **genuine fresh resolve of pydantic-ai 2.22.0 inside the real
Dockerfile**, not a cached pass. It also confirms dropping the
`opentelemetry-api<1.44` ceiling is safe.
### D6 harness probes — run, with a baseline
The behavioural gate is the shared harness D6 probes. No CI job runs
them for showcase paths, so they were run locally on both this branch
and `main`:
| | main (v1) | this branch (v2) |
|---|---|---|
| passed | **33** / 36 | **34** / 36 |
| `reasoning-display` | ✗ `no reasoning-role message rendered within
5000ms` | ✅ **passes** |
| `gen-ui-agent` | ✗ `waitForTurnComplete … runStartCount=2,
done-signal-missing` | ✗ identical error |
| `shared-state-read` | ✗ `Strict mode: 1 candidate fixture(s) skipped
by sequence/turn state` | ✗ identical error |
```bash
cd showcase
AIMOCK_URL_LOCAL=http://localhost:4010 bin/showcase test pydantic-ai --d6 --direct --rebuild --cycle --verbose
```
**The port takes D6 from 33/36 to 34/36.** The two remaining failures
are pre-existing on `main` with byte-identical error strings — this
branch neither causes nor fixes them, and both are tracked in #6381
rather than blocking here.
`gen-ui-agent` is root-caused and is not fixture drift: that demo was
never ported to pydantic-ai. `src/agents/gen_ui_agent.py` exists in
llamaindex with a real `set_steps` tool but has no counterpart here, the
route points at `/gen_ui_tool_based/` (the chart-viz agent), and
`set_steps` is declared nowhere in the package. The fixture fabricates
`set_steps` calls the backend cannot honour, so pydantic-ai rejects the
unknown tool and exhausts its single retry. Confirmed live against real
OpenAI: the cell returns plain text, which is correct for the code as
written.
`reasoning-display` going green is the notable behavioural gain, and it
retires a documented v1 limitation. `PARITY_NOTES.md:91-97` justifies
omitting the reasoning-message branch of `use-rendered-messages.tsx` on
the grounds that "PydanticAI's AG-UI adapter does not emit reasoning
content today" — true on v1, false on v2. (That block is stale on two
further counts: it cites `@ag-ui/core@0.0.43` where `package.json` pins
0.0.57, and claims `ReasoningMessage` is not exported where it is
imported at `reasoning-block.tsx:4`.) Correcting it is tracked on #6364.
To be precise about what that proves: **v2 forwards reasoning content
where v1 dropped it.** The probe supplies the reasoning channel via its
fixture, so what is verified is the forwarding path — adapter → AG-UI
stream → frontend renderer — end to end. Whether a given model actually
emits a reasoning summary live is a separate matter and outside this
port's control: it requires a native reasoning model
(`reasoning_agent.py` defaults to `gpt-5`, overridable via
`REASONING_MODEL`) and, for summary text, a verified OpenAI
organisation. A live run here returned prose with no reasoning block,
consistent with the org-verification gate rather than anything in the
port.
Also verified: the image builds from scratch on v2. Because
`requirements.txt` changed, the cached pip layer was invalidated, so
`build-check (pydantic-ai)` in CI was a genuine fresh resolve of
pydantic-ai 2.22.0 inside the real Dockerfile — which also confirms
dropping the `opentelemetry-api<1.44` ceiling is safe.
### CI gate coverage, for the record
No CI job exercises this package's runtime behaviour on a PR, on this
branch or on `main`:
- `test / e2e / dojo` runs from the upstream `ag-ui` checkout (`ref:
main`) against upstream example agents, and filters on `packages/**` /
`sdk-python/**`
- `test_showcase-frontend-matrix.yml` is dispatch-only and builds the
integration from `base/` — a frozen-backend React baseline
- `showcase_validate.yml` asserts `tests/e2e/` exists with a minimum
spec count; it does not run it
- the package's own `tests/e2e/` (37 files) is invoked by nothing — per
`AGENTS.md` rule 1 the measuring test is the shared harness probe, so
that layer is legacy
## Remaining for #6364
Two acceptance criteria are outstanding, which is why this says Refs
rather than Closes:
- the harness D6 value-test (`bin/showcase test pydantic-ai --d6
--rebuild`), which no CI gate runs for showcase paths
- `PARITY_NOTES.md` has 6 version-dependent blocks, 4 of which were
already inaccurate against the tree before this PR; left alone
deliberately to keep this diff scoped
## Possible follow-up
`multimodal_agent.py` still reaches into three private APIs
(`pydantic_ai._run_context`, `pydantic_ai.models.wrapper`,
`pydantic_ai.models.{ModelRequestParameters,StreamedResponse}`) and
subclasses `WrapperModel`, overriding
`request`/`count_tokens`/`request_stream`. v2 adds a supported
alternative: `AbstractCapability.before_model_request`, which receives a
`ModelRequestContext` carrying `messages` and `streaming`. Migrating
would delete those private imports and ~85 lines. Deliberately not in
this PR — it fixes nothing and would obscure the review.
Reason: Add the current MiniMax text models to BuiltInAgent model
resolution.
- Register MiniMax-M3 and MiniMax-M2.7 as built-in model identifiers.
- Resolve MiniMax model strings through the global endpoint with API key
and regional base URL configuration.
- Document both model specifiers and cover global and China endpoint
selection.
Checks:
- `node_modules/.bin/nx run @copilotkit/runtime:test --
src/agent/__tests__/resolve-model-baseurl.test.ts`
- `node_modules/.bin/nx run @copilotkit/runtime:check-types`
- `pnpm validate:model-names`
- `node_modules/.bin/nx format:check
--files=packages/runtime/src/agent/index.ts,packages/runtime/src/agent/__tests__/resolve-model-baseurl.test.ts`
- `git diff --check`
Fifteen defects in the shell-docs tree, each verified against the
running site or the source of truth rather than pattern-matched. Found
while root-causing
[PDX-313](https://linear.app/copilotkit/issue/PDX-313).
Scoped deliberately: this is content only. The checker changes that
surfaced these follow separately.
## Snippet components used with props but never imported (7)
The subtlest item here, and invisible to anyone skimming the source.
`<FrontendTools components={…} framework="pydantic-ai" />` without an
import falls through to `stubWithPartial` in the global mdx-registry,
which drops props "on the floor" by design. So `framework` never reached
the partial and the shared snippet rendered **untailored** — the reader
got generic content on a framework-specific page.
The `mastra` and `ag2` siblings were already correct. All seven broken
ones are in authored trees, matching the template-residue pattern from
OSS-777.
## Tutorial cross-links that land on the homepage (4)
`/tutorials/ai-todo-app` and `/tutorials/ai-powered-textarea` have no
`index.mdx`, so they `307 -> /`. A reader clicking "next: the todo app
tutorial" gets the docs homepage. The pages are at `/overview`.
## 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 70e2fb31 (2026-05-10, *"rename byoc-\*
slugs to declarative-\*"*); the docs were never updated, so the ids
resolve against nothing in the registry. Only the three registry ID
references per page change — `snippet_cell`, `InlineDemo`,
`IntegrationGrid`.
## What was cut, and why
An earlier revision of this PR also rewrote nine `/integrations/<fw>/*`
links to their canonical URLs. Checking production, those were never
broken:
```
/integrations/adk/quickstart -> 301 /google-adk/quickstart
```
`seo-redirects.ts` keeps that retired surface alive for inbound SEO
traffic, so readers always landed correctly. Canonicalizing them is
still worth doing — a 301 costs a round trip and couples internal
navigation to a legacy surface — but it is cosmetic, and it was padding
a diff whose value is the defects above. Dropped; tracked separately.
## Left alone deliberately
The `runtimeUrl` / `agent` code samples on `generative-ui/hashbrown.mdx`
and `generative-ui/json-render.mdx`. The API routes were renamed to
`copilotkit-declarative-*`, but the agent ids were **not** renamed
consistently:
| demo | agent id |
| --- | --- |
| `declarative-hashbrown` | `agent="declarative-hashbrown-demo"`
(renamed) |
| `declarative-json-render` | `AGENT_ID = "byoc_json_render"` (not
renamed) |
A blind find-and-replace over `byoc-` would have shipped a broken
copy-paste sample. Needs an owner's call.
## Review notes
15 files, +17/-12. The seven import additions are the only changes that
affect what renders; the rest are identifier strings and link targets.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## What does this PR do?
`@copilotkit/react-native` maintained a **private tool-call render
registry** (`hooks/RenderToolContext.tsx`) alongside the canonical one
that `CopilotKitCoreReact` already provides — and which every React
Native app already ships, unused. This PR deletes the fork and points
React Native at the shared registry.
That fork caused three bugs:
| Bug | Symptom | Cause |
|---|---|---|
| **Tool renders never streamed** | A component registered with
`useRenderTool` / `useComponent` painted nothing until the tool call
completed | `CopilotChat` used `JSON.parse` on the argument buffer.
While a model writes a tool call that buffer is *invalid JSON by design*
— AG-UI delivers `TOOL_CALL_ARGS` deltas that are concatenated
client-side — so the parse threw on every delta, warned, and fell back
to `{}` |
| **`useComponent` rendered nowhere** | Silently, with no error | It
writes to core's registry; React Native's chat read React Native's
private `Map` |
| **Chat history degraded** | Navigating away from the registering
screen turned earlier tool calls into a `Called: <name>` placeholder |
The private `Map` deleted renderers on unmount; core deliberately keeps
them |
`@copilotkit/react-core` has used `partialJSONParse` on this path since
v2 shipped. React Native diverged because `useRenderToolCall` was
excluded from its re-exports on the stated grounds that it "depends on
DOM elements via `DefaultToolCallRenderer`" — a claim that was never
true of the hook itself. It was only ever reachable through the fat
`/v2` entry, whose weight is the real hazard (#4893). #5883 moved it
into `/v2/headless` on 2026-07-23; the exclusion comment was rewritten
the next day without revisiting the reason.
### What changed
- **One registry.** `useRenderTool` registers through `useFrontendTool`
into `CopilotKitCoreReact.renderToolCalls`. `CopilotChat` and any custom
surface consume react-core's `useRenderToolCall`.
- **Types are derived, not declared.** `RenderToolProps` is now
`React.ComponentProps<ReactToolCallRenderer<T>["render"]>`, so React
Native cannot drift from `ReactToolCallRenderer` — the contract every
registered renderer is actually invoked against. Change that contract
and `check-types` names every React Native renderer the change breaks.
React Native narrows only the *return* type to `ReactElement | null`,
which `FlatList`'s `renderItem` genuinely requires.
_Scope of that guarantee (corrected during review):_ it does **not**
extend to the type react-core publicly exports under the same name.
Web's `RenderToolProps<S>`
(`react-core/src/v2/hooks/use-render-tool.tsx`) is a separate
hand-declared union, generic over a schema, carrying arguments under
`parameters` (not `args`) and declaring `status` as string literals
rather than `ToolCallStatus` members. Both divergences are live today
and nothing type-checks them shut — the one place the shapes meet,
react-core's own bridge, compiles because a string-enum member is
assignable to its own literal type but not the reverse. Aligning web's
alias is a breaking web API change, filed separately.
- **`RenderToolContext.tsx` deleted** (−150 lines), along with 15 tests
that described the removed subsystem. One of them — `unregisters the
render function on unmount` — asserted the chat-history bug as a
requirement.
- **Two structural CI guards for #4893**, in opposite directions: a test
failing if any React Native source imports the fat `/v2` entry, and a
script failing if react-core's `/v2/headless` or `/v2/context` chunks
ever link shiki/mermaid/cytoscape/katex/streamdown. Both were verified
able to fail by deliberately introducing the regression. These are
*structural* assertions, not size budgets — `dev-docs/bundle-size.md`
freezes `limit` fields until OSS-122.
- **`react-native` added to the bundle-size glob**, which it had never
been in, plus a `size:headless` measurement.
React Native also gains capabilities it lacked: render props inferred
from your schema, `name`/`toolCallId` on render props, and `result` on
completed calls.
**Corrected during review — two capabilities this originally claimed are
not delivered:**
- **Wildcard (`"*"`) renderers do not work on React Native.** Because
`useRenderTool` routes through `useFrontendTool` (which calls
`addTool`), `name: "*"` registers a frontend tool literally named `*` —
advertised to the model, and colliding with core's separate
wildcard-executable-tool path. react-core's `useRenderTool` is
renderer-only and special-cases the wildcard; React Native's is not. The
guide now advises against it.
- **`followUp` (and `available`) are not forwarded**, and the handler's
`context` argument is dropped, so `stopAgent()`'s abort signal is
unreachable from an RN handler.
Both are tracked in § Known limitations for the follow-up that converges
React Native onto react-core's hooks — deleting RN's `useRenderTool` in
favour of re-exporting `useFrontendTool` (tool + renderer) and
react-core's `useRenderTool` (renderer-only, wildcard-capable). That is
an API change with its own migration note, so it is not in this PR.
### ⚠️ Breaking (in a minor)
`useRenderToolRegistry` and `RenderToolProvider` are **removed**. Both
are documented on the docs site, so this is a real break — see the
`BREAKING CHANGE:` footer on `db67ccf`, which is what the release notes
derive from, plus the rewritten reference pages.
```diff
- const registry = useRenderToolRegistry();
- const renderer = registry.get(toolCall.function.name);
- return renderer ? renderer({ args, status }) : null;
+ const renderToolCall = useRenderToolCall();
+ return renderToolCall({ toolCall });
```
Also note two semantic changes: `args` is `Partial<T>` **only** while
`status` is `"inProgress"`, and a render function is now captured at
registration — if it closes over changing values you must declare them
in `deps` (React Native previously refreshed the closure on every
render).
**Known limitation:** agent-scoped renderer resolution does not take
effect on React Native. `CopilotChatConfigurationProvider` is not in
RN's provider tree, so `agentId` always resolves to the default.
Renderers still resolve by name; two agents registering the same tool
name resolve arbitrarily. Filed separately.
### A data point worth recording
Adding `useRenderToolCall` to the measured headless entry moved the
bundle **92.8 kB → 92.7 kB**. Flat. The hook React Native spent months
not using was already inside the chunk every RN app resolves whole —
Metro doesn't tree-shake, so the fork never saved a byte. It cost them.
### Testing
- `@copilotkit/react-native`: **253 passing / 22 files** ·
`@copilotkit/react-core`: **1480 passing / 123 files** · `check-types`
and `build` green for both.
- Each of the three bugs has a deterministic test driving a real
`CopilotKitCoreReact` — no mocking of the code under test.
- Both #4893 guards carry mutation evidence: introduce the regression,
watch them fail, revert, watch them pass.
### Follow-up
`useRenderTool`'s JSDoc is split across two blocks, which orphans the
primary description from IDE hover (the `@param deps` warning still
surfaces). One-line fix, deliberately left out of the final fix wave.
## Related PRs and Issues
- **Supersedes #6346** (@davidmckayv) — its diagnoses were correct and
its test assertions are ported here, re-driven through the real registry
rather than a mocked local one. Credited via `Co-Authored-By` on
`4104bd1`.
- Addresses the React Native half of **#4893**.
- Builds on **#5883**, which created the lean `/v2/headless` entry this
PR consumes.
## Checklist
- [x] I have read the Contribution Guide
- [x] If the PR changes or adds functionality, I have updated the
relevant documentation
- [x] "Allow edits by maintainers" is checked
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## Summary
- add an on-demand production check for the website and docs discovery
surfaces defined by #6458
- derive the ten in-scope routes and media types from the public
contract instead of maintaining a second monitoring manifest
- exercise those routes as four documented crawler user agents with a
global concurrency cap of four
- validate status, content type, canonical host, robots/sitemaps, one
sampled sitemap link, LLM index links, and soft-404 behavior
- retain failure evidence and provide a deliberate `exercise_alert`
input for proving the `#oss-alerts` path
## Why this matters
AEO is a production property, not a one-time content change. A correct
repository can still deploy a broken canonical, HTML fallback, stale
sitemap, or inaccessible LLM index. Those failures happen at the top of
the agent-led growth funnel: if agents cannot reliably discover and
verify CopilotKit, downstream recommendation and activation work never
gets a chance to perform.
This PR adds the smallest useful operating check for that risk. It is
deliberately limited to PDX-340's website/docs scope. It does not
monitor MCP, the CopilotKit capability document, raw Markdown, Open
Graph, or JSON-LD. Existing deploy-parser utilities are reused where
practical, requests run with bounded concurrency, and failures include
the exact URL, crawler identity, observed status/type, and a bounded
response excerpt.
The workflow is intentionally manual at first. We should not create a
scheduled noisy alarm while the website LLM endpoints are known red, and
we should not claim Slack ownership until a deliberate failure proves
the secret and alert path. A small follow-up can add the schedule after
one normal run is green and one `exercise_alert` run reaches
`#oss-alerts`.
## Stacked dependency
- Depends on #6458; this PR is intentionally based on
`codex/pdx-317-aeo-surface-contract`.
## Validation
- `pnpm nx run @copilotkit/showcase-scripts:validate-aeo-contract
--skip-nx-cache`
- `pnpm nx run @copilotkit/showcase-scripts:test --skip-nx-cache --
__tests__/check-aeo-synthetics.test.ts
__tests__/aeo-synthetics-wiring.test.ts
__tests__/verify-deploy.drivers.test.ts` (102 tests)
- targeted `oxfmt` and `oxlint` checks
- `git diff --check` and commit hooks
## Live baseline (2026-08-12)
The narrowed production command fails with eight records: four crawler
identities × two website gaps.
- `https://www.copilotkit.ai/llms.txt` returns HTTP 200 `text/html` with
a noindex soft-404 instead of plain text
- `https://www.copilotkit.ai/llms-full.txt` returns the same soft-404
The remaining website/docs targets pass: both home canonicals, both
robots files, both sitemaps and sampled links, and both docs LLM
indexes. The current failures are why this PR ships manual-first rather
than enabling a schedule.
## Status
PDX-340 remains In Progress until the website endpoints are fixed, a
normal workflow run is green, the deliberate Slack alert reaches
`#oss-alerts`, and a follow-up enables the agreed schedule.
## Summary
- publish a single shared, versioned technical contract for website,
docs, and docs MCP AEO surfaces
- publish the human policy through the existing shell-docs MDX pipeline
at `/aeo`
- expose the machine-readable contract at
`/.well-known/copilotkit-capabilities/v1.json`
- validate the contract with JSON Schema/Ajv plus narrow repository and
CI cross-reference checks
- run the actual shell-doc behavior tests in CI and assign external
website and Pathfinder gaps to named owners
## Why this matters
Answer engines and coding agents decide which source to trust from
machine signals such as canonical hosts, stable URLs, response types,
and consistent capability claims. When those signals disagree,
CopilotKit can be classified incorrectly, cited from the wrong hostname,
or skipped even when it is the right product.
This PR gives those public surfaces a versioned source of truth. It
separates standards, community conventions, and CopilotKit-specific
guarantees; records real endpoint paths and media types; and makes
ownership explicit when behavior lives in another repository or service.
That gives us a reliable base for improving agent discovery without
pretending one repository can enforce every public surface.
The implementation deliberately uses the current docs architecture:
`/aeo` is ordinary shell-docs MDX under
`showcase/shell-docs/src/content/docs/`, not a bespoke page or the
retired docs tree. Schema shape lives in JSON Schema, while the small
TypeScript layer only checks relationships JSON Schema cannot express,
such as whether referenced files and CI commands exist.
## Validation
- `pnpm nx run @copilotkit/showcase-scripts:validate-aeo-contract
--skip-nx-cache`
- `pnpm nx run @copilotkit/showcase-scripts:test --skip-nx-cache --
__tests__/validate-aeo-contract.test.ts` (6 tests)
- `npm --prefix showcase/shell-docs test -- src/app/sitemap.test.ts
src/app/llms.txt/route.test.ts src/app/llms-full.txt/route.test.ts
'src/app/llms-mdx/[[...slug]]/route.test.ts'
src/app/well-known/copilotkit-capabilities/v1.json/route.test.ts
src/lib/runtime-config.test.ts
src/lib/__tests__/next-config-redirects.test.ts` (43 tests)
- `npm run typecheck` in `showcase/shell-docs`
- `npm run build` in `showcase/shell-docs`
- targeted `oxfmt`, `oxlint`, TypeScript, diff, and commit-hook checks
## External follow-ups
- CopilotKit/website must link the same policy and fix `/llms.txt` plus
`/llms-full.txt`, which returned 200 `text/html` soft-404 pages during
the production audit
- Pathfinder/docs MCP owners must define a machine-readable discovery
surface; the current contract records `/sse` as the known transport
without presenting transport availability as discovery
## Related
- PDX-317
The PR's reviewer asked that the `RenderToolProps` shape change be covered where upgraders
actually read it. A `BREAKING CHANGE:` footer on ec42161670 already describes it, but that
footer reaches no reader: `scripts/release/lib/changes.ts:43` collects commits with
`--format=%H %s`, and `grep -rn "BREAKING" scripts/release/` returns zero hits, so no footer
in this repo has ever reached generated release notes. The docs page is the destination that
does reach users. (The collector is a release-pipeline bug, filed separately.)
Checked every item in ec42161670's inventory against the page. All were present and accurate
except one: the page said renderers "must now tolerate missing fields while in progress" and
stopped there, naming no error code and never mentioning `check-types`. That is the half of
the change most existing renderers trip over, and it breaks the build, not the screen.
Added to the migration section: on the un-narrowed union `args` is `Partial<T> | T`, so
`args.foo` reads as `T["foo"] | undefined` and a strict `tsc --noEmit` rejects any use needing
the field present — TS18048 when dereferencing or calling it, TS2322/TS2345 when passing it
into a slot typed without `undefined`. Deliberately NOT claimed as a blanket "every read
fails": a bare JSX interpolation still compiles because an element accepts `undefined`
children, and the page's own Usage example does exactly that, so the blanket form would have
contradicted a working example on the same page. Added a fix diff narrowing on `status`, and
a cross-link to the two Behavior-section breaks a migration-only reader would otherwise
miss (render captured at registration, unmount keeping the renderer).
Verified against source, not just the footer: the three-arm union in
react-core/src/v2/types/react-tool-call-renderer.ts, the effect keyed on
JSON.stringify(deps) and the cleanup that removes only the tool in use-frontend-tool.tsx,
and `"strict": true` plus `check-types` in the react-native package.
Docs only; one file, no restructuring, nothing removed.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The guide told readers that a `"*"` entry resolves as a renderer-only wildcard
on React Native "exactly as it does on the web", and framed the one difference
as an ergonomic tax (a `"*"` entry "still needs `parameters`"). That is false,
and the real consequence is not ergonomic.
react-core's `useRenderTool` is renderer-only: its body's sole registration is
`addHookRenderToolCall` (use-render-tool.tsx:190), and it special-cases
`name === "*" && !parameters` into a schema-less fallback renderer
(use-render-tool.tsx:166) which `useRenderToolCall` resolves last
(use-render-tool-call.tsx:151). React Native's hook instead delegates wholesale
to `useFrontendTool` (useRenderTool.ts:53), which calls `addTool`
unconditionally (use-frontend-tool.tsx:23). So on RN `name: "*"` registers a
frontend tool literally named `*`. `buildFrontendTools` has no wildcard
exclusion (run-handler.ts:1236), so that tool is advertised to the model in the
run's tool list, and it occupies core's separate wildcard-executable-tool slot
(run-handler.ts:610, 626) whose handler is invoked for every unmatched tool call
with args wrapped as `{ toolName, args }` (run-handler.ts:988) rather than in
the caller's declared shape.
- Rewrote the bullet to advise against `"*"` on React Native and state the
mechanism. Also completed its requirements list: `description` is as
non-optional as `parameters` (useRenderTool.ts:13), and react-core's hook
takes no `description` at all.
- Fixed the example's `status !== "complete"`, which was a web-shaped parity
assumption that does not compile: RN's props derive from
`ReactToolCallRenderer`, whose `status` is the `ToolCallStatus` enum, not
web's string literals. Branches on `ToolCallStatus.Complete` now, and notes
the `args`-vs-`parameters` difference alongside it.
- Added a Known limitations entry, in the voice of the `threadId` one, covering
the wildcard gap plus two more the audit turned up: `followUp` and
`available` are accepted by `useFrontendTool` and not forwarded, and the
`handler` type drops the `context` argument core does pass at runtime
(run-handler.ts:821). All tracked for the convergence follow-up.
No `followUp` claim was present on the page to correct — the gap is real, so it
is documented as a limitation rather than a retraction. No behaviour change:
`packages/react-native/src/hooks/useRenderTool.ts` is untouched, the
convergence is its own PR.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
An earlier commit rewrote the useRenderTool reference to say that comparing a render prop's
`status` against a raw string no longer type-checks, and called that a breaking change. That
was wrong, and it made upgraders believe working code was broken.
`ToolCallStatus` is a string enum, and TypeScript relates an enum literal type to a
same-valued plain string literal (not the reverse). Equality tests comparability both ways, so
`status === "complete"` compiles AND narrows. Only two forms fail: comparing against a string
that matches no member (TS2367), and assigning a raw string to a `status`-typed variable
(TS2322) — assignment, never comparison.
Corrected all three sites that claimed otherwise (the RenderToolProps narrative, the `status`
PropertyReference, and the migration section's "both halves are breaking"). The enum-based
examples stay, now framed as recommended style — self-documenting, and loud if a member's
value changes — rather than a compilation requirement. The migration section now names the
added `InProgress` arm as the one genuinely breaking half.
Also fixed a separate false claim in the same file: the out-of-chat rendering example said
that without a `toolMessage` the status "stays InProgress ... forever". `useRenderToolCall`
reads `executingToolCallIds` from the provider and branches toolMessage -> Complete, else
isExecuting -> Executing, else InProgress, so the Executing arm is reachable with no tool
message at all.
Docs only; no source behaviour changes.
worker-loop's claim gate had exactly one conditional --
`if (budget.available <= 0)` -- and `available` is free Playwright
browser-CONTEXT slots (maxContexts - liveContextCount), nothing else. A
worker whose container has leaked PIDs to the cgroup ceiling therefore
still advertises full capacity and keeps winning claims it cannot
possibly run: the driver cannot fork, so each job burns its entire
600000ms lease and lands as an abort. Measured 2026-08-10: workers at
pids=1000/1000 with 758-761 zombies, 320 `timeout after 600000ms` rows.
Decline the claim above 0.90 of pids.max. Deliberately far above the
control-plane's 0.75 saturation ALARM: the two thresholds do different
jobs. 0.75 pages an operator while the worker is still perfectly able to
run jobs; gating dispatch that early would convert a warning into ~36h
of withheld fleet capacity. 0.90 leaves 100 free PIDs at the prod
ceiling -- a chosen reserve, not a derived one (the per-job PID cost of
a chromium context tree is not measured), hence the env override. The
ordering that matters is that the alarm always fires before capacity is
withdrawn.
BLAST RADIUS -- reuses the SAME decline-and-idle path as the existing
no-budget branch, which is what makes an all-workers-saturated fleet
safe: the job is never claimed, so it is never dropped and never
requeued; it simply stays `pending`. The loop then sleeps a full
pollIntervalMs, so a fully-saturated fleet idles at the poll cadence
instead of spinning. The queue stalls VISIBLY -- pending rows pile up,
the rising-edge warn says why, and the control-plane's
system:worker-pid-saturation alarm fired at 0.75 before this gate
engaged at 0.90. A stalled, alarmed queue is recoverable by redeploy;
claim-fail-repeat silently burned the whole cadence.
The gate is INERT when the cgroup gauges are unreadable (pidUsageRatio
-> null: off-Linux, every macOS dev box), so local workers claim exactly
as before.
Prod harness-workers replicas reach the platform-fixed pids.max=1000
ceiling roughly every 7 days and NOTHING alarmed. Measured 2026-08-10
20:09-20:10Z: pids=1000/1000 zombies=758, 1000/1000 zombies=761,
837/1000 zombies=744, with 320 `timeout after 600000ms` abort rows and
an e2e-smoke run 42 minutes into a 15-minute cadence with 3 jobs still
pending. The documented pool-unrecoverable alarm did not fire: it only
trips when the self-heal breaker gives up, which a PID-starved but
still-heartbeating worker never reaches.
The signal was already on the wire and read by nobody. The worker's
~75s heartbeat writes capacity_pids_current / capacity_pids_max onto
its `workers` row (worker/registration.ts), and fleet-health lists that
whole roster every 15s — its own comment said "the capacity gauges are
ignored here". Nothing in non-test source compared them.
Alarm control-plane-side rather than worker-side, because status-writer
documents `fleet-cp` as the only authoritative fleet writer ("workers
never write status directly"), and because fleet-health already holds
the roster read this needs.
- fleet-health raises a rising-edge alarm at pids.current/pids.max >=
0.75 (~36h of lead time at the observed leak rate), evaluated BEFORE
the online/stale branch since the failing worker is fully ONLINE.
- Latched per worker with a 0.65 hysteresis clear: the monitor ticks
every 15s, so an unlatched alarm would page ~8600 times across the
lead-time window. Construction fails loud on a ratio pair with no gap.
- Unmeasured gauges (null off-Linux, unbounded pids.max) never alarm --
pidUsageRatio returns null and null is never read as zero.
- Routed to a system:worker-pid-saturation status row plus #oss-alerts
via SLACK_WEBHOOK_OSS_ALERTS, the target family-silence and the
D0-gone monitor already post to. Deliberately NOT
SLACK_WEBHOOK_BROWSER_POOL_UNRECOVERABLE, which appears nowhere in
this repo outside its own definition and is unset everywhere -- an
alarm nobody receives is the gap being closed.
harness-workers leaked one cgroup PID slot per orphaned chromium grandchild.
Node as PID 1 only waitpid()s processes it spawned, so every browser crash
stranded ~5 <defunct> renderers permanently. Prod climbed to
pids.current=1000/1000 with zombieCount=757 over 6d22h uptime, after which no
browser could launch and ~295 d6 cells went abort fleet-wide.
Install tini in the existing playwright apt layer and run it as PID 1 via
exec-form ENTRYPOINT. No -g, so signal delivery to node is unchanged and
orchestrator.ts's SIGTERM drain still runs; tini propagates the child's exit
status so a crash still exits non-zero and Railway still restarts.
## What broke
The regression was introduced by commit fec70d086 (feat(angular):
checkpoint 2 - core and package), merged through PR #6109 as b07482da5.
That commit established Angular 20 as the package’s compiler and support
floor, but the demo remained on Angular 21 after 8b13fbcb7 (build:
update ng).
It also introduced the packed smoke runner without canonicalizing macOS
temporary paths, allowing /var/... and /private/var/... to resolve
inconsistently.
## Why I made this change
I moved the demo back to Angular 20 so it exercises the lowest supported
Angular version, aligned the Angular 20 dependencies and support
contract on
20.3.27, and canonicalized the packed consumer directory before starting
the SSR server.
This keeps the demo, package metadata, tests, and lockfile consistent
while making the packed smoke test reliable across symlinked temporary
directories.
## Changes
- Align the Angular demo with the Angular 20 support floor.
- Update Angular 20 dependencies and support-policy tests to 20.3.27.
- Resolve the packed consumer directory to its real path before
launching SSR.
## What does this PR do?
Fixes stale Copilot Runtime documentation links that still point to
`/concepts/copilot-runtime` and now route users to the existing
`/backend/copilot-runtime` page.
This updates both the source JSDoc and the generated reference MDX so
the current docs content and future regenerated reference docs stay
aligned.
## Related PRs and Issues
- Closes#2082
## Testing
- `rg -n "concepts/copilot-runtime" packages
showcase/shell-docs/src/content` returns no matches
- `rg -n "backend/copilot-runtime"
packages/runtime/src/lib/runtime/copilot-runtime.ts
packages/react-core/src/components/copilot-provider/copilotkit-props.tsx
showcase/shell-docs/src/content/reference/v1/classes/CopilotRuntime.mdx
showcase/shell-docs/src/content/reference/v1/components/CopilotKit.mdx`
- `git diff --check`
## Checklist
- [x] I have read the [Contribution
Guide](https://github.com/copilotkit/copilotkit/blob/master/CONTRIBUTING.md)
- [x] If the PR changes or adds functionality, I have updated the
relevant documentation
- [x] "Allow edits by maintainers" is checked (lets us help iterate on
your PR directly — faster turnaround for everyone)
## Summary
This establishes a stronger machine-readable source of truth for agents
choosing and implementing CopilotKit:
- lock production docs canonicals, Open Graph URLs, robots, sitemap, and
LLM artifacts to `https://docs.copilotkit.ai`, with deploy smoke
coverage that fails loudly on hostname leakage
- add a versioned, generated public API manifest covering 26 packages,
92 public import paths, runtime adapters, host factories, compatibility
ranges, and source-backed deprecations
- add manifest drift detection to the release suite and root
generate/check commands
- update the public setup/debug/package skills and their deterministic
evals to current package names, factories, repository paths, and
`1.67.1` metadata
- keep package-owned skills and top-level public mirrors in sync
## Growth impact
Agents should encounter one consistent answer across docs metadata,
LLM-facing artifacts, release metadata, and executable skills. That
reduces hallucinated imports and stale setup paths while giving crawlers
and coding agents a concrete reason to select CopilotKit for
agent-native application experiences—including agent-to-agent
interaction, shared state, human-in-the-loop workflows, tool rendering,
and generative UI.
## Validation
- frozen lockfile install passed
- changed-file formatting passed
- repository lint passed with existing warnings only
- full Nx typecheck passed: 32 projects plus dependencies
- focused docs/manifest/skill suites passed: 4 files, 113 tests
- shell-docs typecheck passed; shell-docs lint passed with existing
warnings
- plugin skill mirrors and public API manifest drift checks passed
- affected commit hook matrix passed tests, publint, and
are-the-types-wrong checks
- full package test matrix passed except two contention timeouts; both
failed projects then passed uncached in isolation:
- `@copilotkit/react-core`: 123 files, 1,481 tests
- `@copilotkit/vue`: 100 files, 1,074 tests
- corrected sequential Nx build passed for all 26 package projects
## Notes
- the repository-wide formatter currently reports 25 pre-existing files
on `main`; every file changed by this PR passes formatting
- deployed docs will continue exposing the old showcase hostname until
this change is promoted; the new production verification will block
future canonical, OG, robots, sitemap, `llms.txt`, or `llms-full.txt`
leakage
- no redirect is included for `docs.showcase.copilotkit.ai` because
ownership of that host is outside this repository's source of truth
Linear: PDX-316, PDX-318, PDX-319
The status PropertyReference declared a string-literal union while the usage
example below it compared against ToolCallStatus. The example was right: RN's
RenderToolProps is derived from ReactToolCallRenderer["render"], whose arms are
typed ToolCallStatus.InProgress/.Executing/.Complete, so a reader who followed
the type= attribute and wrote status === "executing" got TS2322.
Fixed both places that stated the type rather than the values: the
PropertyReference, and the migration section, which described the NEW status as
a literal union and so buried the actual breaking change (RN's old union really
was "executing" | "complete", so existing string comparisons stop compiling).
Added a diff showing that migration. Also aligned the value-naming prose and the
useRenderToolCall example comment on enum members, and recorded in the
RenderTool*Props comparison list that react-core's own props types do declare
status as string literals -- that contrast is real, not an error on this page.
Note: the example needs ToolCallStatus as a value, but react-native/headless.ts
currently re-exports it under `export type`. That export fix is owned elsewhere.
The `deps` array was documented as "similar to `useEffect`" in both the
PropertyReference and the Behavior list. It is not: `useEffect` compares
elements with `Object.is`, while this hook serialises the whole array with
`JSON.stringify` and compares the string
(packages/react-core/src/v2/hooks/use-frontend-tool.tsx:45).
That difference is load-bearing now that React Native's `useRenderTool`
registers through `useFrontendTool` and the documented remedy for its
capture-at-registration semantics is "declare changing values in deps".
Both sites now state the real comparator and link a new "Dependency
comparison" section that tabulates the measured consequences: functions,
`undefined` and symbols serialise to `null`; `Map`/`Set` and instances
whose state is in `#private` fields or prototype getters collapse to `{}`
(own enumerable fields do compare); key order is significant; circular
values and `BigInt` throw during render. The section closes with the two
patterns that work -- a derived primitive, or a latest-value ref.
The react-core/web copy of this page has the same defect and is deferred
to a follow-up.
The React Native guide still described the pre-convergence world: it listed
`useRenderToolCall` among the hooks React Native does not export, and told
readers React Native keeps a render registry separate from react-core's.
Both are now false.
- `useRenderToolCall` IS exported (`src/headless.ts`), along with the
`ReactToolCallRenderer` type. The remaining three web rendering hooks
(`useDefaultRenderTool`, `useRenderCustomMessages`,
`useRenderActivityMessage`) are still genuinely absent, and stay listed with
the reason each one is held back.
- Wildcard resolution now applies on React Native. `useRenderTool` registers
through `useFrontendTool` into `CopilotKitCoreReact.renderToolCalls`, and
`useRenderToolCall` falls back to a renderer named `"*"`. Noted the one
remaining asymmetry: React Native's hook always registers a tool too, so a
`"*"` entry still needs `parameters`, where web has a renderer-only overload.
- The "two different registries" callout is rewritten. There is one registry,
so a `render` passed to `useFrontendTool` does draw in the React Native chat;
the reason to prefer `useRenderTool` is now its `ReactElement | null` return
type, not registry separation.
Left the same bullet's "requires `parameters`" claim alone — still true.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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>
Mark