REST /threads is agent-scoped. The Phoenix user_meta channel is not. Drop live upserts whose agentId does not match the store so Inspector All Agents does not show the same thread twice.
Replace speculative signal machinery with direct state and defer hidden pulses.
Limit click telemetry to real links and add the replay workbench control.
Restore the pointer cursor and record visible launcher presentations.
Add host-scoped read state and the persistent What’s new destination.
Include the responsive Kite treatment, renamed announcement telemetry, and complete behavior tests.
Refs OSS-860, OSS-864, OSS-865
Track the started input through protocol errors so remapped run IDs clean up
the active run without disturbing pre-start failures. Add lifecycle and
multi-call reconciliation coverage.
Reconcile streamed tool results by call identity so divergent message IDs
cannot append a second real result. Share placeholder normalization between
state reconciliation and run-handler forwarding.
## Summary
React v2 feedback callbacks receive an assistant message without the
trace metadata carried by the direct AG-UI event that created it. This
slice exposes that metadata to thumbs callbacks without changing
canonical messages or future run inputs.
## Root cause
AG-UI keeps `rawEvent` on events while reducer-created assistant
messages remain protocol-clean. `StateManager` sees the direct start
event but previously discarded its correlation before
`CopilotChatMessageView` forwarded the message to feedback callbacks.
## Changes
- Store defined direct `TEXT_MESSAGE_START.rawEvent` metadata by agent,
thread, and message.
- Replace repeated scoped entries and prune them with message removal
and lifecycle cleanup.
- Return a cloned sidecar value through
`CopilotKitCore.getRawEventForMessage`.
- Enrich only thumbs-up and thumbs-down callback arguments at click time
across flat and virtualized rendering.
- Add production-path regressions and document the callback-only type.
## Out of scope
Canonical messages, future `RunAgentInput.messages`, render props,
message identity, stream ordering, snapshots, transformed chunks,
persistence, GraphQL, legacy React, Vue, Angular, and standardized trace
semantics remain outside this slice.
## Related PRs and Issues
Addresses #3039.
The callback-only scope follows
https://github.com/CopilotKit/CopilotKit/issues/3039#issuecomment-5086936452.
Related trace-correlation contract: #4634.
## Test plan
- [x] StateManager sidecar tests, 10 passed. Covers direct capture,
falsey values, replacement, scope isolation, cleanup, snapshots, and
chunks.
- [x] React v2 feedback tests, 4 passed. Covers real callback routing,
canonical and outbound cleanliness, render identity, and flat/virtual
paths.
- [x] Full package suites, 625 core tests, 1,475 React Core tests, and 2
script tests passed.
- [x] Typecheck, formatting, lint, and whitespace validation passed;
lint reported five pre-existing warnings.
- [ ] CI green (`static / quality`, `test / unit` on Node 20/22/24).
## Notes
The clean-base behavioral half of the reproduction remains unproved
because temporary worktree setup hung behind unrelated Git processes.
The PR makes no base execution claim for that half.
## What does this PR do?
Makes the existing Vue tool-call memoization lint-valid without changing
rendering behavior.
The existing `v-memo` placement on the fallback renderer inside the
tool-call loop violates the `vue/valid-v-memo` placement constraint.
This refactor introduces a Vue-valid component boundary while preserving
the optimization contract:
- Named `#tool-call-<toolName>` and generic `#tool-call` consumer slots
remain reactive.
- Only the registered fallback renderer remains memoized.
- The fallback memo boundary matches the React counterpart's
renderer-level optimization.
The focused tests act as behavior-preservation and regression guards for
slot updates and fallback rerender prevention.
## Related PRs and Issues
- None.
## Verification
- `CI=1 pnpm exec nx run @copilotkit/vue:test -- --run
src/v2/components/chat/__tests__/CopilotChatToolCallsView.test.ts
--reporter=dot` — 14/14 passed.
- `CI=1 pnpm exec nx run @copilotkit/vue:check-types` — passed.
- `CI=1 pnpm exec nx run @copilotkit/vue:build` — passed.
- Direct ESLint from `packages/vue` on all touched source/test files —
passed.
- `git diff --check upstream/main...HEAD` — passed.
- `CI=1 pnpm exec nx run @copilotkit/vue:lint` remains blocked by 172
pre-existing errors in unrelated files; no package-wide lint cleanup is
included.
- The broad commit-hook suite encountered an unrelated SSR timeout; the
final tree was not changed afterward.
Coverage preserves generic and named slot updates, unchanged fallback
rerender prevention, tool-name changes, agent-specific renderer
selection, status/result behavior, and renderer precedence.
## Scope and exclusions
This is limited to the Vue tool-call rendering boundary, its parity
note, and focused tests. It does not change React behavior, package-wide
lint errors, attachment work, or unrelated rendering paths.
## Checklist
- [x] Contribution guide and package instructions reviewed.
- [x] Relevant Vue parity documentation updated.
- [x] Allow edits by maintainers is enabled.
Refs [OSS-888](https://linear.app/copilotkit/issue/OSS-888).
## The failure
A correctly assembled v2 integration 404s on its first browser request
while every static check passes and `GET /info` returns 200.
`packages/react-core/src/v2/index.ts:28` re-exports the **v1-compat**
`CopilotKit` wrapper, so it is the provider most integrations reach for.
That wrapper pinned:
```tsx
useSingleEndpoint={props.useSingleEndpoint ?? true}
```
which overrode the core's `"auto"` negotiation and forced single-route
transport. But **every** v2 handler defaults to `mode: "multi-route"`
(`endpoints/hono.ts:95`; `createCopilotEndpoint` is an alias at `:90`).
Nothing serves the single-route envelope the client sends, so the
runtime 404s while the provider looks connected.
## What this is *not*
The library defaults do not actually disagree. `CopilotKitProvider` (the
real v2 provider) leaves the flag undefined → `"auto"`, which probes
`GET /info` and falls back to the single-route envelope
(`core/agent-registry.ts` `fetchRuntimeInfoAutoDetect`) — it works
against **either** handler mode. Only the compat wrapper defeated that.
So this is one line of override, not a defaults mismatch needing a
direction chosen.
## Why four onboarding runs hit it, not one
The library bug alone doesn't explain a 100% failure rate. The shipped
`react-core` skill does:
`packages/react-core/skills/react-core/references/provider-setup.md` —
bundled in the npm tarball (`files: ["dist","skills"]`) — **mandated**
the compat wrapper, **forbade** `CopilotKitProvider` as "a subset of the
functionality", and mentioned `useSingleEndpoint` **zero times** across
~10 code samples. An agent following it wrote the 404 configuration
every time.
Meanwhile `skills/copilotkit-setup/SKILL.md` got it right, so the two
shipped skills contradicted each other and nothing gated either against
the code.
## The change
**Commit 1 — the library fix.** The prop already arrives through
`v2Props`, so dropping the override lets it stay `undefined` and inherit
`"auto"`. An explicit `useSingleEndpoint` still wins in both directions.
**Commit 2 — the docs and skills.** Correcting the default made ~15
pages' explanations false. Code samples that pass `{false}` stay valid
(they pin what negotiation would find anyway), so this corrects the
*explanations* rather than the samples — keeping every page true both
before and after release. Includes dropping the now-false causal claim
from the single-route-envelope diagnostic added in #6579.
## Compatibility
Safe for existing v1 apps. A v1 app on a single-route-only handler
(`copilotRuntimeNextJSAppRouterEndpoint` and friends) now does one `GET
/info` that 404s, then falls back to single-route and works. Cost is one
extra request on connect.
One edge case worth a reviewer's eye: if a deployment's `runtimeUrl` +
`/info` returns 200 from something that is *not* a multi-route
CopilotKit runtime (a catch-all proxy serving HTML, say), `"auto"` would
resolve to `rest`. Setting `useSingleEndpoint` explicitly remains the
escape hatch.
Conventional-commit note: this lands as `fix`, but it *does* change a
public default. Flag if you'd rather it carried a minor bump.
## Tests
- New `copilotkit-transport-default.test.tsx` — omitted → `"auto"`,
`{true}` → `"single"`, `{false}` → `"rest"`. Confirmed RED first
(`expected 'single' to be 'auto'`).
- `CopilotChat.readinessGate.test.tsx` depended on the old default to
avoid a REST probe. Single-route transport is a **precondition of that
fixture**, not the behaviour under test, so it now pins the flag
explicitly and its stale comments are corrected. Its coverage (readiness
gate across the real SSE boundary) is unchanged.
- `react-core` 1512 passed · `runtime` 2073 passed · `core` 668 passed.
- `pnpm check:plugin-skills` in sync (`skills/react-core/` is the
generated mirror).
`showcase/shell-docs`'s own vitest suite fails to load 35 files with
`Cannot find package 'react/jsx-dev-runtime'` — reproduced identically
on unmodified `origin/main`, so it is environmental in this checkout and
unrelated. All 183 tests that do run pass.
## Not addressed here
Nothing gates a shipped skill against the code it documents, which is
why `provider-setup.md` could contradict both the library and the
sibling skill indefinitely. Worth its own ticket.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## What does this PR do?
Closes the naming and documentation half of
[OSS-881](https://linear.app/copilotkit/issue/OSS-881). Paired with
CopilotKit/Intelligence#890, which adds `copilotkit verify` and tightens
the evaluation rubric.
### 1. One name for the Intelligence key
**Three** names for one value were live in CopilotKit's own
documentation, and following the wrong one with a CLI-provisioned
project yields an undefined key:
| Name | Where | Code readers |
| --- | --- | --- |
| `INTELLIGENCE_API_KEY` | what `copilotkit project select` writes; all
34 integration examples; the docs site | 34 |
| `COPILOTKIT_INTELLIGENCE_API_KEY` | 7 Channels package READMEs +
packaged skills | **0** |
| `COPILOTKIT_API_KEY` | `examples/slack`, `examples/teams`, and the
TSDoc on `CopilotKitIntelligence` itself | 2 |
`INTELLIGENCE_API_KEY` wins — it is the name the CLI provisions, and
changing it would break every scaffolded project in the wild.
- `COPILOTKIT_INTELLIGENCE_API_KEY` is **retired outright**. Nothing
ever read it, so there is nothing to keep compatible.
- `COPILOTKIT_API_KEY` stays **readable as a deprecated alias** in the
two examples that consume it, so an existing `.env` keeps working, and
is documented as deprecated everywhere it appears.
The third name was the worst placed: it was in the TSDoc on
`CopilotKitIntelligence`, which is what an IDE shows on hover.
This was not only untidy. The CLI's own `channels-preflight` accepts
`INTELLIGENCE_API_KEY` or `COPILOTKIT_API_KEY` — **not**
`COPILOTKIT_INTELLIGENCE_API_KEY`, the name the Channels READMEs told
people to set. So following a Channels README verbatim made `copilotkit
channels` warn that no runtime API key was present while the key sat
visibly in `.env`. After this PR the documented name is one preflight
accepts.
> [!NOTE]
> `NEXT_PUBLIC_COPILOTKIT_API_KEY` is a **different value** — the legacy
Copilot Cloud public key — and is deliberately left alone.
### 2. A real defect, not just naming skew
`skills/runtime/references/intelligence-mode.md` documented
`organizationId` as a `CopilotKitIntelligence` option, sourced from two
further env names (`COPILOTKIT_INTELLIGENCE_ORG_ID`,
`COPILOTKIT_ORG_ID`).
`CopilotKitIntelligenceConfig` has no such field — the copy-pasteable
sample it appeared in **would not compile**. Removed from the samples,
and the prose telling readers to fetch a value for it corrected. That
file is the only place those two names ever existed, which is very
likely why the failing validation run reported that "the runtime reads
`COPILOTKIT_INTELLIGENCE_API_KEY` and `COPILOTKIT_INTELLIGENCE_ORG_ID`".
### 3. Publish the Intelligence wiring
The wiring instructions existed only inside
`node_modules/@copilotkit/runtime/skills/`, and the only docs pages
mentioning `CopilotKitIntelligence` at all were the two Channels
frontends — so a developer on the plain web path had no page to reach it
from.
Adds **`/premium/connect-your-runtime`**: the wiring itself, how to
confirm the credential is actually consumed, the self-hosted
both-URLs-or-neither rule, and a troubleshooting table. Linked into both
navs, and the skills reference now points at the published page.
### 4. A guard so it cannot drift back
`scripts/validate-intelligence-env-names.ts` (`pnpm
check:intelligence-env-names`), wired to lefthook and a new workflow.
The workflow is **intentionally unfiltered**. The two workflows that
would otherwise cover this both filter: `plugin-skills-check` by
`paths:`, and `static/quality` by `paths-ignore: examples/**` — which is
exactly where the deprecated alias lives. Scoping the job would re-open
the hole it exists to close. Legitimate alias sites live in
`ALIAS_ALLOWLIST`.
## Related PRs and Issues
- [OSS-881](https://linear.app/copilotkit/issue/OSS-881) — needs
**both** PRs; neither closes it alone
- CopilotKit/Intelligence#890 — items 1 and 4 (`copilotkit verify` +
rubric contract 1.3.0)
## Verification
- Full lefthook pre-commit ran green: `check-plugin-skills`, `lint-fix`,
the new `check-intelligence-env-names`, and `test`/`publint`/`attw`
across **25 projects**.
- `examples/slack` `managed.test.ts` extended to cover **both** the
canonical name and the alias fallback, and proven non-vacuous — removing
the fallback turns the new test red.
- The drift guard proven non-vacuous the same way: reintroducing a
retired name fails it, exit 1.
- `oxfmt` and `oxlint` clean on every file touched (0 errors).
## 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
🤖 Generated with [Claude Code](https://claude.com/claude-code)
The compat `<CopilotKit>` wrapper no longer pins `useSingleEndpoint` to `true`,
so every statement that it "defaults to single-route" or that a multi-route
backend "needs `{false}`" is now wrong. Code samples that pass `{false}`
explicitly stay valid — they pin what negotiation would find anyway — so this
corrects the explanations rather than the samples, keeping the pages true both
before and after the release.
The shipped `react-core` skill is the load-bearing one. `provider-setup.md`
mandated the wrapper, forbade `CopilotKitProvider` as "a subset of the
functionality", and never mentioned `useSingleEndpoint` across ~10 samples — so
an agent following it wrote the 404 configuration every time. It now documents
the transport and stops steering readers off the negotiating provider.
Also drops the false causal claim from the runtime's single-route-envelope
diagnostic (added in #6579), which named the wrapper's old default as the cause.
`skills/react-core/` is the generated mirror of `packages/react-core/skills/`,
synced with `pnpm sync:plugin-skills`.
Refs OSS-888.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The `CopilotKit` wrapper is re-exported from `@copilotkit/react-core/v2`
(`v2/index.ts`), so it is the provider most integrations reach for. It pinned
`useSingleEndpoint={props.useSingleEndpoint ?? true}`, which overrode the core's
`"auto"` negotiation and forced single-route transport.
Every v2 handler defaults to `mode: "multi-route"`, so the pinned default made
the first browser request 404 while `GET /info` still returned 200 and looked
healthy. Four independent onboarding runs hit it and all four fixed it the same
way, with `useSingleEndpoint={false}`.
The prop already arrives through `v2Props`, so dropping the override lets it
stay `undefined` and resolve to `"auto"` — probe `GET /info`, fall back to the
single-route envelope — which works against either handler mode. An explicit
`useSingleEndpoint` still wins in both directions.
`CopilotChat.readinessGate.test.tsx` depended on the old default to avoid a REST
probe. Single-route transport is a precondition of that fixture rather than the
behaviour under test, so it now pins the flag explicitly and its comments are
corrected.
Refs OSS-888.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
## What does this PR do?
- Uses each `RUN_STARTED.runId` during Runtime SSE connect replay.
- Preserves the first run association when later message snapshots are
cumulative.
- Keeps live message events able to correct an earlier provisional run
association.
- Adds `/connect` and StateManager regression coverage for multiple
server runs.
## Why?
A single `/connect` stream can contain multiple runs. This affects
custom Runtime streams and the built-in in-memory runner, which replays
historic runs through one reconnect stream. StateManager previously
stored replayed state under the connection input ID and reassigned
earlier snapshot messages to the latest run.
## Related PRs and Issues
- Closes#6252
## Validation
- `@copilotkit/core` tests: 59 files, 661 tests passed
- `@copilotkit/core` type check
- Pre-commit lint, test, publint, attw, and commitlint
## Checklist
- [x] I have read the Contribution Guide
- [x] Documentation is not required for this internal bug fix
- [x] Allow edits by maintainers is enabled
Folded into `properties`, they arrived in the per-event slot. That works and it
is the wrong place: the sink treats `global_properties` as the pass-through bag
for `oss.runtime.*` and spreads it into the analytics event, and v1's client
sends package name and version there for the same reason.
Sending them as their own field keeps a process-level fact separable from an
event's own properties the whole way to the warehouse.
It also moves conflict resolution. Two fields cannot collide in the SDK, so a
shared key survives on both and the sink decides, spreading the global bag last
and therefore letting the global win. That is the opposite of what most readers
expect from the word global, so the field docs now say not to reuse a key an
event already sets, and a test pins the behaviour rather than leaving it to be
discovered.
The v2 telemetry client sends exactly the properties each call site passes, so
there is no way for a product built on this runtime to be told apart in the
events that already go. The only route open to one was to send its own events,
which is a second pipeline describing the same runs.
`telemetryProperties` on the runtime is merged into every event. Set beside the
license token and for the same reason: it describes the caller rather than the
call, so every event should carry it whichever handler fired.
Per-event properties win on conflict. A call site describing one event knows
more than a value set once at construction, and letting the general overwrite
the specific would be the wrong way round.
No behaviour change when unset, and nothing is sent when telemetry is off, so
this adds no egress on its own.
Closes
[OSS-882](https://linear.app/copilotkit/issue/OSS-882/add-to-existing-journeys-reach-for-the-v1-compat-copilotkit-wrapper).
## The failure
The v1-compatible `<CopilotKit>` provider pins `useSingleEndpoint` to
`true`
([`copilotkit.tsx:108`](https://github.com/CopilotKit/CopilotKit/blob/main/packages/react-core/src/components/copilot-provider/copilotkit.tsx#L108)),
so its startup handshake POSTs `{ method: "info" }` at the base path. A
multi-route runtime — the default — matches no route for that path and
answered a bare `{"error":"Not found"}`, indistinguishable from a wrong
`basePath` or an unmounted handler.
Two independent onboarding validation runs hit this on their first
browser attempt and each had to guess the cause. Both were
*add-to-existing-app* journeys; the greenfield one reached for
`CopilotKitProvider` and never saw it.
## What changed
**The runtime says what happened.** `detectSingleRouteEnvelope`
recognises a POST whose JSON body carries a `method` the single-route
endpoint accepts, and the multi-route handler uses it at the one point
routing gives up. The 404 now carries a `code` and a message naming the
prop, plus a `logger.warn` so it lands in the dev-server terminal too.
Deliberately conservative — wrong verb, non-JSON, unknown method, or a
JSON POST that isn't an envelope all stay ordinary 404s, unchanged in
status and shape.
**The client stops discarding it.** All four `/info` callers (two in
`agent-registry.ts`, two in `agent.ts`) threw away the response body and
reported only the status, so a server-side diagnosis reached nobody.
They now go through `runtimeInfoError`, which folds a string `message`
from the body into the thrown error. Any future server-side diagnosis
reaches the developer for free.
**Docs.** Five pages paired a v2 multi-route handler with `<CopilotKit>`
and never mentioned the prop. Rather than a warning under a snippet that
is still wrong to copy, the snippets themselves now pass
`useSingleEndpoint={false}`, with a short callout linking to the
provider/handler mapping.
Two pages were deliberately left alone: `backend/runtime-endpoints.mdx`
already documents the pairing in full, and `cookbook/arcade.mdx` uses
`mode: "single-route"` on purpose and already explains it.
`backend/copilot-runtime.mdx` keeps its snippet as-is — it pairs with
the v1 endpoint, where the default is correct — and gains the caveat
only on its "switch to v2 handlers" note.
Option 3 in the issue (reconsidering the compat default) is **not** in
this PR.
## Testing
### Both halves connect, end to end
Real `createCopilotRuntimeHandler` + real `CopilotKitCore` configured
the way the v1 wrapper configures it — no mocks on either side:
```
code : runtime_info_fetch_failed
message: Runtime info request failed with status 404: Received a single-route
request envelope ({ method: "..." }) but this runtime is mounted in
multi-route mode, so the request matched no route. If the frontend uses
<CopilotKit> from @copilotkit/react-core/v2, pass useSingleEndpoint={false}
— that provider defaults it to true. Otherwise mount the runtime with
mode: "single-route" to serve this envelope.
PASS — the diagnostic reached the client
```
The server-side `logger.warn` fired in the same run, carrying `{ url,
path, method: 'info' }`.
### Unit tests
`packages/runtime` — `single-route-envelope-diagnostic.test.ts` (2
positive, 5 control):
```
✓ src/v2/runtime/__tests__/single-route-envelope-diagnostic.test.ts (7 tests) 26ms
Tests 7 passed (7)
```
`packages/core` — `runtime-info-error-detail.test.ts` (2 positive, 5
control):
```
✓ src/__tests__/runtime-info-error-detail.test.ts (7 tests) 267ms
Tests 7 passed (7)
```
### Mutation checks
Every new test was verified to fail when its mechanism is broken, in
both directions.
Detector forced to `return null` — the two positives die, the four
controls hold:
```
× names useSingleEndpoint when the envelope is an info call
× diagnoses every method the single-route envelope accepts
✓ leaves an ordinary unmatched route as a plain 404
✓ leaves a JSON POST that is not an envelope as a plain 404
✓ leaves an unrecognized method name as a plain 404
✓ does not diagnose a non-JSON POST
```
Detector forced to `return "info"` — the controls die instead, proving
they are not vacuous:
```
✓ names useSingleEndpoint when the envelope is an info call
✓ diagnoses every method the single-route envelope accepts
× leaves an ordinary unmatched route as a plain 404
× leaves a JSON POST that is not an envelope as a plain 404
× leaves an unrecognized method name as a plain 404
× does not diagnose a non-JSON POST
```
`runtimeInfoError` with the detail dropped, then with the `typeof
message === "string"` guard removed — each kills a different pair:
```
mutation: detail dropped → 2 failed | 5 passed
mutation: accept any message field → 2 failed | 5 passed
restored → 7 passed
```
### Full suites, builds, docs
| Check | Result |
|---|---|
| `packages/core` full suite | `Test Files 60 passed (60)` / `Tests 662
passed (662)` |
| `packages/runtime` full suite | `Test Files 142 passed (142)` / `Tests
2067 passed (2067)` |
| `packages/core` `tsc --noEmit` | clean |
| `packages/runtime` `tsdown` | `416 files` — build complete |
| MDX compile, 5 edited pages | all `OK` |
| pre-commit `nx run-many -t test,publint,attw` | passed across affected
projects |
| CI on `f94d1ab0` | 72 pass, 3 skipping, 0 fail |
Both suites are fully green. An earlier revision of this description
reported 6
runtime failures as pre-existing on `main`; they were not. They were
artifacts
of a worktree whose `node_modules` had been assembled by hand, and a
proper
`pnpm install` cleared all of them along with the inspector-metadata
failures
from a stale `@copilotkit/shared` dist. `main` is clean.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Two pages document both transport modes and carry a single "point your
frontend at it" snippet serving every front door on the page. Baking
`useSingleEndpoint={false}` into those snippets traded one silent mismatch for
its mirror image: correct for the multi-route majority, wrong for anyone who
followed the `mode: "single-route"` example.
Both now state the rule conditionally next to the snippet instead of asserting
one side of it. Pages with a single handler mode (auth, custom-agent) are
unambiguous and keep the prop inline.
Also pins the one path where the diagnostic could have cost more than it gives:
`clone()` throws once a before-request middleware has drained the body, so the
detector must return null and let the plain 404 stand rather than surfacing a
500. The guard existed; nothing held it in place.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
HumanInTheLoop.onResult resolved with the whole rxjs bus event
({toolCallId, toolName, result}) instead of the bare result, because
lastValueFrom was not mapped. The bound tool handler returns that promise
directly as the tool's result, and run-handler JSON.stringifies a non-string
return into the tool message content, so agents received
{"toolCallId":...,"toolName":...,"result":{...}} where React sends the bare
value.
A LangGraph agent gating a side effect on a field of the human's answer
therefore reads that field off the envelope, finds nothing, and falls through
silently while the model still reports the action succeeded.
The existing tests asserted the envelope as expected behaviour, which is why
this went unnoticed; they now pin the bare result, plus a case that fails if
the routing keys leak again.
Reported in #6571, which attributes the envelope to @ag-ui/langgraph. It
originates here. The missing ToolMessage.name in that issue is a separate
defect and is not addressed by this change.
## Problem
Fleet-wide "empty assistant response": the assistant-message container
mounts but never receives text. #5801 (first released 1.63.0) deferred
the runtime `/info` call to a React effect, widening the "provisional
agent" window; 1.63.2 exposed an `isReady` signal on `useAgent` but
`CopilotChat` never consumed it. A chat submitted during the provisional
window is committed to the provisional agent and then lost when `/info`
swaps in the real agent — the user message and streamed assistant text
disappear, so the assistant bubble renders empty.
This was confirmed with a controlled SSE A/B: stock 1.68.1 does forward
`TEXT_MESSAGE_START → TEXT_MESSAGE_CONTENT → TEXT_MESSAGE_END` (the
runtime is fine — not the in-memory runner / #5837), but the `/info`
agent swap drops the rendered messages; restoring a readiness guard
makes the identical SSE render correctly.
## Fix
`CopilotChat` now consumes `isReady` from `useAgent` and withholds
`onSubmitMessage` until the runtime is ready:
```
- const { agent } = useAgent({ ... });
+ const { agent, isReady } = useAgent({ ... });
...
- onSubmitMessage: onSubmitInput,
+ onSubmitMessage: isReady ? onSubmitInput : undefined,
```
`CopilotChatInput` already derives `canSend` (and its Enter handler)
from `onSubmitMessage`, so withholding it while not-ready (a) disables
the send control and (b) makes Enter a no-op that **preserves** the
composer text — the message can't be committed to the doomed provisional
agent. No runtime/runner changes; no fixture re-recording.
## Red–green proof
New test `CopilotChat.readinessGate.test.tsx` drives the real readiness
race against the real `CopilotChat` submit path: holds the runtime in
Connecting (deferred `/info`), sends during the provisional window, then
resolves `/info` (the real status-change re-render that flips `isReady`)
and asserts the message survives to render an assistant response.
- **RED** (fix reverted): the chat body contains only chrome text — no
user message, no assistant response (the empty-container symptom).
- **GREEN** (fix applied): assistant text renders; passes 3×
consecutively (deterministic).
- Mutation-verified: reverting the fix reproduces RED.
## Verification
- react-core: **1468 tests pass** (0 regressions; 3 pre-existing
web-inspector `localStorage` jsdom-env file errors are unrelated and
present with and without this change).
- react-ui: **69 tests pass**.
- react-core typecheck (`tsc --noEmit`): **0 errors**.
## Follow-up (not in this PR)
The showcase D4 probe driver
(`showcase/harness/src/probes/drivers/d4-chat-roundtrip.ts`) should wait
for the send control to be enabled before pressing Enter (poll
`[data-testid="copilot-send-button"]` `disabled === false` after
typing). Omitted here because it can't be red-green'd without a live
showcase backend. Note this fix makes the follow-up more relevant: with
send gated, a probe that types + Enters during the provisional window
now silently no-ops.
Ref: #5801🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_017t7HsmM31NHNmUQrHF47pm
Withholding onSelectSuggestion left the pill visually enabled but inert,
silently dropping a click during the provisional (!isReady) window. Hide
the pills until isReady (pass an empty suggestions list so the view's
existing hasSuggestions gate keeps them off-screen); retain the handler
gate as defense-in-depth for custom chatView slots. The suggestion-gate
test now asserts the pill is absent while provisional and appears/works
once ready.
Rework the production-shaped SSE regression to render the real public
CopilotKit wrapper (components/copilot-provider/copilotkit) with
runtimeUrl + agent="agentic_chat", advertising agentic_chat in the mocked
single-endpoint info response and relying on the wrapper's default
useSingleEndpoint=true — removing the synthetic GET /info 404 fallback so
the test exercises the same provider chain and POST info/agent-run path
as Showcase.
Three names for one value were live in CopilotKit's own documentation, and
following the wrong one with a CLI-provisioned project yields an undefined
key:
- `INTELLIGENCE_API_KEY` — what `copilotkit project select` writes, used by
all 34 integration examples and the docs site.
- `COPILOTKIT_INTELLIGENCE_API_KEY` — the seven Channels package READMEs and
the packaged skills. Nothing ever read it.
- `COPILOTKIT_API_KEY` — the Slack and Teams examples, and the TSDoc on
`CopilotKitIntelligence` itself, which is what an IDE shows on hover.
`INTELLIGENCE_API_KEY` wins, because it is the name the CLI provisions and
changing it would break every scaffolded project in the wild.
`COPILOTKIT_INTELLIGENCE_API_KEY` is retired outright — no code read it.
`COPILOTKIT_API_KEY` stays readable as a deprecated alias in the two
examples that consume it, so an existing `.env` keeps working, and is
documented as deprecated everywhere it appears.
The skills reference also documented `organizationId`, sourced from a fourth
and fifth env name, as a `CopilotKitIntelligence` option. It is not one:
`CopilotKitIntelligenceConfig` has no such field, so the copy-pasteable
sample it appeared in would not compile. Removed from the samples, and the
prose that told readers to fetch a value for it corrected.
The Intelligence wiring itself was published only inside
`node_modules/@copilotkit/runtime/skills/`, and the only docs pages showing
`CopilotKitIntelligence` were the two Channels frontends — so a developer on
the plain web path had no page to reach it from. Adds
`/premium/connect-your-runtime`, which covers the wiring, how to confirm the
credential is actually consumed, and the self-hosted two-URL rule.
`scripts/validate-intelligence-env-names.ts` keeps this from drifting back.
It runs unfiltered in CI on purpose: the two workflows that would otherwise
cover it filter paths, and static/quality ignores `examples/**` — exactly
where the deprecated alias lives.
The v1-compatible `<CopilotKit>` provider pins `useSingleEndpoint` to `true`,
so it POSTs `{ method: "info" }` at the base path. A multi-route runtime — the
default — matches no route for that path and answered a bare `{"error":"Not
found"}`, which is indistinguishable from a wrong `basePath` or an unmounted
handler. Two independent onboarding validation runs hit this on their first
attempt and had to guess the cause.
The runtime now recognises the envelope at the one point multi-route routing
gives up, and answers the 404 with a message naming the prop, plus a
`logger.warn` so it also lands in the dev server terminal. Status and shape are
unchanged for every other miss.
That message was reaching nobody: all four `/info` callers threw away the
response body and reported only the status. They now route through
`runtimeInfoError`, which folds a string `message` from the body into the
error — so any future server-side diagnosis reaches the developer too.
Docs: five pages paired a v2 multi-route handler with `<CopilotKit>` without
mentioning the prop. Their snippets now pass `useSingleEndpoint={false}` and
link to the provider/handler mapping. `backend/runtime-endpoints.mdx` already
documents the pairing and is untouched; `cookbook/arcade.mdx` deliberately uses
single-route mode and already explains it.
Closes OSS-882
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Alem Tuzlak