@netlify/agent-runner-cli 2.16.0-server.1 → 2.17.0-PAW-612.0

package/dist/skills/netlify-server@netlifyserver/SKILL.md

@@ -9,20 +9,17 @@ A Netlify Server is one long-running Node.js process deployed alongside your sit
 
 ## When to use this skill: explicit request only
 
-Netlify Server is in Early Access. The rule for choosing it is strict:
+Netlify Server is an experimental primitive. The rule for choosing it is strict:
 
 - ONLY build with a Netlify Server when the prompt **explicitly requests a "Netlify Server"** by name (for example "build this as a Netlify Server" or "use the Netlify Server primitive").
 - If the prompt does not name it, discard this skill entirely, even when the request mentions Express, Hono, WebSockets, servers in general, or would otherwise seem like a good fit. In those cases use **Netlify Functions** (see the `netlify-functions` skill) and the other platform primitives as usual.
 - NEVER migrate an existing site's functions to a Netlify Server unless explicitly asked to.
 
-Once a Netlify Server has been explicitly requested:
-
-- Start without a template. Every template is a full-stack framework whose catch-all function takes the requests before the server, so the server would never receive traffic.
-- Implement all API routes inside the server app. Create files in `netlify/functions/` only for scheduled jobs (see below), never for endpoints.
+Once a Netlify Server has been explicitly requested: implement all API routes inside the server app, and do NOT create files in `netlify/functions/` alongside it.
 
 ## Quick start
 
-Create exactly one entrypoint at `netlify/server/index.mjs`.
+Create exactly one entrypoint at `netlify/server/index.mjs`. Any Node.js server works. It MUST listen on `process.env.PORT`.
 
 Express:
 
