## What does this PR do?
Corrects `faciliate` to `facilitate` in the Mastra shared state
documentation.
## Related PRs and Issues
- None.
## Validation
- `codespell
showcase/shell-docs/src/content/docs/integrations/mastra/shared-state/index.mdx`
- `git diff --check`
## Checklist
- [x] I have read the [Contribution
Guide](https://github.com/CopilotKit/CopilotKit/blob/main/CONTRIBUTING.md).
- [x] The relevant documentation is updated by this PR.
- [x] "Allow edits by maintainers" is enabled.
Removed redundant text and improved clarity in the README. Removed stale
and internal references
## What does this PR do?
Fixed the Readme references for the open mcp app example, it was
referencing stale docs folder which does not exist.
## Related PRs and Issues
- (Direct link to related PR or issue, if relevant)
## Checklist
- [ *] I have read the [Contribution
Guide](https://github.com/copilotkit/copilotkit/blob/master/CONTRIBUTING.md)
- [ ] If the PR changes or adds functionality, I have updated the
relevant documentation
# fix(showcases): make MCP Apps deployable
## Summary
- keep the approved `@copilotkit/*` `1.68.1` upgrade and frontend
Railway health check
- import the endpoint stack and built-in agent from
`@copilotkit/runtime/v2`, matching the current
`examples/integrations/mcp-apps` runtime pattern
- align MCP Apps on one AG-UI `0.0.58` client/core/encoder/proto graph
with `@ag-ui/mcp-apps-middleware@^0.0.3`
- replace the stale standalone pnpm lock with the npm lock consumed by
Docker, and make Docker install it deterministically with `npm ci
--legacy-peer-deps`
- remove only unused frontend direct dependencies;
`@copilotkit/react-core`, `@copilotkit/runtime`, and
`@copilotkit/shared` remain direct `1.68.1` dependencies, while the
separately packaged MCP server retains its own `zod@^4.3.5`
## Root cause and RED evidence
- Baseline commit: `0daa38f9a7e50522e246a273802ef3ffde92556b` on current
`origin/main` `c2abbea9cf`.
- `./node_modules/.bin/tsc -p examples/showcases/mcp-apps/tsconfig.json
--noEmit --pretty false` reproduced three compatibility failures:
`TS2305` for `createCopilotEndpoint`, `TS2305` for
`InMemoryAgentRunner`, and `TS2345` because `MCPAppsMiddleware` and the
runtime resolved incompatible `@ag-ui/client` types.
- Before production edits, `npm test` ran the new compatibility contract
and failed `3/3` assertions for the legacy runtime entrypoint, stale
AG-UI versions, and missing npm lockfile.
- Before changing the Docker install command, the deployment contract
failed `1/4` because the Dockerfile still used `npm install
--legacy-peer-deps`.
- The first Docker build sent `889.11 MB` because no `.dockerignore`
excluded host `node_modules` and `.next`; the final context is `5.64
kB`.
## GREEN and verification evidence
- PASS — scoped formatter: repo-pinned `oxfmt --check` exited `0` for
the changed source, contract, and manifest inputs.
- PASS — scoped lint: repo-pinned `oxlint` reported `0 warnings` and `0
errors` for the changed route and compatibility test.
- PASS — explicit typecheck: standalone `./node_modules/.bin/tsc
--noEmit --pretty false` exited `0`.
- PASS — focused tests: `npm test` passed `5/5` contracts covering the
v2 runtime entrypoint, AG-UI graph, npm lock truth, deterministic Docker
install, and Docker context exclusions.
- PASS — production build: `npm run build` compiled, typechecked,
generated all four static pages, and emitted the
`/api/copilotkit/[[...slug]]` dynamic route.
- PASS — npm lock/install truth: `npm ci --legacy-peer-deps
--ignore-scripts` installed `1,234` packages from `package-lock.json`;
`npm ls @ag-ui/client @ag-ui/core @ag-ui/encoder @ag-ui/proto --all`
showed every instance deduped/overridden to `0.0.58`.
- PASS — no-cache container gate: `docker build --no-cache -f Dockerfile
-t codex-mcp-apps-pr .` completed `npm ci`, the in-image Next production
build, image export, and unpack on `node:20-slim` with exit `0`.
- PASS — scope/secret/type hygiene: the final PR changes only
`examples/showcases/mcp-apps/**`; high-confidence secret patterns, type
suppressions, swallowed catches, and floating calls were absent from the
staged diff.
- PASS — branch commit: `db929211253c5f6e4a9567833bdb0d4b6e7c7d8c`
(`fix(showcases): align MCP Apps runtime graph`), following the approved
deployability commit without modifying its Railway file.
## Non-blocking warnings
- npm reports 10 transitive audit findings (5 low, 1 moderate, 4 high);
this compatibility change does not force unrelated breaking upgrades.
- The Node 20 container install emits `EBADENGINE` warnings for
transitive `@azure/*`, `@typespec/ts-http-runtime`, and `openai@7.5.0`
packages that declare Node 22, but the clean Node 20 install and
production build both complete successfully. The existing `node:20-slim`
base is intentionally unchanged because the gate did not reproduce a
failure.
- Local Next builds inside the monorepo warn about the root pnpm lock
plus the standalone npm lock; the standalone build still completes
successfully and Docker uses only the showcase-local npm lock.
# fix(world): preserve LangGraph assistant config
## Summary
- restore the World demo's browser-supplied OpenAI key under
`assistantConfig`
- preserve the behavior of the authoritative legacy World commit
- add a dependency-free migration contract test
## Verification
- rebased cleanly onto current `main` at
`c2abbea9cf6a48c22b1dcd19e9dc469d5cfd458f`
- verified the authoritative legacy source still uses `assistantConfig`
at `markmdev/copilotkit-world@7a27a37b628b9e339d1284ec42382008e67884f5`
- verified `@ag-ui/langgraph@0.0.7` declares, stores, and merges
`assistantConfig`
- regression check against current `main` failed for the expected
missing-`assistantConfig` reason; the branch's dependency-free Node test
passed (`1/1`)
- `oxfmt --write` plus `oxfmt --check` passed on both changed files
- Nx reported no affected lint targets; direct `oxlint` completed with
`0` errors and one pre-existing `NextRequest` type-import warning on the
unchanged import line
- root dependency bootstrap passed with the repository-pinned pnpm
`10.33.4` and `--frozen-lockfile --ignore-scripts`
- `nx run @copilotkit/runtime-client-gql:build` and its 13 dependency
builds passed; this does not make that package resolvable from the
independently managed nested ChatKit Studio workspace
- exact-base and branch World typechecks used the same pnpm `9.15.0`
provisioning: base reports seven diagnostics, branch reports six, and
the branch-only diagnostic count is zero
- the removed base diagnostic is the changed route's invalid `config`
property; all six remaining diagnostics are identical current-`main`
errors in unchanged `page.tsx`, `useCountryData.ts`, and
`countryData.ts`
- both production builds compiled the optimized application source; base
then failed on the invalid `config`, while the branch advanced past the
changed route and stopped on the pre-existing undeclared
`@copilotkit/runtime-client-gql` import
- Python agent compilation passed
- worktree is clean; commit `a25941f9017fcd2a0a8e7660fe768c69cfaa28b6`
changes only the World route and its migration contract test
## Existing baseline debt
The branch introduces no type or production-build regression and removes
the route error it targets. Six unrelated current-`main` type
diagnostics remain:
```text
src/app/page.tsx(14,42): error TS2307: Cannot find module '@copilotkit/runtime-client-gql'
src/hooks/useCountryData.ts(2,50): error TS2307: Cannot find module 'geojson'
src/hooks/useCountryData.ts(4,51): error TS2307: Cannot find module 'topojson-specification'
src/hooks/useCountryData.ts(32,27): error TS2345: Argument of type 'unknown' is not assignable to parameter of type 'string'.
src/hooks/useCountryData.ts(43,12): error TS7006: Parameter 'country' implicitly has an 'any' type.
src/utils/countryData.ts(1,40): error TS2307: Cannot find module 'geojson'
```
The nested ChatKit Studio frozen install also reproduces the separate
current-`main` Playground importer drift covered by D006. D007 no longer
changes `package.json`, so it does not duplicate that lockfile fix.
Legacy source: `markmdev/copilotkit-world` at
`7a27a37b628b9e339d1284ec42382008e67884f5`.
# fix(showcases): sync chatkit studio lockfile
## Summary
- remove stale ESLint importer entries from the shared ChatKit Studio
lockfile
- restore frozen-lockfile validation for Playground, Studio, and World
without reserializing the lockfile
- keep the change limited to the shared dependency contract required by
the Playground deployment
## Verification
- Formatter: N/A for the changed YAML lockfile. The repository's oxfmt
0.36.0 does not accept YAML targets (`Expected at least one target
file`); its full-repository check listed only 28 pre-existing files
outside this branch's one-file diff.
- YAML parsing and structural validation passed: lockfile version 9.0,
four exact manifest importers, 1,431 packages, and 1,431 snapshots.
- The shared four-project workspace completed `pnpm install
--frozen-lockfile --ignore-scripts` with repository-pinned pnpm 9.15.0;
the resolution step was skipped because the lockfile is current.
- Playground and Studio passed explicit `tsc --noEmit`; their Next.js
production builds also passed. Both Python agent modules compiled
successfully, and the workspace defines no JavaScript test suite.
- Lint is N/A for this lockfile-only diff: Playground and Studio's
existing `next lint` scripts prompt to create an ESLint configuration,
while World defines no lint script.
- World's existing source/dependency type errors reproduce in both `tsc
--noEmit` and `next build`; they are unrelated to the removed
ESLint-only importer metadata. World otherwise compiled before its
existing type-validation failure.
- Diff, scope, secret, and worktree hygiene passed: the commit changes
only `examples/showcases/chatkit-studio/pnpm-lock.yaml` with 24
deletions and no additions.
The last mix made the HUD arrow a bit too light.
An empty 28px SW resize handle sat on the collapsed sidebar toggle.
In dark mode that handle painted as a black box.
The south and west edges still resize the floating window.
The SE grip is unchanged.
The launcher floats over a customer's page, and its border only earns its
place against a dark one -- so reviewing this branch needs a dark host page,
and the lab had no way to produce one.
Copied from `examples/v2/react/demo` rather than invented: the host owns a
theme state, and `CopilotChat` gets `className="dark"`, which is what makes
the package swap its own variable set. My first attempt stripped every
background instead, which is why the chat bubble, the send button, the
toolbar's on/off states and the error banner all vanished into one flat
grey -- the chat paints its own surfaces and has to be told, not undressed.
The colours are the demo's, by another route: it writes the oklch literals
that CopilotKit's variables use, and those are Tailwind's neutral steps --
`neutral-950` is `oklch(0.145 0 0)`, `neutral-50` is `oklch(0.985 0 0)`,
`neutral-800` is `oklch(0.269 0 0)`. Measured identical on the running lab.
`@custom-variant dark (&:is(.dark *))` is needed because Tailwind v4 points
`dark:` at `prefers-color-scheme` by default, so the toggle would have been
ignored in favour of the OS. Same declaration the package uses for its own
sheet.
The toggle sits top left, where the react demo puts it. Top right is where
the launcher floats.
## Why
The React Native page covers building the integration thoroughly and
never says how to
establish that it **works**. `verify` appeared zero times in its 646
lines, and the only
verification content was a reactive troubleshooting entry ("no response
from the runtime →
check `/info`").
That gap is sharper here than on the web frontends. There, "open it and
look" is an
unstated fallback that genuinely works. On React Native there is no
browser, so a reader
who follows this page to the end has no proof step at all — and the
obvious substitutes
each prove less than they appear to.
## What this adds
A **Proving it works** section with three checks, explicit that none is
sufficient alone:
1. **`copilotkit verify --round-trip`** — proves an agent answered, with
no browser and no
device. Its limits are stated rather than left to be discovered: it
sends a *fixed*
prompt and records the answer's length, never its text, so it cannot
tell you what came
back; and it proves an agent answered under the declared id, not *which*
deployment
answered.
2. **A device capture** — `adb exec-out screencap -p`, plus `adb logcat`
for an unresolved
redbox. iOS has no `adb` equivalent short of full Xcode, and the Command
Line Tools do
not ship `simctl`, so the section says so instead of implying parity.
3. **Checking the answer against the records the app holds** — the only
step that separates
a correct answer from a fluent one about records that do not exist. That
failure is
invisible in a screenshot, in a video, and to any reviewer unfamiliar
with the data.
Two smaller fixes on the same page:
- **`useAgentContext` is now a callout, not a list entry.** It sat in
the shared-hooks list
described as behaving "the same as on the web", which undersells the one
hook whose
absence fails *silently*. Rendering a list puts it in the view tree, not
in the agent's
context — separate steps. An agent missing the second still answers
plausibly, the tool UI
paints, and nothing errors. React Native has no browser console to
notice it in.
- **`@react-native-community/cli` is now a prerequisite.** React Native
0.87 no longer
bundles it, so an *upgraded* app needs it in `devDependencies` or
`react-native bundle`
and `react-native start` refuse to run. A freshly `init`ed app already
has it, which is
why the quickstart path never surfaced this.
## Notes for review
- **Docs-only.** One `.mdx` file, +78 lines, no code or config touched.
- The three anchor links used (`#connecting-from-a-device-or-bench`,
`#which-hooks-are-shared-and-which-arent`, `#known-limitations`) all
resolve to existing
headings, and match the anchor style the page already uses elsewhere.
- Prose is unwrapped to single-line paragraphs and callout bodies are
2-space indented, to
match the file's existing convention.
- `npm run lint` in `docs/` exits 0 with no new warnings. `vitest run`
gives 188 passed / 29
failed-to-load — **identical to a pristine `origin/main` worktree**,
which I ran to confirm;
those failures are a local module-resolution issue, not this change.
- Deliberately **not** included: documenting `copilotkit verify`
generally. It is currently
undocumented across the whole docs tree (Angular and Vue score zero on
"verif" too), which
wants its own change and probably a shared page rather than a
per-frontend section.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Closes the docs half of OSS-938. The Intelligence half (graph node flip,
`frontend/plan.md`, fixture conversion, replacement unsupported cell)
lands as a separate PR in `CopilotKit/Intelligence` — it cannot share a
PR across the repo boundary.
## Why
React SPA was the only frontend the onboarding graph could not route to
a validated outcome, and the gap was exactly one step: **where Copilot
Runtime lives.** Every framework quickstart hosts the runtime in a
Next.js route handler and sets a relative
`runtimeUrl="/api/copilotkit"`. That path resolves only because Next.js
serves the app and the runtime from one origin. A Vite or CRA app has
neither a server nor a shared origin, so the instruction had nowhere to
land.
The rest of the React tree already works unchanged in a SPA —
`/frontend-tools`, `/generative-ui`, `/human-in-the-loop`, `/headless`,
`/prebuilt-components` and `/reference/v2` contain no Next.js-specific
steps. So this adds one page for the one difference and links out for
everything else, rather than forking a parallel React tree.
## What's here
**1. `docs/frontends/react-spa.mdx`** — the standalone Node runtime
server (the `angular.mdx` / `vue.mdx` shape), the absolute `runtimeUrl`
it requires, `cors: true`, the two-dev-server port story, and links back
out to the root React pages.
**2. `react-spa` registered in
`showcase/shared/frontend-registry.json`** — required, not cosmetic.
Frontend route resolution is gated on `isFrontendId`
(`src/app/[framework]/[[...slug]]/page.tsx:96`, and the `/frontends/x` →
`/x` flattening at line 133), and `isFrontendId` reads the registry. An
unregistered MDX file 404s. Vue and React Native are the precedent —
both registered, both a single page, neither with a namespaced subtree —
so this does **not** create the `/react-spa/**` mirror tree OSS-938
rules out. `feature_support_required: false` matches them, so no
feature-support matrix entries are needed.
**3. The `runtimeUrl` sweep — 13 quickstarts**, each getting a callout
on its provider step noting that the relative path assumes a
Next.js-served origin.
## Two things worth a reviewer's attention
**`cors: true` is load-bearing and easy to omit.** `resolveCorsConfig`
(`packages/runtime/src/v2/runtime/core/fetch-handler.ts:784`) is `if
(!cors) return null`, and `createCopilotNodeListener` passes options
straight through to `createCopilotRuntimeHandler`. So CORS is **off by
default** on exactly the adapter a standalone SPA runtime uses — while
Express (`endpoints/express.ts:126`, `cors: corsOption = true`) and Hono
(`endpoints/hono.ts:105`) default permissive. Since the SPA's app and
runtime are on different origins, omitting it fails every request on
preflight. The page calls this out twice.
**The sweep callouts deliberately contain no root-relative links.** My
first attempt linked `/react-spa`, `/vue` and `/react-native`, which
broke `angular-docs-content.test.ts` → "keeps every rendered
backend-specific Angular link in context" with 45 leaks. That test is
right and the links were wrong: `resolveAngularDoc` falls back to
`frameworkContentSlug`, so the Angular surface **reuses these same
integration quickstarts**, and its link contract deliberately keeps
readers inside `/angular/**`. Enumerating three other frontends was also
wrong content for an Angular reader. The callout now names the guide
paths as inline code instead.
The cost is that the sweep no longer hands the reader a clickable link —
discoverability for React SPA comes from the frontend selector entry
instead. Doing both properly needs a frontend-conditional content
component (the `WhenAngularBackend` pattern, but keyed on frontend),
which is more than this sub-task should carry. Worth a follow-up.
## Corrections to the issue found while implementing
- **There is no doctest harness.** OSS-938 says the snippets are
doctest-gated. `shell-docs` runs vitest over `src/**/*.test.{ts,tsx}`
only — MDX code blocks are never executed. The real gates are that suite
plus `tsc --noEmit`.
- **The docs do have a frontend selector**, backed by the registry (6
entries before this change). The issue's "no frontend selector anywhere"
is true only of MDX *tab groups*.
- **The sweep is 13 source files, not 18 pages.** The langgraph,
microsoft-agent-framework and aws-strands variants are tab groups inside
one page each, so `langgraph-fastapi`/`-python`/`-typescript` collapse
to one file, the three `ms-agent-*` to one, and
`strands`/`strands-typescript` to one.
- **The root `/quickstart` needs nothing.** It is a 17-line routing shim
that 308-redirects to `/` and carries no runtime step at all. The issue
counts it among the 18.
- **The issue's page list misses `built-in-agent` and the root-level
`agent-spec/quickstart.mdx`**, both of which do carry the relative
`runtimeUrl`. Both are swept here.
- **Vue and React Native are already done**, in both repos — both ship
the absolute-`runtimeUrl` recipe and both already route to
`credentials/finalize-plan`. The issue defers them as out of scope, but
that also means the sweep fixes the mis-route for one frontend, not
three.
## Testing
Run in the worktree against `origin/main` (`0943c5196e`).
**`tsc --noEmit` — no new errors.** Baselined by setting my changes
aside on a pristine checkout: 8 pre-existing errors, all from
`@clerk/nextjs` / `@testing-library/react` / `jsdom` being undeclared
and uninstalled in `showcase/shell-docs/package.json` (verified absent
in `main` too, so this is repo state, not this branch). With the changes
applied: the same 8, zero added.
The type widening surfaced one real error, now fixed —
`FRONTEND_REFERENCE_SLUGS` in `frontend-page-content.ts` is `satisfies
Record<FrontendPageId, string>` and needed a `react-spa` entry. It maps
to `"reference"`, the root React reference, same as Vue.
**Test suite — no new failures.**
```
$ npx vitest run src/lib src/app
Test Files 1 failed | 41 passed (42)
Tests 1 failed | 380 passed (381)
× renders one dependency-complete canonical tool-rendering example for mastra
```
That mastra failure is pre-existing — reproduced on a pristine
`origin/main` checkout with every change of mine removed:
```
$ git checkout -- <changed files> && mv react-spa.mdx aside
$ npx vitest run src/lib/__tests__/llm-text.test.ts
Tests 1 failed | 39 passed (40)
× renders one dependency-complete canonical tool-rendering example for mastra
```
**The new page is covered by an existing registry-driven guard, and the
coverage is real.** `frontend-options.test.ts` → "maps every non-React
frontend to an MDX guide page" iterates `FRONTEND_PAGE_IDS` and asserts
`loadDoc(getFrontendContentSlug(id))?.fm.title`. Mutation-checked rather
than assumed — removing the page fails it, restoring it passes:
```
$ mv src/content/docs/frontends/react-spa.mdx /tmp/ && npx vitest run frontend-options.test.ts
× maps every non-React frontend to an MDX guide page
Tests 1 failed | 21 passed (22)
$ mv /tmp/react-spa.mdx src/content/docs/frontends/ && npx vitest run frontend-options.test.ts
Tests 22 passed (22)
```
**Sweep coverage checked programmatically, not by eye.** For each of the
13 files, asserted exactly one `runtimeUrl="/api/copilotkit"`
occurrence, the callout inserted immediately after that code block's
closing fence, and the `runtimeUrl` line exactly 9 lines above it. Then
re-derived the target set from the tree to confirm nothing was missed —
the only quickstart still carrying an un-annotated relative `runtimeUrl`
is `aws-strands`, which is excluded on purpose.
**Route wiring confirmed live.** `GET /frontends/react-spa` → `301` on
the local dev server, which is the registry-gated flattening redirect
firing for a registered id. Full HTML render could not be verified
locally: the dev server 500s on `@clerk/nextjs` for *every* page
(`/vue.md` fails identically), because that dep is undeclared and
uninstalled — pre-existing and not specific to this branch.
**Every outbound link on the new page resolves** — probed
`/frontend-tools`, `/generative-ui`, `/human-in-the-loop`, `/headless`,
`/prebuilt-components`, `/reference/v2`, `/model-selection`,
`/backend/runtime-endpoints`: all 200 or 301-to-canonical.
**Fixed a stale mock while here.**
`src/app/llms-mdx/[[...slug]]/route.test.ts` hard-codes the frontend
list instead of reading the registry, so it silently omitted
`react-spa`. Added it to both lists; suite passes (15/15). The
hard-coding is still a latent divergence worth a follow-up.
## Not done here
- **`aws-strands/quickstart.mdx` is excluded from the sweep**, per the
standing hands-off arrangement while Mark leads the Strands
rejuvenation. That leaves `strands` and `strands-typescript` carrying
the un-annotated Next.js step.
- **A clickable cross-link in the sweep callouts**, per the
Angular-contract finding above.
- The Intelligence-side changes, as noted at the top.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## What
`MastraAgent.getRemoteAgents` appeared **nowhere** in this repo — not in
shell-docs, not in an example, not in a snippet. The only wiring the
Mastra docs taught was `getLocalAgents({ mastra })` behind `import {
mastra } from "@/mastra"`.
That was on the **"Use an existing agent"** branch of the quickstart —
the branch for readers who already have a Mastra service. Two steps
earlier the same branch tells you to `npx create-next-app
my-copilot-app`, a *separate* directory. `@/mastra` cannot resolve
across that boundary, and the shape it teaches moves a running Mastra
service into the frontend, deleting the process the reader was trying to
preserve.
All four cells of the 2026-08-21 Mastra × Next.js sweep reached the
agent over HTTP, and all four derived how on their own. `both` filed
"the remote-Mastra API is entirely undocumented" as its largest
friction; `empty` filed it as its worst papercut at ~10 minutes.
## Changes
**`mastra/quickstart.mdx`** (existing-agent branch)
- Route wired with `getRemoteAgents` over a `MastraClient`, so the agent
keeps running as its own process. Passed as a **factory**, so the agent
list is fetched per request — see the note below on why the promise form
is unsafe.
- `MASTRA_BASE_URL` convention, as `.env.local` in the frontend beside
the route that reads it: `process.env.MASTRA_BASE_URL ??
"http://127.0.0.1:4111"`.
- A **"Start your agent"** step, which the branch never had. Its
liveness check is `/api/agents`, not `GET /` — Mastra serves its console
on the agent port and answers 200 whether or not an agent is registered
(straight from the `empty` cell's evidence).
- A warning that `next dev` rewrites the `tsconfig.json` at its own root
— forcing `esModuleInterop`, `isolatedModules`, `resolveJsonModule` and
`jsx`, setting `noEmit: true`, and replacing `include`/`exclude`.
`noEmit` is the sharp one for an agent project that compiles with `tsc`.
A sibling package is why this path goes over HTTP. `agent-only` derived
this independently.
**`mastra/copilot-runtime.mdx`** — a new **"Local vs remote agents"**
section that decides between the two by *where the agent runs*, not by
preference, plus:
- the full `GetRemoteAgentsOptions` contract (`mastraClient`,
`resourceId`, `observationalMemory`, `tracingOptions`);
- why the factory form is the one to use — `agents` does accept the
promise itself, but that starts the HTTP call at module load with
nothing awaiting it, so an agent server that is not up yet produces an
unhandled rejection and **Node terminates the process**. The factory has
no such window: a failure is a 500 and the next request retries, so a
route that started first recovers on its own. Cost is one `listAgents()`
per request;
- the local-only options (`requestContext`, `untilIdle`) — so a run that
needs background tasks has to be embedded.
**CI gating** — the new route fence carries `doctest="component"` with a
mastra `doctest.json`. The old fence could never have been gated:
`@/mastra` does not resolve. Mastra now has its first typechecked route
snippet, 21 gated fences → 22.
## Verified
```
shipped fence, agent down -> up -> 500, then 200; process survived, no restart needed
promise form, agent down -> node terminated on an unhandled rejection
next build, NodeNext tsconfig -> 13 keys written; module/moduleResolution NOT touched
mastra CLI -> serverPort 4111, getPort over 4111..4131, apiPrefix /api
doc-test extraction -> 21 -> 22 fences; mastra sidecar selected, not the root one
extracted fence, runner config -> tsc exit 0 (runtime 1.68.3; @ag-ui/mastra 1.1.1 and 1.1.2)
mutation: drop resourceId -> tsc exit 1, TS2741 (the gate is live)
previously documented local shape-> tsc exit 2, resourceId missing
MDX compile, both files -> OK (mutation-checked: unclosed tag -> FAIL)
validate-intelligence-env-names -> exit 0
```
The behavioural checks drove the **extracted fence itself** against a
stub agent server, not a paraphrase of it — including confirming it
calls `/api/agents` (the same path the quickstart gives as the liveness
check) and that it honours `MASTRA_BASE_URL`.
The extracted fence was byte-compared against the file that typechecked
green.
**Not run:** the shell-docs vitest suite. No test reads either file,
there are no snapshots, and no page was added or moved — nav, sitemap
and `llms.txt` are unchanged. Lefthook could not run in the worktree
(`tsx: command not found`, no `node_modules`); its one non-skipped gate,
`check:intelligence-env-names`, was run manually against this tree and
passes, and the commit message passes commitlint.
## Second commit
The first commit shipped the promise form and named `moduleResolution:
"NodeNext"` as what `next dev` clobbers. Self-review caught both: the
promise form crashes the process, and `nodenext` is in Next's *accepted*
set for `module` and `moduleResolution`, so it is never rewritten.
`7f068c6` corrects both plus the `MASTRA_BASE_URL` shell, each against a
real run rather than a source read.
## Found along the way, not fixed here
`getLocalAgents({ mastra })` — no `resourceId` — **does not typecheck**
against current `@ag-ui/mastra`; `resourceId` is required in
`GetLocalAgentsOptions`. That shape still ships on four other pages
(`shared-state/` ×3, `background-tasks.mdx`), and
`examples/integrations/mastra/src/agent.ts` carries a `//
@ts-expect-error - ignore for now, typing error` over exactly this call.
Left alone to keep this PR focused; happy to file it or fix it in a
follow-up.
Refs OSS-925.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Review asked for fewer borders and boxes, and for the dot's heavy border to
become a subtle shadow.
The launcher had two concentric lilac hairlines: the border, and a second
ring 1px outside it as a box-shadow, which also hardcoded the lilac instead
of reading the edge token. The outer one goes. What replaces it is a
one-pixel light edge along the top, which keeps the face from reading flat
without drawing a frame.
The border itself stays, and it is not decoration: against a dark host page
the face measures 1.10:1 (GitHub dark) and 1.04:1 (Tailwind slate-900), so
without it the launcher has no outline there at all.
`backdrop-blur-md` goes too. It sat behind a 95%-opaque fill and bought
almost nothing, while mounting a permanent blur layer over a customer's
page. It did have one real side effect -- promoting the launcher to its own
compositing layer -- and without that the hover scale re-rasterises the mark
every frame and it visibly jitters. `will-change: transform` asks for the
layer directly, and the jitter is gone.
The dot loses its opaque 1.5px collar. That collar was 21% of the dot's
footprint, and because the dot's centre sits *on* the rim, its outer half
painted a hard dark crescent onto the host page rather than onto the
launcher -- which is what read as "heavy". A hairline plus a soft drop
separates it just as well. The fill becomes a lens lit from the upper left,
both stops derived from the signal colour so a new tone needs no new values.
Considered and dropped: tinting the border in the signal colour. On a dark
page the border is the whole silhouette, so tinting it recolours the entire
launcher for a state that can persist for hours -- and the launcher already
pulses in that colour when the failure is new.
## Summary
- make planned max-job harness-worker recycling exit cleanly after
ordered teardown, while escaped teardown failures still exit non-zero
- declare Railway `ALWAYS` as the staging and production
`harness-workers` restart policy in the existing service source of truth
- apply and verify the worker policy in the existing staging redeploy
and production promotion paths
- preserve the policy for direct named `harness-workers` pins and block
direct worker rollback with safer pin guidance
## Operational contract
- Railway remains the only worker supervisor; this does not add an
in-process restart manager
- staging worker update/readback failures are release-blocking for that
target, while independent staging services continue
- production promotion verifies the exact newly-created deployment ID,
serving digest, and active restart policy before reporting success
- no retry-max field is managed, and this does not claim unlimited
restarts for pathological crash loops
- generic restore, generic non-worker pin, and generic production
redeploy behavior are intentionally unchanged
## Review fixes
- require production promotion readback to match the deployment ID just
created
- preserve SSOT restart policy and replica settings on direct named
worker pin
- narrow the runbook language to the direct named worker pin path
actually covered by the implementation
## Verification
- `@copilotkit/showcase-scripts`: 78 test files / 2,539 tests passed
- `@copilotkit/showcase-harness`: 177 test files passed / 2 skipped;
3,723 tests passed / 18 skipped
- Ruby 3.3 Railway suite: 195 runs / 782 assertions / 0 failures
- formatter, explicit Nx typecheck, affected Nx build, and `git diff
--check` passed
- Tier-3 CR loop converged with zero mandatory findings after two
confirmation rounds
## Post-merge validation
Observe one unchanged staging worker identity through more than ten
ordinary recycle/restart cycles, confirm it continues claiming work, and
confirm the active deployment remains `SUCCESS` with `restartPolicyType:
ALWAYS`. This is bounded staging evidence, not an infinite-restart
guarantee.
Six Tailwind utilities on the launcher set properties the unlayered `css`
block sets again, and unlayered declarations beat layered ones regardless of
specificity -- so `bg-slate-950/95`, `border-white/20`, `ring-1`,
`ring-white/10` and the two hover variants have never had any effect. Each
was the package's only use, so the checked-in stylesheet drops 939 bytes.
No visual change: verified the three rules are gone from the generated sheet
and the 611 tests still pass.
Kept deliberately: plain `border` (the hand CSS sets only `border-color`),
`rounded-full` (nothing else sets the radius) and the focus-visible trio
(the hand CSS sets only `outline-color`).
The face moves to `#181C1F` at 95%, which review asked for. It is a hair
darker than the `#1C1F24` this replaces -- 17.2:1 against white rather than
16.5:1, a ΔE of 2.3, at the floor of what an eye can separate -- so this
settles the question rather than changing the look.
Resolves the Mastra quickstart runtime step, where this branch's remote-agent
wiring and main's Intelligence wiring landed on the same lines. Kept both: the
per-request `getRemoteAgents` factory now sits alongside `intelligence` and
`identifyUser`, `runner: new InMemoryAgentRunner()` is gone (main dropped it
with the runner), and `resourceId` is derived from the same request header as
`identifyUser` rather than left hardcoded to "user-1", which would have scoped
Mastra's memory and CopilotKit's threads to different users. Both env blocks
and both callouts are preserved.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The page tells you how to build the integration and never how to establish that it
works. `verify` appeared zero times in 646 lines, and the only verification content
was a reactive troubleshooting entry. That gap is sharper here than on the web
frontends: there, "open it and look" is an unstated fallback that actually works. On
React Native there is no browser, so a reader following this page to the end has no
proof step at all.
Adds a "Proving it works" section with three checks, and is explicit that none of them
is sufficient alone, because each one looks more conclusive than it is:
- `copilotkit verify --round-trip` proves an agent answered with no browser and no
device. It sends a fixed prompt and records the answer's length, never its text, so
it cannot tell you what came back -- and it proves an agent answered under the
declared id, not which deployment answered.
- A device capture proves the tool UI rendered. Android gets `adb exec-out screencap`;
iOS has no equivalent short of full Xcode, and the Command Line Tools do not ship
`simctl`, so that is stated rather than left to be discovered.
- Checking the answer against the records the app holds is the only step that
separates a correct answer from a fluent one about records that do not exist. That
failure is invisible in a screenshot, in a video, and to any reviewer unfamiliar
with the data.
Also on this page:
- `useAgentContext` was listed in the shared-hooks list as behaving "the same as on
the web", which undersells the one whose absence fails silently. Rendering a list
puts it in the view tree, not in the agent's context. An agent missing it still
answers plausibly and nothing errors -- and React Native has no browser console to
notice it in. Now a callout.
- React Native 0.87 no longer bundles `@react-native-community/cli`, so an upgraded
app needs it in devDependencies or `bundle` and `start` refuse to run. A freshly
`init`ed app already has it, which is why the quickstart path never hit this. Now a
prerequisite.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
## Problem
`runner` and `intelligence` are mutually exclusive by construction, but
the exclusivity was enforced in only one direction and only for object
literals.
`CopilotIntelligenceRuntime` hardcodes `new
IntelligenceAgentRunner(...)` into its `super()` call
(`runtime.ts:582`), and `runner?` is declared only on
`CopilotSseRuntimeOptions` (`runtime.ts:239`). The type system catches a
`runner:` key on an Intelligence-shaped **object literal** via
excess-property checking — but that is the only barrier. A JS caller, an
`as any`, or a non-literal options object routes through
`CopilotRuntimeShim`'s `hasIntelligenceOptions()` dispatch into the
Intelligence constructor and has `runner` **silently dropped**, with no
diagnostic.
The mirror case is already guarded: `CopilotSseRuntime` throws on
`channels`, and the comment there states the exact reasoning that
applies here — "the type forbids it, but a JS / `as any` caller ...
would otherwise land here and have `channels` silently dropped — fail
loud instead." The Intelligence constructor validates `identifyUser`,
`channels`, `memory`, and `ɵlearning`. Same file, same pattern, one case
missing.
### It also made a shipped skill lie
`packages/runtime/skills/runtime/SKILL.md:87` asserted:
> Passing both `runner` and `intelligence` to `CopilotRuntime` is
rejected at construction.
It was not. And that contradicted the skill's own reference page,
`references/agent-runners.md`, which correctly described the silent
drop. Two files in the same shipped skill said opposite things about the
same behaviour.
## Change
- **Guard** (`runtime.ts:512`) — `CopilotIntelligenceRuntime` now throws
when `runner` is present, mirroring the `channels` guard in
`CopilotSseRuntime`. The message names the exclusivity and points out
that an in-memory/SQLite runner is unnecessary in Intelligence mode,
where durability is managed by the service.
- **`SKILL.md:87` unchanged** — the guard makes it accurate.
- **`references/agent-runners.md` updated** — this is *not* optional.
That page was the accurate one before this change; adding the guard
makes its "the auto-wired Intelligence runner wins regardless of what
you pass" false. Leaving it would fix SKILL.md's lie by creating the
same lie in the reference — rotating the contradiction rather than
resolving it. Its stale `:149-173,285-294` source citation is corrected
to the real line numbers too. Root `skills/` mirror regenerated via
`pnpm sync:plugin-skills`.
## Behavior notes
- Explicit `runner: undefined` still constructs. This matches how the
sibling `identifyUser` / `channels` / `memory` guards treat `undefined`,
and avoids breaking callers that spread an options object.
- The v1 deprecated compat path is unaffected:
`copilot-runtime.ts:492-509` already omits `runner` from its
Intelligence branch, so nothing routes a `runner` into this constructor
from v1.
## Tests
Two tests in `channels-option.test.ts`, alongside the existing `sse
runtime rejects channels` mirror:
- `intelligence runtime rejects a caller-supplied runner` — written
first and confirmed **red** against the unpatched constructor
(`AssertionError: expected [Function] to throw an error`), green after.
- `intelligence runtime tolerates an explicitly undefined runner` — pins
the undefined-tolerance above so the guard cannot over-throw.
## Verification
| Gate | Result |
|---|---|
| `nx test @copilotkit/runtime` | 144 files, **2080 passed, 0 failed** |
| `nx check-types @copilotkit/runtime` | Successfully ran (+22 deps) |
| `oxlint` (changed files) | 0 warnings, 0 errors |
| `oxfmt --check` | no issues in changed files |
| lefthook pre-commit + commit-msg | all green |
Closes OSS-933.
"no telemetry payload anywhere carries the failure message" serialises the
whole property bag and asserts it does not contain "503". Two of those
properties are the anonymous distinct id -- random hex -- so a three-digit
numeric needle lands inside one roughly once in a few hundred runs. It just
failed a CI job that way, which reads like a privacy breach and is not one.
The ids are excluded by name and asserted to still be strings, rather than
weakening the needles, which are the point of the test. Proven both ways:
with an id seeded to contain "503" the test passes with this change and
fails without it, and it still goes red when a real message is attached to
the payload.
`refocusEventErrorLanding` reads the subject back out of the card's
`data-cpk-event-error` attribute, where the DOM can only offer
`string | undefined`, and handed that to a guard typed for
`LauncherSignalKey`. Narrowing untrusted input is what the guard is for, so
it takes a string; every caller that already holds a key still satisfies it.
Tests do not typecheck, so the suite stayed green and only `check-types`
saw it -- which failed three CI jobs on the same one line.
## What does this PR do?
Lets a developer open a saved Inspector thread in the live official
chat.
- New header action: **View in your app**
- Official React and Vue chat switch to that thread
- A pinned `threadId` does not block the switch
- **Stop viewing** or an app thread change restores the previous thread
- Example threads have no action
- Production builds hide the action
- Same agent only. No matching official chat shows an error in the
Inspector
Core owns a two-way EventClient bridge
(`@tanstack/devtools-event-client`). The root import is a no-op in
production.
Docs: Inspector guide, section **View a thread in your app**.
## Related PRs and Issues
-
https://linear.app/copilotkit/issue/OSS-871/new-features-add-a-new-view-thread-in-your-app-feature
## 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
The banking showcase is superseded by `examples/showcases/reskinnable-demo`,
which ships the same banking experience as one of its runtime-swappable skins
(alongside airline) on top of a shared shell. Keeping both means maintaining
two copies of the same demo, so banking is sunset here.
Removes the app and the things that referenced it:
- `pnpm-workspace.yaml` — drops the workspace entry. Also fixes the adjacent
NOTE, which attributed the canary AG-UI pin to "banking's agent" when it is
reskinnable-demo's own Python deep agent that needs it.
- `pnpm-lock.yaml` — regenerated. Only the removed importer and the peer-suffix
re-keying it caused; no dependency version changes.
- `examples/README.md` — the banking row becomes a reskinnable-demo row, so the
successor is listed and the showcase count is unchanged.
- `showcase/shell-docs/.../faq.mdx` — the Banking Assistant link retargets to
reskinnable-demo instead of 404ing.
- `.github/config-allowlist.txt` — drops the deleted `next.config.mjs`.
Not changed: `scripts/migrate-demos.sh` and `scripts/archive-demo-repos.sh`
still name `examples/showcases/banking`. Those are the already-executed one-shot
manifests for the repo consolidation; the path is a historical record there, not
a live reference. reskinnable-demo's `.env.example` and `docker-compose.yml`
likewise still explain their +200 port offset in terms of banking's stack — the
offset stays real, and "was cloned from banking" stays true.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Three claims the code refuses, and one source missing.
- "The failed tool call is highlighted" covered both tool cases, but
`TOOL_NOT_FOUND` is emitted with `toolName` and `agentId` and no
`toolCallId` -- a tool that was never found has no call to point at.
- "The failed `RUN_ERROR` event is highlighted" holds only when such an
event is in the buffer; several codes reach the run source without one.
- "A red launcher pill names the failure. Click it" reads as unconditional,
but the pill is suppressed where there is no room beside the launcher,
leaving a red dot and nothing to click.
- Learning is the fifth source and appeared in neither page. Documented
with the constraint that makes it different: the memory store is created
on first visit, so nothing is reported before that.
`handleMenuSelect` applied the event error's landing on every click on Agent
or AG-UI Events. A landing selects the failed agent, clears the event
filters and re-expands the failed row -- help for a reader who came
*because* of that error, vandalism for one who did not.
`lastEventError` outlives being read on purpose, so the how-to-fix card
survives while it is being read. Together that meant: one run error, and
for the rest of the session every return to AG-UI Events silently wiped the
reader's own search filter and re-expanded a row from hours ago. It also
undid the `all-agents` restore eight lines above it, whose comment says it
exists "so the Events tab isn't silently filtered to one agent".
The three arrivals that really are landings keep it -- pressing the
launcher, pressing the card, and an error arriving while its view is
already open. The new test fails with the old call in place, on the value
the reader can see: expected '' to be 'bookFlight'.
Ben Taylor