Skip to content

BuilderIO/agent-native / .agents/skills/server-plugins

server-plugins

Verified

Framework server plugins and the `/_agent-native/` route namespace. Use when adding a custom server plugin, deciding whether to create an `/api/` route vs an action, or debugging auto-mounted framework routes.

Server Plugins & Framework Routes

Default Plugins (auto-mount)

Five default plugins auto-mount when your app doesn't have a custom version in server/plugins/:

PluginDefault behaviorCustomize when
agent-chatAgent chat endpointsCustom mentionProviders or systemPrompt
authAuth middlewareCustom publicPaths or Google OAuth config
core-routes/_agent-native/poll, /_agent-native/ping, etcCustom envKeys or sseRoute
resourcesResource CRUDRarely
terminalTerminal emulatorRarely

Only create plugin files for plugins you need to customize. Let defaults auto-mount.

Framework Route Namespace: /_agent-native/

All framework-level routes live under /_agent-native/ to avoid collisions with template-specific /api/* routes.

Hard rule

  • ALL framework routes go under /_agent-native/.
  • Templates own /api/* only for route-only domain concerns such as uploads, streaming, webhooks, OAuth callbacks, or non-JSON protocols.
  • Never put framework routes under /api/.
  • Never put template routes under /_agent-native/ — that namespace is reserved.
  • Never create /api/* routes that only wrap, proxy, or re-export actions. Use the existing /_agent-native/actions/:name endpoint or the React action hooks.

Auto-mounted framework routes

RoutePurpose
GET /_agent-native/pollPolling endpoint for DB change detection
GET /_agent-native/eventsSSE endpoint for real-time sync
GET /_agent-native/pingHealth check
GET/PUT/DELETE /_agent-native/application-state/:keyApplication state CRUD
GET/PUT/DELETE /_agent-native/application-state/compose/:idCompose draft CRUD
POST /_agent-native/agent-chatAgent chat SSE endpoint
GET /_agent-native/agent-chat/mentionsMention search for @-tagging
GET /_agent-native/env-statusEnv key configuration status
POST /_agent-native/env-varsSave env vars
/_agent-native/auth/*Authentication (login, session, logout)
/_agent-native/google/*Google OAuth (callback, auth-url, etc.)
/_agent-native/resources/*Resource CRUD
/_agent-native/actions/:nameAuto-mounted action endpoints
/_agent-native/available-clisAvailable CLI tools
/_agent-native/agent-terminal-infoTerminal connection info
/_agent-native/collab/*Real-time collaboration (see real-time-collab)
/_agent-native/a2aA2A JSON-RPC endpoint (see a2a-protocol)

Actions-First Approach

For standard CRUD and data operations, use defineAction in actions/ — the framework auto-mounts them as HTTP endpoints at /_agent-native/actions/:name. Only create custom /api/* routes for things actions can't do:

  • File uploads with multipart form data
  • Streaming responses
  • Webhooks from external services
  • OAuth callbacks

Before adding a route, inspect the existing action files. Reuse the action if it already encodes the business rule, or add a new action if the operation should be available to both the agent and the UI. A route whose implementation mostly calls an action is usually the wrong abstraction.

The Nitro Vite plugin handles both /api/ and /_agent-native/ prefixes via file-based routing in server/routes/.

Related Skills

  • actions — Prefer actions over custom /api/ routes
  • authentication — Auth middleware and session handling
  • portability — Use H3 (not Express) for all routes
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 319kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 319kUpdated Claude CodeCodexVerifiedInstall