@@ -52,87 +49,49 @@ app.get('/api/hello', (c) => c.json({ hello: 'world' }))
 export default app
 ```
 
-What the entry file exports decides how Netlify runs it:
-
-- **An `http.Server`**, such as `http.createServer(app)`: requests go to that server. WebSocket libraries attached to it (`ws`, Socket.IO) work.
-- **An object with a `fetch` method**, such as a Hono app: called for each request.
-- **An Express app**, or a function with 3 or more parameters: hosted in an HTTP server Netlify creates. WebSocket upgrades get a `501`, so export `http.createServer(app)` instead when you need them.
-- **Any other function**: called as a handler `(request, context) => Response`, the same signature as a Netlify Function. A plain Node.js `(req, res)` listener lands here too and breaks; wrap it in `http.createServer()`.
-- **Anything else, or no default export**: Netlify waits for your code to start a server with `listen` on `process.env.PORT`, the way the framework's documentation shows. It must be listening within 10 seconds.
-
-A handler or `fetch` app accepts WebSockets with `upgradeWebSocket(request)` from `@netlify/server`, which returns `{ socket, response }`; return `response` from the handler.
-
 Declare dependencies in `package.json` as usual. Deploy is the normal site deploy; nothing extra to configure. The build log confirms detection with the line `Netlify Server detected at netlify/server/index.mjs`.
 
 ## Rules
 
 - **One entrypoint only.** `netlify/server/` must contain exactly one of `index.mjs`, `index.js`, `index.ts`, or `index.mts`. Two entry files fail the build. Prefer `index.mjs` with ESM syntax; split the rest of the server into modules that the entrypoint imports.
-- **A server that calls `listen` uses `process.env.PORT`.** It is set before your code is imported. Do not hardcode a port.
-- **Node.js 24 or later.** The server runs on the build's Node.js version, and the deploy fails on anything earlier.
+- **Listen on `process.env.PORT`.** It is set before your code is imported. Do not hardcode a port.
 - **Do not daemonize, fork, or spawn long-lived child processes.** One process serves the traffic.
 - Environment variables work as usual via `process.env`.
 - When adding npm modules, ensure `node_modules` is in `.gitignore`.
 
 ## Routing and static files
 
-By default, the server receives every request that nothing else in the project handles. Requests are handled in this order:
-
-1. Edge Functions.
-2. Redirect and rewrite rules.
-3. Static files in the publish directory.
-4. Netlify Functions, on the paths they're configured for.
-5. The server, for everything else (or only the paths it's configured for, see below).
+The server receives every request that is not served as a static file:
 
-Rules:
-
-- Files in the publish directory win over the server for matching paths, even on paths the server claims. Use the publish directory for assets like images, fonts, or a favicon.
+- Files in the publish directory win over the server for matching paths (`preferStatic`). Use the publish directory for assets like images, fonts, or a favicon.
 - Do NOT put an `index.html` in the publish directory if the server should render `/`. A static `index.html` shadows the server's root route.
-- A rewrite rule that matches every path, such as a single-page app's `/* /index.html 200`, sends requests to its destination instead of the server. Limit such rules to the paths the frontend handles.
-- Full-stack frameworks (Next.js, Nuxt, SvelteKit, Astro, TanStack Start) usually deploy a Netlify Function on `/*` that handles every request not served by a static file, covering both page rendering and the framework's API routes. Like the rewrite above, it takes those requests before the server does, so the server never receives any. If a Netlify Server is explicitly required, do not use a full-stack framework. Otherwise, put server code in the framework's own server routes.
-- There is no path prefix: the server sees its requests with their original paths.
-
-To have the server handle only some paths, set `path` (defaults to `/*`) and `excludedPath`, using the same syntax as function paths. Export them as `config` from the entry file, or set them in a `[server]` section in `netlify.toml`:
-
-```javascript
-export const config = {
-  path: '/api/*',
-  excludedPath: ['/api/legacy/*'],
-}
-```
+- There is no path prefix: the server sees `/`, `/api/anything`, and everything else, with the original paths.
 
 ## Lifecycle: scale to zero
 
 This is the most important mental model for building correctly:
 
-- After 5 minutes with no requests, the server is shut down. The next request starts a fresh process (a cold start).
+- After a period with no traffic, the server is shut down. The next request starts a fresh process (a cold start).
 - **All process memory is lost on every scale-to-zero, deploy, and platform maintenance event.** In-memory caches are fine as caches; they are NEVER storage. Anything that must survive belongs in Netlify Blobs or Netlify Database (see the `general-database` skill to choose).
-- Netlify can run several instances of the server at once (up to 3; 1 on Free and Personal plans). Each has its own memory and its own WebSocket connections; nothing in memory is shared between them.
-- In-flight requests and open WebSocket or Server-Sent Events connections are never cut off by the idle shutdown; while any are open, the instance stays running.
-- The server must send a response's status and headers within 20 seconds, or the request fails with a `502`. Stream slow responses, such as AI output, or respond right away and finish with `waitUntil`.
+- In-flight requests are never cut off by the idle shutdown.
 - Background work that outlives the request that triggered it (for example, responding early and then finishing a task) MUST be registered with `getContext().waitUntil(promise)`. Registered work keeps the process alive until the promise settles; unregistered work may be reclaimed the moment no requests are active.
-- Never keep the server alive on purpose: no self-pings, no timer that calls the server, no `waitUntil` chain that schedules more work to stay running, and no `scale.min` above `0` (during Early Access a deploy that sets it fails). Scale to zero is the design. If the user asks for an always-on server, explain this and build without it.
-- Scheduled or recurring work (cron, nightly cleanup, periodic sync) goes in a scheduled function (see the `netlify-functions` skill) that calls a server route. Never use `setInterval` or other timers meant to outlive a request.
 - `waitUntil` extends the idle lifetime, but deploys and platform maintenance still stop the process with only a short grace window. Keep background tasks short (seconds, not minutes), and persist anything critical before responding. For genuinely long jobs, persist a job record and process it in resumable increments across requests.
 
-Graceful shutdown hook (optional): register it with `onShutdown` from `@netlify/server`. It runs as soon as the instance starts stopping and receives `drained`, a promise that resolves once in-flight requests and `waitUntil` work have finished. Stop background work and close WebSockets right away, then `await drained` before releasing what that work still uses. Apps that already listen for `SIGTERM` keep working.
+Graceful shutdown hook (optional): export a `shutdown` function from the entrypoint; it is called before the process is stopped. Keep it fast (a few seconds), for example flushing a buffer to Blobs. For Express-style apps that call `listen`, you can also listen for `SIGTERM` directly.
 
 ```javascript
-import { onShutdown } from '@netlify/server'
-
-onShutdown(async ({ drained }) => {
-  wss.close()
-  await drained
-  await pool.end()
-})
+export const shutdown = async () => {
+  await flushPendingWrites()
+}
 ```
 
 ## Request context: geolocation, cookies, site metadata
 
-Inside request handling, get the Netlify request context with `getContext` from the `@netlify/server` package (add it to `package.json`):
+Inside request handling, get the Netlify request context with `getContext` from the `@netlify/functions` package (add it to `package.json`):
 
 ```javascript
 import express from 'express'
-import { getContext } from '@netlify/server'
+import { getContext } from '@netlify/functions'
 
 const app = express()
 
@@ -148,7 +107,6 @@ Rules:
 
 - ONLY call `getContext()` while handling a request (inside a route handler, middleware, or code awaited from one). It throws outside a request.
 - Works with every server form, including WebSocket upgrade handling.
-- Anything started inside a request (a `setInterval`, a lazily started background loop, a client that creates its own timers, WebSocket message handlers) keeps that request's context for its whole life, so `getContext()` there returns a stale request instead of throwing. Start long-lived work outside request handling, and never read per-request context from it.
 
 ### SSO user: `context.user`
 
@@ -168,62 +126,52 @@ See the [changelog post](https://www.netlify.com/changelog/2026-10-07-context-us
 
 The AI Gateway works with zero configuration: provider credentials and base URLs (`OPENAI_API_KEY`, `OPENAI_BASE_URL`, and equivalents for other providers) are injected into `process.env` automatically. See the `netlify-ai-gateway` skill for supported models and usage.
 
-AI Gateway, Netlify Blobs, and Netlify Database clients can be created once at module scope and reused: the platform keeps their credentials current. One exception: `NETLIFY_PURGE_API_TOKEN` expires after 15 minutes, so read it from `process.env` each time you call the purge API and never store it in a module-level variable.
+One rule specific to servers: **construct AI SDK clients inside request handling, never at module scope.** Credentials are injected per request, so they do not exist when the module is first imported.
 
 ```javascript
 import OpenAI from 'openai'
 
-const client = new OpenAI()
-
 app.post('/api/chat', async (req, res) => {
+  const client = new OpenAI() // created per request: credentials are available here
   // ...
 })
 ```
 
 ## WebSockets
 
-WebSockets work for servers that handle HTTP upgrades. Create the HTTP server, attach the WebSocket server to it, and export it. Starting it with `server.listen(process.env.PORT)` instead of exporting it works too.
+WebSockets work for servers that handle HTTP upgrades (the `listen` form). Attach the WebSocket server to the same HTTP server:
 
 ```javascript
 // netlify/server/index.mjs
-import { createServer } from 'node:http'
 import express from 'express'
 import { WebSocketServer } from 'ws'
 
 const app = express()
-const server = createServer(app)
-const wss = new WebSocketServer({ server, path: '/ws' })
-
-wss.on('connection', (ws) => {
-  ws.send('connected')
+const server = app.listen(process.env.PORT)
+const wss = new WebSocketServer({ noServer: true })
+
+server.on('upgrade', (req, socket, head) => {
+  if (req.url !== '/ws') {
+    socket.destroy()
+    return
+  }
+  wss.handleUpgrade(req, socket, head, (ws) => {
+    ws.send('connected')
+  })
 })
-
-export default server
 ```
 
 Rules for WebSocket clients you generate:
 
 - ALWAYS implement automatic reconnection with backoff in the browser client. The platform may terminate long-lived connections periodically; a reconnecting client makes this invisible to users.
 - Do not rely on a socket staying open indefinitely, and do not keep client state only on the server side of a socket: rebuild the needed state on reconnect.
-- Clients can be connected to different instances, and each instance only sees its own sockets. Keep state every client must see, such as chat history, in Netlify Database or Blobs.
-
-## Fetching user-supplied URLs
-
-An endpoint that fetches a URL taken from the request (link previews, webhook testers, image proxies) runs inside Netlify's network, so it must:
-
-- Accept only `http:` and `https:` URLs.
-- Resolve the hostname and refuse loopback, private, link-local, and unique-local addresses, including `169.254.169.254`.
-- Follow redirects manually (`redirect: 'manual'`) and check every hop the same way.
-- Return only what the feature needs (extracted fields, a capped body), never forward the caller's method, headers, or body. A generic `/proxy?url=` endpoint is an open relay; don't build one.
 
 ## Common mistakes
 
 - Treating process memory as a database. It is wiped on every cold start. Use Blobs or Database.
 - Hardcoding a port or defaulting to `3000` without reading `process.env.PORT` first.
 - Adding an `index.html` to the publish directory that shadows the server's `/` route.
-- Creating `netlify/functions/` endpoints alongside the server. Put API routes in the server app; use functions only for scheduled jobs.
+- Creating `netlify/functions/` endpoints alongside the server. Put API routes in the server app.
 - Two entry files in `netlify/server/` (for example both `index.mjs` and `index.ts`). Keep one.
 - Fire-and-forget background jobs without `getContext().waitUntil(promise)`. Unregistered work may be reclaimed mid-flight; registered work should still be short and non-critical.
-- Calling `getContext()` at module scope. It only works while handling a request.
-- Storing `NETLIFY_PURGE_API_TOKEN` in a module-level variable. Read it when you call the purge API.
-- Keeping the server warm with self-pings or timers, or running scheduled work with `setInterval`. Use a scheduled function that calls a server route.
+- Constructing AI SDK clients (or calling `getContext()`) at module scope. Per-request state does not exist at import time.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@netlify/agent-runner-cli",
   "type": "module",
-  "version": "2.16.0-server.1",
+  "version": "2.17.0-PAW-612.0",
   "description": "CLI tool for running Netlify agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -48,6 +48,7 @@
     "check:types": "tsc --noEmit",
     "prompts": "LOG=0 vitest run --config vitest.prompts.config.js",
     "site:build": "npm run prompts && node site/build.mjs",
+    "site:dev": "npm run site:build && netlify dev --dir site/dist",
     "postinstall": "node scripts/postinstall.js"
   },
   "engines": {

package/dist/skills/general-backend@backend/SKILL.md

@@ -1,78 +0,0 @@
----
-name: general-backend
-description: Use this skill whenever the task involves server-side code — API endpoints, backend logic, request handlers, WebSockets, server-side AI calls, auth checks, or any code that must run on a server rather than in the browser. Covers Netlify Server, Netlify Functions, Edge Functions, and full-stack framework server routes.
----
-
-# Server-side code on Netlify
-
-Where server-side code goes depends on the project. Work out which case applies before writing code, and for a
-new project, before scaffolding a template.
-
-## New project that needs a Netlify Server: no template
-
-The create-mode templates are built on a full-stack framework that deploys its server-side rendering as a Netlify
-Function on every path, so a Netlify Server added to a template project never receives requests. If the project
-needs a Netlify Server, don't scaffold a template. A new project needs one when it has any request-driven backend
-code: API endpoints, data saved and read through the backend, WebSockets, server-side AI calls, or an HTTP server
-framework such as Express, Hono, or Fastify.
-
-A site with no backend code (static pages, a marketing or content site, a client-only tool) needs neither a server
-nor functions. Use the templates as usual for it.
-
-## Project with a full-stack framework: use its server routes
-
-Full-stack frameworks (such as TanStack Start, Next.js, Astro, SvelteKit, Remix, Nuxt) build
-their own server code into Netlify Functions at deploy time. In these projects, put request handling in the
-framework's server routes or server functions instead of adding a Netlify Server. Call Netlify Database, Blobs, and
-the AI Gateway from those routes. Use Netlify Functions alongside them only for the cases listed under "Only when
-Server can't" below.
-
-HTTP server frameworks such as Express, Hono, Fastify, and Koa are different: nothing deploys them for you, so they
-run as a Netlify Server, covered next.
-
-## Otherwise: Netlify Server
-
-**Netlify Server** runs one long-running Node.js process (Express, Hono, Fastify, or plain `node:http`) from
-`netlify/server/index.mjs`. Put every request-driven piece of backend code in it:
-
-- API endpoints and route handlers
-- Server-rendered pages and form handling in your own routes
-- WebSockets and streaming responses
-- Calls to the Netlify AI Gateway, Netlify Database, and Netlify Blobs
-- Short work that continues after the response (seconds, such as sending an email), registered with `waitUntil`
-- Auth checks, webhooks from third-party services, proxies to external APIs
-
-Don't pick Functions just because the task is small or looks like a single endpoint.
-
-See the **netlify-server** skill for complete setup instructions and usage examples.
-
-## Only when Server can't: Netlify Functions
-
-Use **Netlify Functions** alongside the server only for:
-
-- **Scheduled functions**: work that runs on a cron schedule, with no incoming request.
-- **Event handlers**: code triggered by platform events, such as Netlify Forms submissions, Netlify Identity events
-  (signup, login, validate), or deploy events.
-- **Background functions**: jobs that can run longer than about a minute and must not be cut off midway, such as
-  generating a report or processing an upload (up to 15 minutes). When a server instance is replaced by a deploy or
-  scaling event, its background work gets only 90 seconds to finish. The server enqueues the job by calling the
-  background function and returns right away.
-
-Scheduled functions and event handlers run without an incoming request, which a server can't do, and background
-functions aren't cut off when a server instance is replaced. Everything else stays in the server, including the
-endpoints these functions talk to.
-
-See the **netlify-functions** skill for complete setup instructions and usage examples.
-
-## Request and response changes at the edge: Edge Functions
-
-Use **Edge Functions** for logic that runs on every request before it reaches the server or the site: rewrites and
-redirects based on geolocation or cookies, A/B tests, header changes, or lightweight auth checks. They run in Deno
-close to visitors and don't replace the server for application logic.
-
-See the **netlify-edge-functions** skill for setup instructions.
-
-## Existing projects
-
-If an existing project already serves its backend from `netlify/functions/`, keep using that for changes to it.
-Don't migrate an existing backend to a Netlify Server unless asked.