server-plugins

# 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/`: | Plugin | Default behavior | Customize when | | ------------- | ------------------------------------------------- | ------------------------------------------- | | `agent-chat` | Agent chat endpoints | Custom `mentionProviders` or `systemPrompt` | | `auth` | Auth middleware | Custom `publicPaths` or Google OAuth config | | `core-routes` | `/_agent-native/poll`, `/_agent-native/ping`, etc | Custom `envKeys` or `sseRoute` | | `resources` | Resource CRUD | Rarely | | `terminal` | Terminal emulator | Rarely | **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 | Route | Purpose | | ------------------------------------------------------------- | ---------------------------------------- | | `GET /_agent-native/poll` | Polling endpoint for DB change detection | | `GET /_agent-native/events` | SSE endpoint for real-time sync | | `GET /_agent-native/ping` | Health check | | `GET/PUT/DELETE /_agent-native/application-state/:key` | Application state CRUD | | `GET/PUT/DELETE /_agent-native/application-state/compose/:id` | Compose draft CRUD | | `POST /_agent-native/agent-chat` | Agent chat SSE endpoint | | `GET /_agent-native/agent-chat/mentions` | Mention search for @-tagging | | `GET /_agent-native/env-status` | Env key configuration status | | `POST /_agent-native/env-vars` | Save 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/:name` | Auto-mounted action endpoints | | `/_agent-native/available-clis` | Available CLI tools | | `/_agent-native/agent-terminal-info` | Terminal connection info | | `/_agent-native/collab/*` | Real-time collaboration (see `real-time-collab`) | | `/_agent-native/a2a` | A2A 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