The shell-docs copy of ag-ui-middleware.mdx had been authored with full
content while the upstream file remained a 10-line TODO stub. Port the
70-line authored version up so the docs-sync pipeline stops threatening
to overwrite it.
When the runtime registers an agent as default, CopilotKit hooks auto-select
it; passing agentId: "default" (or a stale "assistant" ID that isn't
actually registered) is noise. Applies to built-in-agent/shared-state.mdx
and unselected/shared-state.mdx across shell-docs and upstream.
Goal: fast 'wow that's fast' initial experience for users trying the
built-in agent. Sweeps shell-docs unselected/ and upstream built-in-agent/
so both trees match. Also collapses two mismatched GPT-4o rows in the
model-selection table into a single honest 'GPT-5.4 Mini' row.
Fix the long-standing typo across the example directory name + module
identifiers, align imports + package names. Also touches examples/integrations/adk
docker-compose fixtures and examples/e2e agents reference doc.
## Summary
Three connected features land together so the CopilotKit VS Code
extension becomes a coherent debugger/preview surface:
1. **Hook Explorer** — every V1 + V2 render hook can be discovered and
previewed live with auto-generated controls, an inline `▶️ Preview
Component` CodeLens, and a sidebar that lists every captured site.
2. **AG-UI Event Inspector** — live SSE debug stream of all AG-UI
events, filterable and color-coded, in a sidebar view + editor panel.
3. **A2UI Catalog sidebar → webview** — the last native TreeView gets
replaced with a Tailwind-styled webview that matches the other two, now
with a proper **Go to source** action on components and fixtures.
## Hook Explorer
### Discovery + preview
- oxc-based scanner walks the workspace and finds every call-site of any
hook in the registry (17 across V1 + V2, render + data).
- Preview panel bundles the user's source via Rolldown (IIFE format,
React externalized, CSS collected per `@copilotkit/a2ui-renderer`
pattern), executes it in the webview with a capture-only **stub** for
`@copilotkit/react-core` (+ `/v2`), and mounts the user's component just
long enough to record each hook's config.
- Auto-generated form on the left/top drives the `render` prop's
args/parameters/state/event live. V1 parameter arrays and V2 Zod /
Standard Schema all map through a unified `FormSchema` derived at
runtime from the captured config.
- `useCopilotAction`, `useCopilotAuthenticatedAction_c`,
`useCoAgentStateRender`, `useLangGraphInterrupt`, `useRenderTool`,
`useRenderToolCall`, `useDefaultRenderTool`, `useLazyToolRenderer`,
`useRenderCustomMessages`, `useRenderActivityMessage`,
`useHumanInTheLoop`, `useInterrupt`, `useFrontendTool`, `useComponent`,
`useDefaultTool` all previewable.
- Inline `▶️ Preview Component` CodeLens above every render-hook call
site, backed by the same `copilotkit.hooks.preview` command as the
sidebar.
- Imported render components work: rolldown walks transitive imports
from the hook's `render` prop through any number of sibling files.
- Cross-file hook switches are robust: controls are reset on load,
Harness only mounts once the real HostRoot is ready, a top-level error
boundary auto-recovers when you pick a different hook.
### Why the stub approach
Bundling the real `@copilotkit/react-core` through rolldown's IIFE
output hit a `__commonJSMin` TDZ chain (`require_clipboard`,
`require_graphql`, `require_context_helpers`, …) because the
chat/runtime-client/markdown graph has circular imports. Externalizing
react-core + routing to a Proxy-backed stub that captures hook configs
avoids the whole CJS wrapping problem, shrinks the preview bundle from
~24 MB to ~1.3 KB, and keeps the preview runtime path completely
runnable without a live CopilotKit backend. Tradeoff documented in
`copilotkit-stubs.ts`.
### Weather-themed fixtures
14+ fixtures under `packages/vscode-extension/test-workspace/hooks`,
each a distinct visual scenario (forecast card, severity-palette alerts
with imported CSS, forecast strip, live radar grid, conic-gradient
precipitation gauge, air-quality badge with imported render, pollen
report with a 2-hop import graph, HITL evacuation confirm,
sunrise/sunset gradient, etc.). Used both as regression fixtures and as
the demo surface for video.
### Styling
- Tailwind-via-CDN + VS Code CSS variables for theme-aware chrome.
- User-provided CSS imports collected by rolldown and injected as a
`<style>` tag per load.
- Controls + form fields converted to Tailwind; textarea matches input
styling.
- Framed "Rendered output" card so the render prop is visually
unmistakable.
## AG-UI Event Inspector
### Runtime (`@copilotkit/runtime` + `@copilotkit/shared`)
- `DebugEventBus` — in-memory pub/sub on `BaseCopilotRuntime`, only
instantiated when `NODE_ENV != production`.
- Event tap in `createSseEventResponse` broadcasts every AG-UI event
with metadata (agentId, threadId, runId, timestamp).
- `GET /debug-events` SSE endpoint — returns 404 in production, streams
`DebugEventEnvelope` JSON to connected clients, initial `: connected`
comment flushes headers immediately.
### VSCode Extension
- `DebugStream` — Node SSE client with auto-reconnect, exponential
backoff, URL validation, error surfacing.
- `InspectorPanel` (editor panel, command `CopilotKit: Open AG-UI
Inspector`) and `InspectorViewProvider` (sidebar view) both use a shared
`DebugStream` instance — events persist when switching tabs.
- Inspector React app: `ConnectionBar`, `FilterBar`, `EventList`,
`EventDetail`.
- Color scheme: purple (lifecycle), red (errors), blue (text), orange
(tools), green (reasoning), teal (state), yellow (activity), gray
(unknown).
## A2UI Catalog → webview
- Replaces `ComponentPreviewProvider` (native TreeDataProvider) with
`CatalogListViewProvider` (WebviewViewProvider), matching the Hooks and
Inspector sidebars.
- New React webview with refresh header, component rows (name + relative
path + `auto` badge when no fixture), expandable fixtures list.
- Click a component row → preview (or toggle if it has fixtures); click
a fixture row → preview that fixture.
- Hover action buttons: `▷` preview + `</>` go-to-source on every row.
- "Go to source" opens the component file for component rows; for
fixture rows it opens the fixture file and jumps the cursor to the named
fixture key.
## Test coverage
- Runtime: DebugEventBus unit tests (8), handleDebugEvents endpoint (5),
fetch-router routes (4), integration across Express/Hono/Node/Fetch (9).
- Hooks: scanner + 16 fixture bundle-smoke test, regression guard
against `node_<builtin>` self-references, CSS collector test, stub-based
capture E2E, cross-kind controls remount, FormRenderer defensive
rendering.
- Inspector + webview: DebugStream reconnect (10), inspector components
(17), colors (9).
- Total: **178 tests** passing for the vscode-extension package; runtime
suite unchanged.
## Test plan
- [ ] `pnpm nx run copilotkit-vscode-extension:build` and `pnpm nx run
copilotkit-vscode-extension:test` both green
- [ ] F5 launches the Extension Dev Host with `test-workspace` open
- [ ] Hooks sidebar lists every fixture hook; click a row → preview
opens; `</>` button opens the source
- [ ] `▶️ Preview Component` CodeLens shows above every render hook in a
`.tsx` file; clicking it opens the preview
- [ ] Form controls drive the render live; cross-kind hook switches
(action ↔ custom-message) don't crash; a forced render-prop throw
recovers when a different hook is picked
- [ ] Imported-render fixtures (`ImportedAirQuality`,
`ImportedPollenReport`) bundle and preview correctly
- [ ] A2UI Catalog sidebar is the new webview, refresh works, `</>` on a
fixture opens the fixture file and reveals the named key
- [ ] AG-UI Inspector connects to `GET /debug-events`, filters + detail
work, events survive sidebar/panel switch, invalid URL shows red error
Mirror of #4128 by @MalaikaAbb.
The PR changes API identifiers (`ChatAgent`→`Agent`,
`chat_client=`→`client=`, `model_id=`→`model=`, `@ai_function`→`@tool`)
across several pages but leaves other sibling docs
(`human-in-the-loop.mdx`, `frontend-tools.mdx`, `auth.mdx`) on the old
API — this is a partial migration that needs human review to confirm the
new API is correct and to coordinate updating the remaining pages.
**Included:**
-
`docs/content/docs/integrations/microsoft-agent-framework/agent-app-context.mdx`
-
`docs/content/docs/integrations/microsoft-agent-framework/generative-ui/state-rendering.mdx`
-
`docs/content/docs/integrations/microsoft-agent-framework/generative-ui/tool-rendering.mdx`
-
`docs/content/docs/integrations/microsoft-agent-framework/quickstart.mdx`
-
`docs/content/docs/integrations/microsoft-agent-framework/shared-state/in-app-agent-read.mdx`
-
`docs/content/docs/integrations/microsoft-agent-framework/shared-state/in-app-agent-write.mdx`
**Excluded:**
- `docs/lib/integration-features.ts`
Assumed these are unrelated to the docs fix and excluded them from the
mirror. The original #4128 was closed as part of this handoff; if the
excluded changes are required, please open a new PR for them.
Completes the partial migration in PR #4128 — extends the same
identifier rename pattern (ChatAgent→Agent, ChatClientProtocol→
SupportsChatGetResponse, chat_client=→client=, model_id=→model=,
@ai_function→@tool, Dict→dict) to the four sibling pages the fork
PR left on the old API, and patches one Dict annotation in
state-rendering.mdx that slipped through the original mirror.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Drops the inline TypeScript typecast from the Mastra agent-app-context
example and uses optional chaining + direct access instead, so the doc
snippet is easier to read and copy. Keeps optional chaining on `.find`
so the example stays safe when the AG-UI context is absent. Also fixes
the `[!code highlight:N]` count after the comment line was removed.
Ports @Abubakar-01's changes from #4125 so they can ship together with
the `requestContext` rename, targeting the new `showcase/shell-docs/`
path after the shell restructure on main.
Co-authored-by: Muhammad Abubakar <abubakaran102025@gmail.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add a card for the new Intelligence Platform explainer to the Learn
index card grid, positioned between Architecture and Threads so the
landing page reads overall architecture → platform → features → protocols.
Without this, the page is reachable only via the sidebar and is
invisible to evaluators browsing /learn top-down.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add the documentation kit for self-hosted CopilotKit Intelligence:
- (root)/premium/self-hosting.mdx — canonical how-to covering platform
prerequisites, values file configuration (AWS ALB/IRSA and on-prem
nginx paths), secret delivery via External Secrets or direct
Kubernetes Secrets, install/verify/upgrade/uninstall steps, and an
inline values.yaml reference
- learn/intelligence-platform.mdx — Diataxis explanation covering the
app-api / app-frontend / realtime-gateway workloads, the
control-plane/data-plane split, the multi-tenancy model
(organization/project/user with auth.deploymentMode postures), the
platform-layer vs application-layer split for self-hosted installs,
secret rotation, scaling, upgrade, error handling, and the
hosted-vs-self-hosted decision
- snippets/shared/premium/self-hosting.mdx — shared snippet that
mirrors the canonical how-to for integration pointer pages
- integrations/*/premium/self-hosting.mdx (12 frameworks) — thin
pointer pages that import the shared snippet, so Self-Hosting is
discoverable from every integration sidebar (a2a has no /premium/
subdir and is intentionally skipped)
- meta.json nav entries in (root)/premium, learn, and every integration
premium sidebar
Also wraps the remaining Threads docs with the ThreadsEarlyAccess gate
(root threads.mdx, shared threads snippet, multi-conversation-chat
tutorial) and replaces the previous "self-hosted Enterprise, configure
your database connection per the Enterprise setup guide" placeholders
with real /premium/self-hosting links — the Threads docs referenced a
setup guide that did not exist until now.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Wrap the Threads documentation surface with the existing
InsecurePasswordProtected component via a thin ThreadsEarlyAccess
wrapper that surfaces Threads-specific splash copy and the shareable
early-access URL. Register the wrapper in both route handlers so the
gate works for docs under both (home) and integrations slug routes.
Wraps learn/threads.mdx and reference/v2/hooks/useThreads.mdx; the
remaining Threads pages are wrapped in the follow-up commit that also
fixes the cross-links to the new Self-Hosting docs.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Restores the API-surface change from the original QA PR #3866 (merged
via mirror #4040) that was inadvertently reverted in 804c5d0f. Keeps
Jordan's other fixes (imports, model, null guards, grammar) intact.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Persona fix: the landing page at /vs-code-extension only documented the
A2UI catalog preview, so builders using CopilotKit hooks and runtime
debuggers never discovered their respective features. Restructured
into a three-section hub that surfaces Hook Explorer, A2UI Catalog,
and AG-UI Inspector side-by-side, with install steps at the top and
cross-links to the deep-dive pages.
/troubleshooting/hook-explorer refreshed end-to-end:
- Replaced stale TreeDataProvider description with the current webview
sidebar + row-click-previews + '</>' go-to-source UX.
- Documented the inline '▶️ Preview Component' CodeLens.
- Expanded hook coverage table to include useComponent, useDefaultTool,
useHumanInTheLoop, useInterrupt, useRenderCustomMessages,
useRenderActivityMessage, useDefaultRenderTool, useLazyToolRenderer,
useCopilotAuthenticatedAction_c, useRenderToolCall — all 15 render
hooks covered with their preview shape.
- Added 'Behavior notes' section: auto-recovery on crash + reset on
selection change, controls persistence, Tailwind + local CSS flow-
through.
- Added imported-render support note.
/troubleshooting/event-inspector — added a back-link to Hook Explorer
at the bottom callout so the cross-link is bidirectional.
Per PR review suggestion (14) — a cpk- prefix makes collision with a
user-named agent essentially impossible. The earlier change only
documented the route as reserved; renaming it removes the hazard.
Rename scope:
- URL path segment (/debug-events → /cpk-debug-events) in the router,
handler switch arms, method-not-allowed check, and integration suite.
- RouteInfo union discriminator ('debug-events' → 'cpk-debug-events')
in hooks.ts and its two consumers in fetch-handler.ts.
- VS Code DebugStream client URL.
- Docs page (event-inspector.mdx) — both the Callout and the Steps copy.
Left unchanged (internal names that describe the feature but aren't the
public route):
- packages/runtime/src/v2/runtime/handlers/handle-debug-events.ts
- packages/runtime/src/v2/runtime/core/debug-event-bus.ts
- packages/shared/src/debug-event-envelope.ts (and the DebugEventEnvelope
type)
- 'debug-event' (singular) message type in the VS Code webview bridge —
that's the extension host ↔ webview protocol, not the HTTP route.
## Summary
Two showcase MDX files reference `<TailoredContent>` +
`<TailoredContentOption>` from
`@/components/react/tailored-content.tsx`, but the component file was
missing in showcase. This PR:
- Adds `showcase/shell/src/components/react/tailored-content.tsx`
(copied from upstream `docs/components/`)
- Inlines a tiny `cn()` helper to avoid pulling `classnames` into
showcase/shell deps
- Hardens BOTH copies (docs + showcase, kept byte-identical) against
real bugs found in CR review
## Bugs fixed in TailoredContent (both copies)
- **Build-breaker:** `useSearchParams()` in Next.js 14+ App Router
requires `<Suspense>` wrapper or `next build` fails. Added internal
Suspense wrapper so consumers don't need to add one.
- **State/URL desync:** `selectedIndex` was stored in useState
initialized once — back/forward nav didn't update. Now derived from
`searchParams` each render.
- **Keyboard a11y broken:** `role="tab"` + `tabIndex={0}` with no
keyboard handler. Added standard ARIA tab pattern: `role="tablist"`,
`role="tabpanel"`, Enter/Space to select, ArrowLeft/Right + Home/End to
navigate, roving tabindex.
- **`cloneElement` clobbered caller's icon className:** now merges via
`cn()`.
- **`TailoredContentOption` rendered `<div>` despite JSDoc saying "won't
render":** now returns `null`.
- **Unvalidated `defaultOptionIndex`:** clamped to `[0, options.length -
1]`.
- **Empty options silently produced broken UI:** now `return null`
(hooks-rules-safe; no throw mid-render).
- **Duplicate option IDs silently collided:** `console.warn` in dev mode
(via `useEffect`, not render body).
- **Hooks rules violation:** conditional hook ordering under state
changes (fixed by running all hooks unconditionally).
- **Side effects during render:** `console.warn` mutation moved to
`useEffect`.
- **`options`/`optionIds` unstable identities:** memoized via `useMemo`.
## Known remaining (non-blocking)
- The 2 copies of `tailored-content.tsx` must be kept in sync manually.
Proper fix is a shared package — out of scope for this PR.
- Stale `searchParams` race on rapid concurrent clicks across multiple
TailoredContent widgets on the same page (pre-existing upstream).
- `useMemo([children])` is ineffective since React.Children identity
changes per parent render (minor perf).
## Test plan
- [ ] CI green
- [ ] showcase-shell builds without Suspense errors
- [ ] Visit docs pages with `<TailoredContent>` — tabs render, keyboard
nav works, URL reflects selection
Mirror of #3868 by @Abubakar-01.
Wraps `agent.runAgent(...)` in a `useEffect` with an empty dependency
array in both the docs and showcase MDX files, and adds a prose warning
explaining why calling `runAgent` directly in the component body causes
"thread is already processing" errors.
## Summary
Resolves the recurring `docs-sync` manual-review flag on
`integrations/mastra/agent-app-context.mdx` by applying the sync
script's clean-transform to bring the showcase copy in line with
upstream, plus a small typo fix.
- Typo: `useCopilotReadble` → `useCopilotReadable` (both files)
- Clean-transform sync: restores 2 code-block imports
(`useAgentContext`, `useState` — both actually used in the example on
lines 40 + 32), normalizes whitespace
- Bumps `showcase/shell/.docs-sync-sha` from `41b6eb93` to `0e7811402`
## Note
There is an existing auto-generated PR #4044 covering this same file
(plus 2 aws-strands files). Close that PR after merging this one; the
aws-strands files will be handled by a separate future sync run once the
updated workflow (see branch `ci/docs-sync-auto-pr`) is merged.
## Test plan
- [ ] CI green
- [ ] Post-merge: `npx tsx showcase/scripts/sync-docs-from-main.ts
--dry-run` no longer flags this file for review
Add a sentence to the warning callout explaining that if agentId doesn't
match a runtime-registered agent, the interrupt will silently never fire.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Most framework integrations don't ship their own A2UI rendering tool, so the
shared snippet now guides users to inject `render_a2ui` via
`a2ui: { injectA2UITool: true }`. The LangGraph fixed-schema guide returns A2UI
operations directly from a Python tool, so the middleware auto-detects them and
tool injection is unnecessary — switched to `a2ui: {}` there with a note.
The docs table and prose claimed `debug: true` sets `verbose: true`,
but the implementation intentionally defaults verbose to false (PII
safety). Fixed the table and explanatory text to match.
Also removed packages/vscode-extension/README.md which was committed
on this branch by mistake — it describes an unrelated VS Code extension
and has nothing to do with debug mode.
Updated JSDoc and troubleshooting docs to accurately describe that
the client-side debug prop forwards config to the AG-UI transport
layer, not CopilotKit's own logging. Removed fabricated console.debug
output examples that don't exist.
Sam Julien