mirror of
https://github.com/CopilotKit/CopilotKit.git
synced 2026-09-14 16:26:20 +08:00
Jordan Ritter
4b4923561b
## 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