Renames the docs CTA tracking event from `cta_clicked` to
`try_for_free_clicked` to match the per-event custom event names used
on the marketing website, and uses a single `location` string property
in place of the previous `surface` / `variant` / `target` / `page_path`
shape. Surface identifiers are normalized to underscored snake_case to
match the location values already used on the website.
Same change applies to the docs navbar handler that fires when a
visitor clicks the Free Developer Access link.
Adds a sign-up CTA to the shared `prebuilt-components` snippet so it
appears on all twelve per-integration `/{framework}/prebuilt-components`
pages that consume it, and adds a matching CTA to the LangGraph
prebuilt-components page (which uses custom content rather than the
shared snippet).
Moves the Built-in Agent overview CTA from below the features grid to
above the first H2 so it lands above the fold on standard viewports.
Places dashboard sign-up CTAs on topical pages, threads guides,
reference pages, and integration overview pages. Each CTA is tagged
with a stable surface identifier for PostHog attribution and routes to
the dashboard with matching UTM parameters.
Placements include:
- Home and quickstart landing pages
- Prebuilt-components, shared-state, and chat-related reference pages
- Threads how-to, tutorial, reference, and per-integration threads pages
(via the shared snippet)
- Inspector, event-inspector, and learning explainer pages
- Premium overview, observability, headless-ui, and self-hosting pages
(via the shared snippets)
- Integration overview pages — placed via the new afterFeatures slot on
the four FrameworkOverview-based pages (LangGraph, ADK, AWS Strands,
Microsoft Agent Framework) and below the features grid on Built-in
Agent
- Manual-setup quickstart pages (a2a, ag2, agent-spec, built-in-agent,
crewai-flows, deepagents)
Also normalizes platform copy across the affected pages.
Removes the unreleased Threads management surface (useThreads hook,
multi-conversation tutorial, the per-integration Threads how-to, the
shared snippet) and the Intelligence Platform / self-hosting pages
introduced alongside them, plus the ThreadsEarlyAccess gate that wrapped
them. The Learn landing page stays; just drops the Threads card and the
Intelligence Platform card. Sidebars (root, learn, reference/v2/hooks,
12 integrations + their premium subsections) are pruned to match.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
## 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
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>
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.
- Rewrite opening to address the user's problem (missing events, broken
state) rather than describing the feature
- Add cross-link callout from error-debugging → debug-mode and vice versa
- Fix [VERIFY] log format (remove incorrect colon)
- Move troubleshooting scenarios before reference tables since debugging
is the primary use case
- Fix clone() dropping debug config on ProxiedCopilotRuntimeAgent
- Pass raw DebugConfig to agents instead of collapsing to boolean
- Clamp verbose to false when enabled is false
- Fix pino-pretty log format in docs (parentheses, timestamps, levels)
- Add loggedEventCount to doc example
- Fix "Agent run started/finished" → actual log messages in arch docs
- Fix all doc imports to use @copilotkit/runtime/v2 (symbols only
exported from v2 entry point)
- Replace v1 copilotRuntimeNextJSAppRouterEndpoint with v2 pattern
(CopilotRuntime + createCopilotEndpoint + InMemoryAgentRunner)
- Add warning callout on TanStack reasoning example (reasoning events
not surfaced by TanStack converter)
- Fix randomUUID imports in converters: use @copilotkit/shared instead
of Node.js crypto to match codebase convention
- Fix collectEvents timer leak in test-helpers.ts (add clearTimeout)
- Fix JSDoc/comments: convertInputToTanStackAI accurately describes
role allowlist, TanStackInputResult.messages comment updated
- Close TOCTOU window: set abortController synchronously before Observable
creation in classic run(), matching factory run() pattern (M3)
- Add concurrent run guard to classic run() (C1)
- Add threadId/runId to RUN_ERROR events in classic mode (I2)
- Check both 'output' and 'result' property names in classic tool-result (C2/M2)
- Add try/catch around JSON.stringify in classic tool-result (I4/M2)
- Add undefined guards before emitting state snapshot/delta events (I3)
- Guard assignToolsToAgents against factory-mode agent configs (M1)
- Improve error handling in classic error case with proper fallback (C3)
- Improve TanStack converter TODO comment with known gap details (M5)
- Document @ts-expect-error on clone() middlewares access (S1)
- Add JSDoc to AgentFactoryContext.abortController (M4)
- Fix duplicate import and clean up react-router example
- Update docs AgentFactoryContext reference
Source fixes:
- Fix TOCTOU race in concurrent run guard — set abortController
synchronously before Observable creation, closing the window where
two run() calls could both pass the guard
- Add JSON.stringify try/catch in TanStack TOOL_CALL_RESULT handler
(matching existing aisdk.ts protection against circular refs)
- Use role allowlist (user/assistant/tool) instead of denylist in
convertInputToTanStackAI to exclude activity/reasoning roles
- Change error+abort handler from break to return in aisdk converter
to stop processing after error during abort
- Fix version-pinned comments (remove "AI SDK 5.0" reference)
Test fixes:
- Add timedOut flag to collectEventsIncludingErrors to distinguish
hung observables from normal completion
- Add clearTimeout on success/error to prevent timer leaks
- Remove timing-dependent setTimeout in concurrent run guard test
Docs fixes:
- Split imports: copilotRuntimeNextJSAppRouterEndpoint from
@copilotkit/runtime, Agent/converters from @copilotkit/runtime/v2
- Fix forwardedProps example: use CopilotKit properties prop
- Fix useCopilotChat → useCoAgent for state management reference
- Fix model syntax colon → slash (openai/gpt-4o)
Critical fixes:
- Guard concurrent run() calls — throw if agent is already running
- Check both "output" and "result" properties on AI SDK tool-result events
for compatibility with older AI SDK versions
- Handle undefined/missing error in AI SDK error events with proper
Error wrapping instead of throwing undefined
Important fixes:
- Add TOOL_CALL_RESULT handling to TanStack converter (was silently dropped)
- Include threadId and runId in RUN_ERROR events for run correlation
- Guard state tool events (STATE_SNAPSHOT/STATE_DELTA) against undefined
snapshot/delta fields before emitting
- Wrap JSON.stringify in tool-result with try/catch to handle circular refs
- Fix collectEventsIncludingErrors to distinguish error vs normal completion
Test coverage:
- Add tests for convertInputToTanStackAI (message filtering, tool call
mapping, context injection, state serialization)
- Add tests for state management tool results in AI SDK converter
- Add tests for async factory (Promise-returning) paths
- Add tests for tool-result property compatibility (output vs result)
- Add tests for error event handling edge cases
- Add tests for concurrent run guard and RUN_ERROR correlation fields
- Replace flaky setTimeout-based abort test with signal-based sync
Other:
- Add exhaustiveness check (default: never) in config type switch
- Document clone() @ts-expect-error coupling with AbstractAgent.middlewares
- Fix docs: remove incorrect "v6" version reference, fix wrong hook name
- New docs/(root)/migration-guides/ section with migrate-to-v2, migrate-attachments,
migrate-to-1.10.X, migrate-to-1.8.2
- Troubleshooting now only contains error-debugging, observability-connectors, common-issues
- Update all @deprecated JSDoc URLs from /troubleshooting/ to /migration-guides/
- Update doc cross-links (multimodal-attachments page, snippet import)
- Move snippet to snippets/shared/migration-guides/
- Set minimum version to v1.56.0 (was vX.Y.Z placeholder)
Attachment queue & previews:
- Image lightbox with View Transition API morph animation
- Video lightbox with native controls and play button overlay
- Document lightbox (PDF via blob URL, text inline, info card fallback)
- Drop zone overlay with upload icon
- Filename preservation via InputContent metadata
- Proper video thumbnail sizing and play/pause indicator
- Fix attachment queue positioning (max-w-3xl constraint)
- Padding between X button and content for audio/document cards
- Document filenames wrap instead of truncating
Attachments config:
- onUploadFailed callback for validation/upload errors (file-too-large, invalid-type, upload-failed)
- onUpload accepts sync or async returns
- AttachmentUploadResult discriminated union with explicit interfaces
- Metadata field on Attachment and onUpload return type
AG-UI version bump:
- Bump @ag-ui/client, @ag-ui/core, @ag-ui/encoder, @ag-ui/proto to 0.0.51
- Remove process.env Vite workaround (fixed upstream in 0.0.51)
Deprecation lifecycle:
- @deprecated JSDoc on all legacy image upload APIs
- ImageRenderer, ImageRendererProps, ImageUpload type, imageUploadsEnabled prop,
inputFileAccept prop, ImageRenderer prop, AIMessage.image, ImageData
- Codemod at codemods/migrate-attachments.ts (15 tests)
- Migration guide updated with codemod instructions and new type shapes
Docs:
- New guide: docs/(root)/multimodal-attachments.mdx
- Updated migration guide with onUpload return type, metadata, codemod section
- Cross-links from prebuilt-components and migration guide
- Label change: "Add photos or files" → "Add attachments"
Tests:
- CopilotChat.attachments.test.tsx — 5 tests for onUploadFailed
- migrate-attachments codemod — 15 tests
Moves the streaming performance tip into a reusable snippet and imports
it on both the root headless page and the v2 basics headless-ui snippet
(used by built-in-agent and a2a framework pages).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Update user-facing references from "LangGraph" to "LangChain" per CPK-7186.
The integration label, descriptions, and agent terminology now use "LangChain"
while preserving "LangGraph" for technical references (Platform, Studio, CLI,
StateGraph, code/package names, and API references).
- Rename integration label in integrations.ts, meta.json, integration-grid,
feature-matrix, quickstart-dropdown, and link-validation
- Update ~47 MDX docs: "LangGraph agent(s)" → "LangChain agent(s)"
- Update FAQ, snippets, and learn section references
- Keep URL paths (/langgraph) unchanged for backward compatibility
- Keep all code imports, package names, and LangGraph Platform/Studio/CLI as-is
https://claude.ai/code/session_01JAQ7P3GEeP2bGZtc6V45WY
SSE transport is no longer available. Update all MCP server setup
instructions to use HTTP transport with the /mcp endpoint, and
remove the Tadata callout.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The src/v1.x/ and src/v2.x/ directories were leftover artifacts from
the package consolidation. They contained only outdated configs, old
Cursor rules, superseded docs, and stale GitHub workflows — none
referenced by any code, build config, or Nx project.
Also fixes 3 broken doc links that pointed to src/v1.x/ paths.
Flatten all packages from packages/v1/* and packages/v2/* into packages/* —
every package now lives directly under the @copilotkit/ scope with no v1/v2
subdirectories.
- Move all v1 packages (react-core, react-ui, runtime, shared, etc.) from
packages/v1/* to packages/*
- Absorb v2 react code into packages/react-core/src/v2/ (exported via /v2 subpath)
- Absorb v2 agent code into packages/runtime/src/agent/ (exported via /v2 subpath)
- Move v2 packages (core, angular, demo-agents, etc.) to packages/*
- Replace all @copilotkitnext/* imports with @copilotkit/* equivalents
- Keep @copilotkitnext/angular as the sole exception (angular remains on next)
- Update CI workflows, renovate config, release scripts for flat structure
- No public API surface changes — all exports fields are preserved
Co-authored-by: Alem Tuzlak <t.zlak@hotmail.com>
Signed-off-by: Tyler Slaton <tyler@copilotkit.ai>
Shared MDX snippets had hardcoded langgraph URLs in IframeSwitcher
components. Now they accept a framework prop so each integration page
can specify its own feature viewer path.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- CopilotKit imports changed to V1 path (@copilotkit/react-core)
- useDefaultTool renamed to useDefaultRenderTool
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Sam Julien