eslint-plugin-copilotkit-guardrails

ESLint rules enforcing CopilotKit v1.57.x runtime shape correctness. Targets shape A (CopilotKit-native BuiltInAgent + A2UI + AG-UI) by default; future shape B/C/D rules can be added without breaking existing consumers.

Why this exists

CopilotKit's v1 → v2 transition introduced a set of subtle traps that type-check silently but break at runtime or feature-load time. Real incidents observed in scaffolded codebases:

• CopilotRuntime imported from @copilotkit/runtime (root v1 class, no a2ui field), then a2ui: {...} added, then the field dropped to silence typecheck — shipping a broken agent with A2UI silently disabled.
• BuiltInAgent imported from a hypothetical @copilotkit/agent package (doesn't exist) or from the root subpath of @copilotkit/runtime (doesn't export it).
• defineTool written with Vercel AI SDK's inputSchema instead of CopilotKit's parameters.
• A2UI middleware paired with AnthropicAdapter (silently does nothing — A2UI doesn't inject through service adapters).
• app/api/copilotkit/route.ts missing export const runtime = "nodejs" (edge runtime breaks BuiltInAgent).
• System prompts piled with ALWAYS / NEVER rules instead of transmitted reasoning (brittle prompts that fight the model).

Each rule below catches one of those failure modes at lint time.

Install

pnpm add -D eslint-plugin-copilotkit-guardrails

Peer deps: eslint ^9.0.0. Optional: @typescript-eslint/parser ^8.0.0 if you want to lint TypeScript.

Configure

Flat config (eslint.config.mjs or eslint.config.js):

import copilotkitGuardrails from "eslint-plugin-copilotkit-guardrails";

export default [
  copilotkitGuardrails.configs.recommended,
  {
    settings: {
      copilotkit: { shape: "a" }, // default; explicit is better
    },
  },
];

Or pick rules individually:

import copilotkitGuardrails from "eslint-plugin-copilotkit-guardrails";

export default [
  {
    plugins: { "copilotkit-guardrails": copilotkitGuardrails },
    rules: {
      "copilotkit-guardrails/copilotkit-runtime-v2-import": "error",
      "copilotkit-guardrails/built-in-agent-import": "error",
      // ...
    },
  },
];

Settings

settings.copilotkit.shape: one of "a" | "b" | "c" | "d". Defaults to "a".

| Shape | Runtime | | ----- | ------------------------------------------------------------------------- | | a | CopilotKit-native BuiltInAgent (Vercel AI SDK under the hood). DEFAULT. | | b | In-process TypeScript LangGraph CoAgent. (Rules not yet shipped.) | | c | Remote Python LangGraph / CrewAI / Mastra / Agno CoAgent. (Not yet.) | | d | Direct AG-UI agent (custom AbstractAgent). (Not yet.) |

Shape-specific rules bail when shape doesn't match. As a v0.1 detail, only shape A rules ship.

Rules

All rules are error in the recommended config except where noted.

| Rule | Description | Autofix | | ------------------------------------------------------------------------------ | ------------------------------------------------------------------- | -------- | | copilotkit-runtime-v2-import | CopilotRuntime must come from @copilotkit/runtime/v2. | ✓ | | built-in-agent-import | BuiltInAgent must come from @copilotkit/runtime/v2. | ✓ | | define-tool-shape | defineTool uses parameters: z.object({...}), not inputSchema. | — | | no-a2ui-with-service-adapter | Reject a2ui paired with a service adapter (shape A only). | — | | route-nodejs-runtime | CopilotKit route must export runtime = "nodejs". | ✓ | | copilotkit-route-catchall | Route must live at [[...route]]/route.ts (catch-all) for v2. | — | | no-caps-stacking-in-prompt | Warn when system prompts pile on caps-stacking tokens. | — (warn) |

Changelog

v0.2.0

• Added copilotkit-route-catchall: requires the v2 route handler at app/api/copilotkit/[[...route]]/route.ts. Catches the flat-route silent-404 incident.
• Updated route-nodejs-runtime to match both flat and catch-all route paths.

v0.1.0

• Initial release with 6 rules.

Roadmap (v0.3+)

The doctrine that motivates this plugin lists 18 failure modes; v0.1–0.2 ship 7 of them. Likely additions:

• Catalog API hygiene (createCatalog arg shape, props: schema key)
• A2UI provider wiring (<CopilotKitProvider a2ui={{ catalog }}> vs nonexistent <A2UIProvider>)
• v1/v2 hook mixing (useCopilotAction v1 alongside useFrontendTool v2)
• Terminal frontend tool missing followUp: false
• Stylesheet path (@copilotkit/react-core/v2/styles.css)
• Reject copilotRuntimeNextJSAppRouterEndpoint in shape A
• Require both POST and GET exports from the v2 route handler
• Shape B/C/D rule sets

File issues for any failure modes that bite you in production scaffolds — they're prime candidates for new rules.

License

MIT — John Pearson.