Seven published packages declared `engines.node: ">=18"`, but CI has never
run Node 18 and Node 18 reached end of life on 2025-04-30. The claim
pointed at a runtime nothing tests and that receives no security patches.
Raise those seven to `">=20"`, the lowest version the unit matrix
(20.x, 22.x, 24.x) actually proves, and raise the root manifest to match.
Also give `@copilotkit/runtime` its first `engines` field. It declared
none, while #7089 moved it to pino 10, which drops Node 18. Pino ships no
`engines` of its own, so a consumer on Node 18 installed cleanly and
failed later, at runtime.
Closes#7107
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
## What does this PR do?
Fixes Stop → resend on Intelligence threads.
`IntelligenceAgentRunner.stop()` previously returned `true` after
requesting an abort, while the handler kept renewing the hosted lock.
Agents that ignored abort could keep the thread locked until natural
completion.
Stop now fences late producer events, requests cancellation, and
finalizes the run through the existing event queue. It resolves `true`
only after the gateway acknowledges every queued event and the runner
completes cleanup. The gateway's existing terminal-event handling
releases only that run's lock. Cancellation does not depend on the agent
promise settling; AG-UI subscriptions also detach when the agent
supports it. Delivery rejection, teardown, or the 60-second deadline
cannot report success.
### Compatibility
- No Intelligence or AG-UI server change, new event type, required
capability, dependency bump, or coordinated rollout.
- Existing single-event and batched acknowledgments both work. Older
agents without `detachActiveRun()` retain the cancellation fallback.
- HTTP paths, empty-body requests, single-route envelopes, and response
bodies are unchanged. Missing, mismatched, and duplicate Stop requests
retain `false`.
- The existing optional runner `runId` remains supported. This PR does
not duplicate #6982's HTTP run-selection change.
- Provider cancellation remains best effort; stopping a run cannot undo
external tool effects.
### Validation
- RED: the new legacy/batch transport tests failed because no terminal
event followed a non-cooperative abort. The subscription-cleanup test
separately failed before detachment was added.
- GREEN: 11 new tests exercise real Phoenix WebSocket framing, delayed
terminal acceptance, immediate resend, older agents, throwing aborts,
late events, partial messages/tools, pre-join Stop, rejection, timeout,
and both HTTP route modes. All 2,306 runtime tests and the existing
runner tests pass.
- `pnpm nx run-many -t test,check-types,build,publint,attw
--projects=@copilotkit/runtime --parallel=2` passed again after rebasing
onto current main.
- The 11 new transport and HTTP tests also passed on Node 20.19.4; the
fixture supplies WebSocket only when the Node global is absent.
- The required pre-commit check passed tests and package validation for
nine affected packages. An initial parallel run timed out in the
unrelated SQLite replay test; its isolated rerun passed all 15 tests,
followed by a passing hook with `NX_PARALLEL=2`. No test timeout
changed.
- Focused oxlint and oxfmt checks; `git diff --check`. Oxlint reports
only three existing warnings in the runner and its older test file.
- Local integration: the actual runtime HTTP handler and a gateway built
from Intelligence `a55679d1055ab831930331e64b6129d14e73b613`, with
isolated Redis/PostgreSQL. App API lock acquisition/renewal were
represented by a test adapter over real Redis. Two consecutive streamed
runs stopped in 179 ms and 156 ms; each response followed lock release.
PostgreSQL retained both ordered five-event sequences, one
`RUN_FINISHED` per run, and no `RUN_ERROR`. The fixture included the
current replay-projection migration.
## Related PRs and Issues
Closes#7078.
Related: #6982 (HTTP selection of an exact run).
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Stopping an Intelligence run now waits for terminal confirmation
before completing.
* Stop requests prevent late events and clean up local run
subscriptions.
* Runs can be stopped at different connection stages, including before
channel join.
* Partial text and tool-call streams are properly closed when stopping.
* Stop failures and durability timeouts are surfaced appropriately.
* HTTP Stop endpoint behavior is preserved while waiting for run
completion.
* **Documentation**
* Added guidance on stopping runs, cancellation ordering, failure
handling, and gateway acknowledgments.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Problem
Inspector feature setup prompts included an unnecessary optional
diagnostic-feedback instruction.
## Why
Threads and Learning use this shared feature CTA prompt, so the extra
instruction was copied into their onboarding flow.
## Fix
Remove the instruction from the shared template and assert it is absent
in the navigation test.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Changes**
- Updated the onboarding prompt to retain the instruction not to reveal
credentials.
- Removed the instruction referring to optional diagnostic feedback
reports.
- **Tests**
- Updated onboarding navigation coverage to verify the credential
protection wording and ensure the removed diagnostic feedback wording is
not present.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Problem
The Inspector treated any Threads list endpoint as durable Threads
support. An OSS app using `InMemoryAgentRunner` therefore skipped the
Rich Threads setup CTA even without Intelligence.
## Why
Local thread inspection and Intelligence persistence are separate
capabilities. Developers should be able to inspect ephemeral
conversations without losing the path to durable Threads.
## Fix
- Show the full Rich Threads setup CTA when Threads are unavailable, or
when Intelligence is off and no local threads exist.
- Switch to the thread list when the first ephemeral thread appears,
with a compact “Keep your threads” banner explaining that history can
disappear on restart.
- “Make them permanent” opens the full setup view inside the Inspector.
A sticky “Back to your threads” link returns to local history.
- Remove the banner/setup override when Intelligence becomes available.
Preserve the existing Intelligence-backed empty and populated views.
- Correct the OSS workbench fixture to omit Intelligence, add an
ephemeral-history fixture, and explicitly identify Intelligence-backed
test fixtures.
Validation: production build and type checks pass. Inspector suite:
**700 passed, 3 failed**. All three failures reproduce on untouched main
(`3e86b8d559`) with the same dependencies (baseline: 693 passed, 3
failed): CSS serialization assertions in `inspector-navigation.spec.ts`,
`thread-detail.spec.ts`, and `threads-states.spec.ts`. The pre-commit
package checks ran and failed only on that Inspector test task; the
repeat commit excludes that already-run hook.
Verified in the in-app browser: empty OSS CTA, ephemeral list/banner,
upgrade/back navigation, Intelligence enabled with Threads disabled,
dark theme, and a narrow viewport. Local screenshots are supplied in the
accompanying task.
Workbench: `pnpm exec nx run @copilotkit/web-inspector:dev:standalone`,
then use `oss-no-metadata-enabled-zero`, `oss-ephemeral-existing`, or
`pro-disabled-zero` on port 5177.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **New Features**
- Added support for ephemeral Threads when Intelligence is unavailable.
- Displays an ephemeral Threads banner with an option to make threads
permanent.
- Added navigation back to existing threads from the setup view.
- Keeps the Threads setup view locked when required capabilities are
unavailable.
- Expanded support for additional Threads states and scenarios.
- **Style**
- Added light and dark theme styling for the ephemeral Threads banner
and setup navigation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Provide native Intelligence SDK operations and runtime routes with
application-owned identity, durable runs, A2UI, MCP Apps, entitlements,
Inspector metadata, and telemetry. Include package docs, hosting examples,
and regression tests.
Provide native Intelligence SDK operations and runtime routes with
application-owned identity, durable runs, A2UI, MCP Apps, entitlements,
Inspector metadata, and telemetry. Include package docs, hosting examples,
and regression tests.
Provide native Intelligence SDK operations and runtime routes with
application-owned identity, durable runs, A2UI, MCP Apps, entitlements,
Inspector metadata, and telemetry. Include package docs, hosting examples,
and regression tests.
Provide native Intelligence SDK operations and runtime routes with
application-owned identity, durable runs, A2UI, MCP Apps, entitlements,
Inspector metadata, and telemetry. Include package docs, hosting examples,
and regression tests.
Report failures without private diagnostic payloads in analytics. Preserve
completion counts for streams containing RUN_ERROR and notify clients when
execution fails.
Consume upstream MCP Apps 0.1.0, retain trusted server credentials, and
reject proxy requests outside the selected agent scope. Ordinary runs
without selected servers do not attach middleware.
Validate AG-UI tool arguments against their JSON schemas. Keep relaxed
structured output limited to the open A2UI tool and preserve existing tool
tests.
## Problem
The Inspector locked Threads state varied by license metadata even
though the real availability gate is whether Runtime exposes the Threads
list endpoint. That let users with Threads unavailable land in different
legacy onboarding states.
## Why
License state and Threads capability are separate signals. Keying the
pane on license metadata made Threads unavailable diverge from the
license-disabled setup view, even though neither state can list saved
Threads.
## Fix
- Gate the locked setup view on Runtime Threads capability.
- Use the intended Rich Threads product header, Copy setup prompt,
engineer CTA, and video for every locked state.
- Keep the existing enabled-but-empty Threads preview when the list
endpoint is available.
- Update Inspector docs to describe the capability-based state instead
of removed license-specific variants.
- Simplify the static locked copy and regression coverage.
- Squash the PR into one semantic commit.
The earlier copied-prompt/intent commit was intentionally dropped during
rebase because #7030 landed that work on main.
Validation:
- Inspector: 696 tests passed, 0 skipped.
- Inspector typecheck passed.
- Shell-docs typecheck passed.
- Shell-docs production build passed, including 227 static pages.
- Standalone `pro-disabled-zero` visual check passed.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **User Experience**
* Unified the locked Threads view around Rich Threads setup guidance.
* Added **Copy setup prompt** and **Talk to an Engineer** actions.
* Threads availability is now determined by Runtime capability rather
than license metadata.
* Empty Threads views no longer display local example threads or example
tours.
* **Documentation**
* Updated setup and troubleshooting guidance to describe the
capability-based Threads experience.
* Clarified that Inspector uses action links supplied by Runtime and
directs incomplete configurations to the Runtime route guide.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Problem
`@ag-ui/mcp-middleware@0.0.1` declared `@ag-ui/client` under
`dependencies` at an exact version, so every install of
`@copilotkit/runtime` nested a second copy of the client beside the one
the consumer already had.
That is not only install size. `@ag-ui/client` carries types, and two
copies are two distinct type identities, so a consumer who also declares
`@ag-ui/client` gets a type check that fails on a field unrelated to
either version, naming a private property and their own line rather than
the duplication:
```
error TS2322: Type 'MCPMiddleware' is not assignable to type 'Middleware'.
Types of parameters 'next' and 'next' are incompatible.
Type '…/node_modules/@ag-ui/client…AbstractAgent' is not assignable to type
'…/@ag-ui/mcp-middleware/node_modules/@ag-ui/client…AbstractAgent'.
Types have separate declarations of a private property '_debug'.
```
`0.0.2` (ag-ui-protocol/ag-ui#2689) moves `@ag-ui/client` to
`peerDependencies` at `>=0.0.40`, matching the four sibling middlewares,
so it resolves to the copy the host already has.
## Why this touches three files
The pin bump is one line. The other change is removing this override
from the root `package.json`:
```
"@ag-ui/mcp-middleware>@ag-ui/client": "0.0.53"
```
It was added in c3f7961242 alongside the `0.0.1` dependency — that
commit's own message reads "Add released `@ag-ui/mcp-middleware@0.0.1`
dependency (lockfile + `@ag-ui/client` override)". It was the in-repo
workaround for the hard pin.
With `0.0.2` it is not merely redundant. It forces a stale `0.0.53` onto
a peer this workspace satisfies at `0.0.59`, and the first resolve after
the bump reported exactly that:
```
└─┬ @ag-ui/mcp-middleware 0.0.2
└── ✕ unmet peer @ag-ui/client@0.0.53: found 0.0.59
```
Removing the override clears that line. Unrelated pre-existing warnings
(langchain) are unaffected.
## Testing
**1. The duplicate is gone, verified against the published artifact.** A
real `npm install` of `@copilotkit/runtime@1.71.0` alongside a directly
declared `@ag-ui/client@0.0.59`, with `@ag-ui/mcp-middleware@0.0.2` in
place:
```
node_modules/@ag-ui/client -> 0.0.59
```
One copy. Before the bump the same install produced two, the second
being a nested `0.0.54`.
**2. In this workspace, the lockfile loses exactly one version.**
Comparing resolved `@ag-ui/client` versions against `origin/main`:
```
main: 0.0.36 0.0.42 0.0.51 0.0.53 0.0.57 0.0.59
branch: 0.0.36 0.0.42 0.0.51 0.0.57 0.0.59
removed: 0.0.53
```
The remaining versions are unchanged from main — they come from examples
pinning older published `@copilotkit` packages and are untouched here.
The lockfile is a net 40 lines smaller.
**3. The middleware now shares the host's client.** After a real `pnpm
install`:
```
$ ls -d node_modules/.pnpm/@ag-ui+mcp-middleware@*/node_modules/@ag-ui/client
0.0.59 <- @ag-ui+mcp-middleware@0.0.2_@ag-ui+client@0.0.59_…
```
**4. Clean install.** A full `pnpm install` completes with **zero**
unmet peer warnings (`Done in 38.8s`).
**5. Types.** `nx run @copilotkit/runtime:check-types` passes. This runs
both `tsconfig.json` and `tsconfig.check.json`, so test files are
covered — relevant because `packages/runtime` imports `MCPMiddleware` at
`channel-manager.ts:21` and `agent-utils.ts:5`, and a test mocks the
module:
```
NX Successfully ran target check-types for project @copilotkit/runtime and 22 tasks it depends on
```
**6. Pre-commit suite.** `test`, `publint` and `attw` across 25 projects
and 27 dependent tasks: `Successfully ran targets`.
## Notes
No changeset: the release goes through workflow scopes.
This install only works today because #7093 added
`@ag-ui/mcp-middleware` to the `minimum-release-age` exemptions. `0.0.2`
is hours old, and without that exemption pnpm hard-fails:
```
ERR_PNPM_NO_MATURE_MATCHING_VERSION Version 0.0.2 (released 1 minute ago) of
@ag-ui/mcp-middleware does not meet the minimumReleaseAge constraint
```
This closes the middleware half of the duplicate-tree problem. The
larger half — CopilotKit's own exact `@ag-ui/client` pins, which still
nest a copy per package whenever a consumer declares a different version
— is #6782.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Chores**
- Updated the runtime component to a newer maintenance release.
- Streamlined package configuration by removing an outdated version
override.
- Updated release validation to keep package installation settings
consistent.
- Expanded release handling for additional middleware packages.
- No user-facing functionality or public API changes are included.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
**Draft.** Pairs with Intelligence
[#1196](https://github.com/CopilotKit/Intelligence/pull/1196)
(OSS-1157), which is also open. Neither has to land first — see
*Ordering*.
## What changes
The prompt a developer copies — from the Inspector, the docs hero, the
feature cards — opened with two sentences of instruction to the coding
agent.
**Before**
> Identify which coding-agent product you are, using a short slug such
as `codex` or `claude-code`. From the root of the project where you want
CopilotKit, run `npx --yes copilotkit@latest onboard start --run
<run-id> --coding-agent <coding-agent-slug>`. Follow the Markdown
instructions it prints until onboarding is complete.
**After**
> Help me get started with CopilotKit. Run this command and follow the
instructions:
>
> `npx --yes copilotkit@latest onboard start --run <run-id>`
Identification moves into the prompt graph, which is the surface that
talks to the agent for the rest of the run: `onboard identify
--coding-agent <slug>`, run by `authenticate/start`.
Sites updated, kept byte-identical with Intelligence's own
`createCodingAgentOnboardingPrompt`:
- `packages/web-inspector/src/lib/onboarding-prompt.ts` —
`ONBOARDING_PROMPT_TEMPLATE` and `FEATURE_ONBOARDING_PROMPT_TEMPLATE`
- `showcase/shell-docs/src/lib/intelligence-onboarding-prompt.ts` —
`INTELLIGENCE_ONBOARDING_PROMPT` and `createFeatureSetupPrompt`
## What the feature prompts keep
Their standing permission for the CLI session check stays: *"If it
requires a CopilotKit CLI session check, you have permission to run it.
Never reveal credentials or send optional diagnostic feedback reports."*
That sentence is the developer granting something by copying the text,
and the graph cannot grant it to itself. Only the identification half is
cut.
## Ordering
No lockstep. The CLI still accepts `--coding-agent` on `start`, so the
old wording keeps working, and the new wording works against the
published CLI today because `--run` alone was always valid. Either
repository can merge first.
## Verification
| Suite | Result |
|---|---|
| `packages/web-inspector` — `onboarding-prompt.test.ts` | 11 passed |
| `packages/web-inspector` — `inspector-navigation.spec.ts` | 22 passed
|
| `oxlint` + `oxfmt --check` on the changed files | clean |
| pre-commit hook (`lint-fix`, env-name check, `test,publint,attw` over
5 affected packages) | ran on commit |
**Not run locally:** the `showcase/shell-docs` suites. That package
installs with npm separately from the pnpm workspace, so its `react`
does not resolve in a fresh worktree. Its assertions are updated in this
diff (`hero-onboarding-prompt-button`, `learning-setup-prompt`,
`rich-threads-setup-prompt`, `learning-setup-docs`,
`rich-threads-setup-docs`) and CI covers them — that is the main thing
to watch before this leaves draft.
## Still to do before undraft
- Confirm shell-docs CI is green.
- The marketing site has a fifth copy of this prompt, inline in
`src/components/home/copy-onboarding-prompt-button.tsx`. Separate draft
PR on `CopilotKit/website`.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Improvements**
- Simplified onboarding prompts by removing the requirement to identify
or provide a coding-agent slug.
- Onboarding commands now start directly with the setup run or selected
feature intent.
- Updated prompts to provide clearer setup instructions and more concise
session-check guidance.
- Refined credential-safety messaging to clearly warn users never to
reveal credentials or send optional diagnostic reports.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
`@ag-ui/mcp-middleware@0.0.1` declared `@ag-ui/client` as an exact
dependency, so every install nested a second copy of the client beside the
one the consumer already had. Because `@ag-ui/client` carries types, two
copies are two distinct type identities, and a consumer passing a value
into `CopilotRuntime` hit a type error naming a private `_debug` field and
their own line rather than the duplication.
`0.0.2` (ag-ui-protocol/ag-ui#2689) moves `@ag-ui/client` to a peer at
`>=0.0.40`, matching the four sibling middlewares, so it resolves to the
copy the host already has.
This also removes the `@ag-ui/mcp-middleware>@ag-ui/client` override. That
override was added in c3f7961242 alongside the `0.0.1` dependency, as the
in-repo workaround for the hard pin. With `0.0.2` it is not just redundant:
it forces a stale `0.0.53` onto a peer the workspace satisfies at `0.0.59`,
and the first resolve after the bump reported that as an unmet peer.
The lockfile loses exactly one `@ag-ui/client` version, `0.0.53`. The other
resolved versions are unchanged from main.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
## What does this PR do?
v2 MCP `sse` servers accepted a `headers` auth map on `mcpServers` (the
documented `Authorization: Bearer …` example) but never put those
headers on the wire.
`SSEClientTransport`'s second argument is `SSEClientTransportOptions`,
not a raw header map. Passing `{ Authorization: "…" }` matches none of
`authProvider` / `requestInit` / `eventSourceInit` / `fetch`, so the SDK
ignored it. Auth-required servers then 401'd, and the run skipped the
server (`MCP server … failed to connect — skipping it for this run`) —
the agent just had no tools.
This wraps `serverConfig.headers` as `{ requestInit: { headers } }`,
matching the HTTP transport's options-object pattern. No public type
change: `MCPClientConfigSSE.headers` stays as documented.
Adds a small regression test that stands up a local HTTP listener and
asserts the outbound SSE request carries `Authorization: Bearer
SENTINEL-TOKEN`.
Verified locally:
```
nx run @copilotkit/runtime:test -- src/agent/__tests__/mcp-servers-integration.test.ts
# 10 tests passed
```
No changeset: this repo migrated off Changesets; CI fails on new
`.changeset/*` files. The conventional commit subject is the release
note.
Intended for upstream `CopilotKit/CopilotKit` `main`:
https://github.com/CopilotKit/CopilotKit/compare/main...Zsanz3:CopilotKit:cursor/fix-mcp-sse-headers-22fc?expand=1
## Related PRs and Issues
- Fixes#6927
## 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 (no docs change — this is a bugfix of documented
behavior)
- [x] "Allow edits by maintainers" is checked (lets us help iterate on
your PR directly — faster turnaround for everyone)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Bug Fixes**
* Fixed SSE-based MCP connections so configured authorization and other
request headers are correctly sent.
* Added coverage to verify authenticated SSE connections complete
successfully without runtime errors.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
The prompt a developer copies from the Inspector, the docs hero and the feature
cards opened with two sentences of instruction to the coding agent: identify
yourself with a slug, and pass it as a flag. It is the one piece of text a human
reads, decides on and pastes, and most of it was addressed to something else.
Help me get started with CopilotKit. Run this command and follow the
instructions:
npx --yes copilotkit@latest onboard start --run <run-id>
Identification moves into the prompt graph, which is the surface that talks to
the agent for the rest of the run: `onboard identify --coding-agent <slug>` is
run by `authenticate/start` (Intelligence OSS-1157). The CLI still accepts
`--coding-agent` on `start`, so this wording and the old wording both work and
neither repository has to land first.
The feature prompts keep their standing permission for the CLI session check.
That sentence is the developer granting something by copying the text, and the
graph cannot grant it to itself, so only the identification half is cut.
Kept byte-identical across the Inspector template, the docs constant, and
Intelligence's own `createCodingAgentOnboardingPrompt`.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Follow-up asks from Ben's review, plus a version alignment:
- Add codeSplitting: false to the activity UMD build (matching a2ui-renderer), so
it emits a single self-contained activity.umd.js. Without it a sibling chunk
could leave the CopilotKitMcpAppsRendererActivity global incomplete, and
es-check (syntax-only) would not catch it.
- Run attw as two analyses instead of a package-wide suppression: the root
entry with the esm-only profile (it wraps the ESM-only ext-apps bridge, so its
CJS resolution is intentionally absent while ESM and type checks stay active),
and the remaining entries with node16. This keeps no-resolution enforced on
every other entry point instead of silencing the rule for the whole package.
- Bump the package version 1.70.1 to 1.71.0 to match the shared-version monorepo
scope, and regenerate the public API manifest.
## Problem
A developer on the Learning pane clicks **Copy setup prompt** and gets a
prompt for **Threads**.
Three sites hard-coded the Threads tile as the feature target on a pane
whose own `serviceId` is `memory`:
- `handleLearningSetupCopy` called
`getHomeFeaturePromptTarget("threads")`.
- the locked Learning overview passed `setupPrompt: { serviceId:
"threads" }`.
- `cpk-learning-view`'s `.setupPrompt` was built from `"threads"`.
The mislabelling reached the reader, not just the internals: the
button's `aria-label` and its live-region announcement both read
"Threads setup prompt copied" under the heading "Turn every interaction
into reusable context." After #7004 moved these buttons onto the CLI
intent routes, the copied text read `--intent add-rich-threads` —
equally wrong, on the same three lines.
#7004 left them alone on purpose, because the target looked like a
product decision rather than a naming slip.
## Why it is a bug and not a flow
Threads-first was the defensible reading: Learning needs threads, so
send the developer to set up Threads first. Three checks say that
premise is false.
1. **Learning works with no thread routes at all.** A runtime mounted
`mode: "single-route"` serves no `threads/*` route, and Learning still
binds Containers — the binding happens server-side while a run starts,
in the Intelligence run handler, independent of the mount. Intelligence
PR #1198 proves a full round trip and Container assignment on exactly
that shape.
2. **The Inspector does not gate it.** `learningOn` reads the `memory`
tile and `threadsOn` reads `threads`, independently. Nothing conditions
one on the other.
3. **The route does not require them.** `feature/learning/start.md`
lists existing thread routes among the things it *inspects*; its only
hard stop is a project with no CopilotKit app.
So the target was the bug. The intent table in `onboarding-prompt.ts`
already maps `memory` to `add-learning`, and its comment already says
why — the tile is the Learning tile, enabled by a configured Learning
Container, "which is exactly what `feature/learning` sets up". These
three call sites were the leftover.
Pointing at `add-learning` is also the more robust answer: that route
inspects its own prerequisites and refuses cleanly through
`feature/stop` when one is missing, instead of this pane hard-coding a
guess at which prerequisite matters.
## Evidence
RED first. Two existing tests pinned the wrong behavior by asserting the
Learning preview's button is the `"threads"` one; inverted to
`"memory"`, they failed with `expected null not to be null` — the
Learning button did not exist. They now also assert what actually
reaches the clipboard (`--intent add-learning`) and that the accessible
label says Learning rather than Threads.
```
@copilotkit/web-inspector test 697 passed (38 files)
@copilotkit/web-inspector check-types clean
oxfmt --check on both changed files clean
```
## What is deliberately unchanged
- `renderThreadsView` keeps its own `serviceId: "threads"`. It is the
Threads pane.
- The Home Threads tile keeps its target, and its test still reaches it
through `clickHud("threads")`.
- `inspector-metadata.spec.ts`'s Threads-tab assertion is untouched for
the same reason.
Only the Learning pane borrowed the Threads target, and only that
borrowing is removed.
Closes OSS-1151.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Bug Fixes**
* Updated the Learning setup prompt to target the correct Learning
feature.
* Copied setup instructions now provide Learning-specific configuration.
* Updated the setup prompt button’s accessibility label to identify
Learning correctly.
* Learning onboarding no longer requires the Threads feature.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
The Learning pane's button now reads "Copy setup prompt for Learning", because
it asks for the Learning tile rather than borrowing the Threads one. Five
Playwright specs waited on the old accessible name and timed out.
Four of the five belong to Learning. The fifth is the Threads pane: "guides an
unavailable Threads runtime through setup instead of showing a dead end"
asserts a Rich Threads overview iframe beside the button, and it keeps the
Threads label. A blanket rename over the file had taken that one too, and the
browser run is what caught it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
## What
Replaces nine packaged knowledge skills with two entry points.
| | |
| --- | --- |
| `copilotkit` | The `copilotkit-docs` MCP server: four search tools and
two explore tools, which corpus answers which question, and the
instruction not to answer from memory. |
| `copilotkit-cli` | The CLI, led by `copilotkit verify --json`. |
**Deleted:** `copilotkit-setup`, `copilotkit-develop`,
`copilotkit-integrations`, `copilotkit-debug`, `copilotkit-upgrade`,
`copilotkit-agui`, `copilotkit-contribute`, `copilotkit-self-update`,
and the three package-generated skills (`react-core`, `runtime`,
`a2ui-renderer`).
Net: **-28,851 / +335 lines.**
**Kept, and out of scope here:** `setup-slack-channel`,
`channels-setup`, `copilotkit-channels`, `inspector-docs`,
`inspector-workbench`, `intelligence-docs`. The first three are
procedures rather than knowledge; the last three are internal
maintenance, not part of the public product. Their disposition is a
separate call.
## Why
The packaged skills had become a second copy of the documentation, and a
copy goes stale silently.
- `runtime` and `react-core` were roughly 60% transcribed API surface.
Of the remaining "Common Mistakes" prose, most already existed on a docs
page.
- Four claims in the deleted skills contradicted the source they cited.
One of them reached a shipped PR (#7005) before it was caught, and had
to be corrected in `14231a6169` — the skill asserted that server tools
cannot render UI because the browser never sees a tool-call start event,
which `packages/runtime/src/agent/index.ts:1519,1584` contradicts.
- `copilotkit-debug` was 1,289 lines of hand-written triage. Since
#1180, `copilotkit verify` covers version skew, CORS, and transcription
directly, which is most of what those lines described.
- Nothing in telemetry or in the issue tracker suggests the
per-lifecycle split was load-bearing for anyone.
The gotchas worth keeping were moved onto docs pages first, in #6993,
#6997 and #7021's predecessors, so this PR removes rather than discards.
## Also in this PR
- `skills` dropped from the `files` field of `@copilotkit/react-core`,
`@copilotkit/runtime` and `@copilotkit/a2ui-renderer`, so the tarballs
stop carrying a copy.
- `RESERVED_LIFECYCLE_SLUGS` in `scripts/sync-plugin-skills.ts` goes
from 14 entries to 8.
- `.claude-plugin/plugin.json` and `marketplace.json` descriptions no
longer advertise the deleted lifecycle.
- `/build-with-agents` (56,393 distinct viewers in 90 days) named three
deleted skills in a table and told the reader to "Use the
copilotkit-setup skill to get started". Rewritten for the two-skill
model.
- `README.md` and the two stale cross-references in
`copilotkit-channels/SKILL.md` updated.
- One dead `skills/copilotkit-setup/SKILL.md` entry removed from
`ALIAS_ALLOWLIST` in `scripts/validate-intelligence-env-names.ts`.
`scripts/__tests__/public-skill-drift.test.ts` guarded specific wording
inside files that no longer exist. It is now a link guard instead: every
`docs.copilotkit.ai` path a packaged skill names has to resolve to a
page in this repo, and the two entry points have to stay free of a
transcribed API surface (asserted as: no `sources.md` other than the
channels skill's).
## Supersedes
Closed in favour of this one, with a comment on each: #7017 (the CLI
skill, whose content seeded `copilotkit-cli`), #7021, #7023.
## Needs a decision from someone else
- **#5689** (@onsclom) is a skill-lift eval for `copilotkit-setup`,
which this PR deletes. No file overlap, so it will not conflict, but the
eval target is gone. Austin's call whether to retarget it at
`copilotkit` or drop it.
- **#6636** (community, for #6125) fixes
`packages/react-core/skills/react-core/references/agent-access.md`, the
one file it touches, which this PR deletes. Needs a reply to the author
explaining why, not a silent close.
- **Install-command drift, unresolved.** `README.md` and
`showcase/.../cli/cli.mdx` say `npx copilotkit@latest skills install`;
`/build-with-agents` says `npx skills add CopilotKit/CopilotKit/skills
-y`. Both commands work. Picking one retires a shipped CLI command,
which belongs in the Intelligence repo, so this PR leaves both in place
and changes only the prose around them.
## Testing
The worktree has no `node_modules`, so `lefthook` could not resolve
`tsx`, `oxlint` or `nx` and the commit used `--no-verify`. Every gate
the hook would have run was run by hand against the repo's own binaries,
and the pre-commit failure output was the "command not found" line in
each case, not a gate verdict.
`pnpm check:plugin-skills` — the mirror gate, which also enforces orphan
deletion:
```
$ tsx scripts/sync-plugin-skills.ts --check
plugin skill mirror in sync
```
`pnpm check:intelligence-env-names`:
```
$ tsx scripts/validate-intelligence-env-names.ts
Intelligence env var names and hosts are canonical.
```
Both script suites:
```
$ vitest run scripts/__tests__/public-skill-drift.test.ts scripts/__tests__/sync-plugin-skills.test.ts
Test Files 2 passed (2)
Tests 16 passed (16)
```
**Mutation-checked the new link guard**, so it is not passing for the
wrong reason. Appending `See
[nope](https://docs.copilotkit.ai/this-page-does-not-exist).` to
`skills/copilotkit/SKILL.md`:
```
⎯⎯⎯⎯⎯⎯⎯ Failed Tests 1 ⎯⎯⎯⎯⎯⎯⎯
+ "skills/copilotkit/SKILL.md: /this-page-does-not-exist",
Test Files 1 failed (1)
Tests 1 failed | 3 passed (4)
```
Restored, back to 4 passed. The guard already caught one real mistake of
mine while I was writing the skill: I had linked `/custom-look-and-feel`
from the nav list without checking, and the page is
`/custom-look-and-feel/css`.
`oxfmt` on the four changed TypeScript files: no changes. Both plugin
manifests re-parsed as JSON after editing.
MDX: `build-with-agents.mdx` changes are prose, one table body and one
fence body. Its JSX tag inventory is byte-identical to `origin/main`:
```
$ diff <(git show origin/main:$f | grep -o '</\?[A-Z][A-Za-z]*' | sort | uniq -c) \
<(grep -o '</\?[A-Z][A-Za-z]*' $f | sort | uniq -c) && echo IDENTICAL
IDENTICAL
```
`https://docs.copilotkit.ai/build-with-agents` returns 200, so the new
README link resolves.
Not run: the showcase docs build, which needs the per-entry
`node_modules` symlinks and the pretest generators this worktree does
not have. CI covers it.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **New Features**
- Added `copilotkit` skill for searching current documentation and
source.
- Added `copilotkit-cli` skill for project verification, onboarding,
authentication, scaffolding, and CLI commands.
- Added guidance to use `copilotkit verify` to validate project wiring.
- **Documentation**
- Updated marketplace, plugin, README, and agent-building guidance for
the new skills.
- Updated channel guidance to reference CLI-based setup.
- **Removals**
- Removed legacy setup, development, integration, debugging, upgrade,
contribution, and self-update skills.
- Package distributions no longer include bundled skill documentation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
A developer on the Learning pane clicked "Copy setup prompt" and got a prompt
for Threads. Three sites hard-coded the Threads tile as the feature target on a
pane whose own serviceId is `memory`, so the button's aria-label and its
live-region announcement both read "Threads setup prompt copied" under the
heading "Turn every interaction into reusable context." After the feature
buttons moved onto the CLI intent routes, the copied text read
`--intent add-rich-threads`: equally wrong, on the same three lines.
Threads-first was the defensible reading, and it is false. Learning does not
need the Threads feature. A runtime mounted `mode: "single-route"` serves no
thread route at all and still binds Learning Containers, because the binding
happens server-side while a run starts; `learningOn` reads the `memory` tile
independently of `threadsOn`; and `feature/learning` lists thread routes among
the things it inspects rather than requires.
So the target was the bug, not the labels. All three sites now ask for
`memory`, which the intent table already maps to `add-learning` — and that
route inspects its own prerequisites and refuses through `feature/stop` when
one is missing, rather than this pane guessing at one.
`renderThreadsView` keeps its own `serviceId: "threads"`, and the Home Threads
tile is unchanged: both are genuinely about Threads.
Closes OSS-1151.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
## What does this PR do?
Points the Inspector's seven per-feature "Copy setup prompt" buttons at
the CLI's seven `--intent` feature routes, and retires the prose that
duplicated them.
Intelligence#994 shipped `onboard start --intent <slug>` and seven
feature routes. Nothing emitted the flag, so the only way to reach a
route was to type it by hand — and the Inspector had already solved the
same problem its own way, with a per-feature template of its own. Two
implementations of feature onboarding for the same seven outcomes, and
the routes had no caller at all.
**What changed**
* Home's feature buttons emit `onboard start --run <id> --coding-agent
<slug> --intent <slug>`.
* `homeFeatureImplementationPrompt` is gone. Its body — inspect first,
read the guide, make a plan, implement the smallest change, prove it
works — is what the route already carries, with per-phase check-ins, a
`feature/stop` route for a missing prerequisite, prompts pinned to a CLI
version through `onboarding-graph.lock.json`, and intent-tagged
telemetry on every step. A copied paragraph carries none of that and
drifts the moment the API moves, which had already happened once to
Learning.
* One table, `FEATURE_ONBOARDING_INTENT`, maps each tile to one intent.
`Record<HomeServiceId, OnboardingIntent>` makes a new tile without an
intent a type error, and a test holds the two sets equal in both
directions.
* The two docs feature prompts follow: the Learning and Rich Threads
guides name an intent instead of repeating setup prose. They pass no
`--run` id, because these strings are static and `llm-text` inlines them
into cached raw Markdown, where one minted id would be shared by every
reader. The CLI mints its own when the flag is absent.
**Two naming decisions, both recorded in code**
The two id sets stay separate. A `HomeServiceId` names a tile and the
pane behind it, so `websocket` and `audio` are right for it; an intent
names work to be done, so `add-realtime-sync` and `add-voice` are right
for that. One table maps between them rather than forcing one string to
be both.
`memory` maps to `add-learning`, and that is now a fact rather than a
guess. `learningOn` is `learningSnapshot?.configuration.state ===
"configured"` — a configured Learning *container*, which is exactly what
`feature/learning/start.md` sets up through `getLearningContainerId`.
The tile id `memory` and the `memories` menu key are older names for
that same pane.
**The generic prompts stay generic**
The Inspector's install prompt, the docs CTA, and the Intelligence web
app keep pointing at the generic route. All three are entry points for a
developer with no CopilotKit app yet, and every feature route requires
one: it inspects for an app first and reads `feature/stop` when it is
missing. The reasoning is written into `onboarding-prompt.ts` so the
next person does not have to rederive it.
## The release blocker is cleared
`copilotkit@4.9.50` published on 2026-09-10 and is now `latest`. Its
tarball carries all seven `intentRoots` and all seven `prompts/feature/`
directories, built from Intelligence `1e703c3c`.
The exact string this PR's buttons copy was run against the real
package:
```
$ npx --yes copilotkit@latest onboard start --run abc123def456 \
--coding-agent claude-code --intent add-a2ui
onboarding_run_id: abc123def456
onboarding_graph_tree: 249d0337...
# Add A2UI to the existing CopilotKit app
```
All seven intents exit 0 against the published package. An unknown
intent is refused with `ONBOARDING_INTENT_NOT_FOUND` and a list of the
seven valid slugs, so a future drift between the table in this PR and
the CLI's map fails on the first command rather than onboarding the
wrong feature.
The release pinned the same CopilotKit template commit as 4.9.47
(`380ad122`), so the only delta between the two CLI versions is
Intelligence-side.
## The shell-docs half was ungated, so this adds a job
No CI job ran the `showcase/shell-docs` vitest suite, and none of the
prompt files were in `test_integration-docs.yml`'s paths filter. The
assertions in that half were verified on a developer's machine and
nowhere else, which is the same gap the retired prose had.
`feature-prompt-intents` now runs the five prompt test files on any
change to them, scoped to those files because the whole suite is not
green on main. Verified by running the job's exact command locally: 5
files, 17 tests, all passing.
## Related PRs and Issues
- Closes OSS-1150
- Follow-up: OSS-1151
- Callers for CopilotKit/Intelligence#994
## Validation
Run in a worktree off `origin/main`, with pre-existing failures
confirmed by running the same specs against unmodified `origin/main` in
the same worktree.
* `web-inspector` — `tsc --noEmit` clean; `tsdown` build clean; `vitest
run` 662 passed, 35 failed. All 35 are `threads-states.spec.ts` dying in
`setupSettledState` on `Cannot assign to read only property 'mock'`,
which reproduces identically on `origin/main` (35 failed | 1 passed of
36, before and after). The one assertion this PR changes in that file is
therefore not exercised locally; the same button is covered by
`launcher-hud.spec.ts`, which passes.
* `web-inspector` — `tsc --project dev/tsconfig.json` reports 2 errors
in `dev/*-state-lab-server.ts`, both `Uint8Array` vs `BodyInit`; same 2
on `origin/main`.
* `shell-docs` — `tsc --noEmit` clean; `vitest run` 875 passed, 6 failed
in `brand-nav`, `angular-docs-content`, `llm-text` (mastra) and
`ms-agent-python-stable-api`; the same 6 fail on `origin/main`.
* `oxfmt --check` and `oxlint` clean on every file in the diff. The
three files oxfmt still flags are two generated JSON bundles and
`page-tree-bridge.ts`, none of them touched here.
## 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)
The packaged skills had grown into a second copy of the documentation.
`runtime` and `react-core` were roughly 60% transcribed API surface, and
most of their remaining "Common Mistakes" prose already existed on a docs
page. A cached copy of an API goes stale silently: four claims in the
deleted skills contradicted the source they cited, and one of them reached
a shipped PR before it was caught.
Replace them with two skills that look the answer up instead of restating
it:
- `copilotkit` — the four search tools and two explore tools of the
bundled `copilotkit-docs` MCP server, which corpus answers which
question, and the instruction not to answer from memory.
- `copilotkit-cli` — the CLI, led by `copilotkit verify --json`. Since
#1180 `verify` covers version skew, CORS, and transcription, which is
what most of the old `copilotkit-debug` skill described by hand.
Deleted: copilotkit-setup, copilotkit-develop, copilotkit-integrations,
copilotkit-debug, copilotkit-upgrade, copilotkit-agui, copilotkit-contribute,
copilotkit-self-update, and the three package-generated skills (react-core,
runtime, a2ui-renderer).
The `skills` directory is dropped from the `files` field of the three
packages that shipped one, so the tarballs no longer carry a copy.
`public-skill-drift.test.ts` guarded wording in files that no longer exist.
It is now a link guard: every `docs.copilotkit.ai` path named by a packaged
skill has to resolve to a page in this repo, and the two entry points have
to stay free of a transcribed API surface.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Ran Shemtov