@netlify/agent-runner-cli 2.17.0-PAW-612.0 → 2.18.0-smtp.0

package/dist/skills/netlify-identity/references/advanced-patterns.md

@@ -0,0 +1,104 @@
+# Advanced Identity Patterns
+
+## Password Recovery
+
+Three-step flow: request recovery email, handle the callback, then set a new password.
+
+```typescript
+import { requestPasswordRecovery, handleAuthCallback, updateUser, AuthError } from '@netlify/identity'
+
+// Step 1: Send recovery email
+async function handleForgotPassword(email: string) {
+  try {
+    await requestPasswordRecovery(email)
+    showSuccess('Check your email for a password reset link.')
+  } catch (error) {
+    if (error instanceof AuthError) showError(error.message)
+  }
+}
+
+// Step 2: handleAuthCallback() returns { type: 'recovery', user } — show password reset form
+// (See the handleAuthCallback switch in SKILL.md)
+
+// Step 3: Set new password
+async function handlePasswordReset(newPassword: string) {
+  try {
+    await updateUser({ password: newPassword })
+    showSuccess('Password updated.')
+  } catch (error) {
+    if (error instanceof AuthError) showError(error.message)
+  }
+}
+```
+
+The recovery callback fires a `'recovery'` auth event, not `'login'`. The user is authenticated but should be prompted to set a new password before navigating away.
+
+## Invite Acceptance
+
+When a user clicks an invite link, `handleAuthCallback()` returns `{ type: 'invite', user: null, token }`. Use the token to accept the invite and set a password.
+
+```typescript
+import { acceptInvite, AuthError } from '@netlify/identity'
+
+async function handleAcceptInvite(token: string, password: string) {
+  try {
+    const user = await acceptInvite(token, password)
+    showSuccess(`Welcome, ${user.email}! Your account is ready.`)
+  } catch (error) {
+    if (error instanceof AuthError) showError(error.message)
+  }
+}
+```
+
+## Email Change
+
+When a user verifies an email change, `handleAuthCallback()` returns `{ type: 'email_change', user }` with the change already applied — the returned `user` carries the new email. The user must be logged in when clicking the verification link.
+
+Like recovery (and unlike invite acceptance), there is no token to consume and no follow-up call — `handleAuthCallback()` does the work. Handle it in the `handleAuthCallback()` switch (see SKILL.md) and confirm the new address.
+
+```typescript
+// In the handleAuthCallback() switch (see SKILL.md):
+case 'email_change':
+  showSuccess(`Email updated to ${result.user?.email}`)
+  break
+```
+
+If you process the verification token yourself instead of letting `handleAuthCallback()` read the URL hash, call `verifyEmailChange(token)` directly — it applies the change and returns the updated user.
+
+## Session Hydration
+
+`hydrateSession()` bridges server-set cookies to the browser session. Call it on page load when using server-side login (e.g., login inside a Netlify Function followed by a redirect).
+
+```typescript
+import { hydrateSession } from '@netlify/identity'
+
+const user = await hydrateSession()
+if (user) {
+  // Browser session is now in sync with server-set cookies
+}
+```
+
+`getUser()` auto-hydrates from the `nf_jwt` cookie if no browser session exists, so explicit `hydrateSession()` is only needed when you want to restore the full session (including token refresh timers) after a server-side login.
+
+## SSR Integration Patterns
+
+For SSR frameworks, the recommended pattern is:
+
+- **Browser-side** for auth mutations: `login()`, `signup()`, `logout()`, `oauthLogin()`
+- **Server-side** for reading auth state: `getUser()`, `getSettings()`, `getIdentityConfig()`
+
+Browser-side auth mutations set the `nf_jwt` cookie and localStorage, and emit `onAuthChange` events. The server reads the cookie on the next request.
+
+The library also supports server-side mutations (`login()`, `signup()`, `logout()` inside Netlify Functions), but these require the Netlify Functions runtime to set cookies. After a server-side mutation, use a full page navigation so the browser sends the new cookie.
+
+Always use `window.location.href` (not framework router navigation) after server-side auth mutations in Next.js, TanStack Start, and SvelteKit. Remix `redirect()` is safe because Remix actions return real HTTP responses.
+
+## Full API Reference
+
+For the complete API reference — all function signatures, type definitions, OAuth helpers, admin operations, session management, auth events, and framework-specific examples — read the package README:
+
+```
+node_modules/@netlify/identity/README.md
+```
+
+The README is shipped with the npm package and is always in sync with the installed version.

package/dist/skills/netlify-identity/references/authorization-and-sessions.md

@@ -0,0 +1,24 @@
+# Netlify Identity — authorization and session gotchas
+
+Where role-based access actually gets enforced, and why a role change doesn't take effect immediately.
+
+## Admin operations run only in the Functions runtime
+
+Identity's admin API — creating users, updating a user's roles or metadata, deleting users (the `admin.*` operations) — requires a privileged admin token that is available **only in the Netlify Functions runtime**. It is not exposed to browser code and is not available in Edge Functions. Do all role assignment and user administration from inside a modern v2 Function (or an Identity event function), never from the client and never from an edge function. A "promote this user to admin" button in the UI must call a Function endpoint that performs the change server-side — it cannot call the admin API directly from the browser.
+
+You don't configure or read the admin token yourself — the Netlify Functions runtime provides it automatically to `admin.*` calls made inside a Function, so there is no env var to set and no `Netlify.env.get(...)` to call for it. Run the `admin.*` operations server-side in a Function; never hardcode an admin token, ship one in the client bundle, or expose the admin operations to the browser. Exposing an admin capability client-side would let any visitor grant themselves the `admin` role.
+
+## Redirect gating only covers CDN document requests
+
+`conditions = { Role = [...] }` redirects are enforced by the CDN **only when it serves a document (navigation) request** — a fresh HTTP request for the path. They are a coarse page-level perimeter, not real authorization:
+
+- **SPA client-side navigation bypasses them.** When a client-side router (React, Vue, SvelteKit, etc.) navigates to `/admin` in the browser, no new document request reaches the CDN, so the redirect rule never runs and the route renders regardless of the user's role.
+- **Anything in the client bundle is downloadable by anyone.** Role-gated content compiled into the JavaScript bundle ships to every visitor who can load the page; hiding a component behind a client-side role check does not protect the data inside it.
+
+So use redirect gating for coarse routing only. Enforce anything sensitive **server-side on every request** — a Netlify Function (or the API it calls) that resolves the user with `getUser()` and checks the server-controlled `app_metadata.roles` — never a client-side route guard or a hidden UI element as the only gate.
+
+## Role changes don't affect live sessions until the JWT refreshes
+
+Roles are baked into the `nf_jwt` when the token is issued, and that JWT stays valid until it expires (about an hour). Changing a user's roles — via the dashboard, the admin API, or an Identity event function — does **not** update tokens already held by signed-in users. A user you just promoted keeps seeing the old view, and a user whose role you just revoked keeps their access, until their token refreshes (`AUTH_EVENTS.TOKEN_REFRESH`) or they log out and log back in. Both redirect `Role` conditions and function-side `app_metadata.roles` checks read the current token, so both see the stale roles until then.
+
+Don't expect a role change to take effect mid-session. When it needs to apply right away, direct the user to log out and back in (or otherwise refresh their token) so a new `nf_jwt` carrying the updated roles is issued.

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

@@ -0,0 +1,225 @@
+---
+name: netlify-server
+description: Run a long-running HTTP server (Express, Hono, Fastify, or plain node:http) on Netlify. The default for server-side code — API endpoints, backend logic, WebSockets, server-side AI calls. Use Netlify Functions only for scheduled jobs, long background jobs, and platform event handlers.
+---
+
+# Netlify Server
+
+A Netlify Server is one long-running Node.js process deployed alongside your site. Unlike Netlify Functions, which run per request, the server process is started once, reused across requests, scaled to zero when idle, and started again on the next request. It runs standard Node.js servers with no Netlify-specific APIs: if it listens on a port, it works.
+
+## When to use this skill
+
+Use a Netlify Server for server-side code by default (see the `general-backend` skill):
+
+- Start a new project that needs a Netlify Server 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 and request-driven backend code inside the server app.
+- Create files in `netlify/functions/` alongside it ONLY for scheduled functions, background functions for jobs that can run longer than about a minute, and platform event handlers (Forms submissions, Identity events, deploy events). See the `netlify-functions` skill.
+- NEVER migrate an existing site's functions to a Netlify Server unless explicitly asked to.
+
+## Quick start
+
+Create exactly one entrypoint at `netlify/server/index.mjs`.
+
+Express:
+
+```javascript
+// netlify/server/index.mjs
+import express from 'express'
+
+const app = express()
+
+app.get('/api/hello', (req, res) => {
+  res.json({ hello: 'world' })
+})
+
+app.listen(process.env.PORT)
+```
+
+Hono (no `listen` call; export the app as the default export):
+
+```javascript
+// netlify/server/index.mjs
+import { Hono } from 'hono'
+
+const app = new Hono()
+
+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.
+- **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).
+
+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.
+- 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 the project needs a Netlify Server (see the `general-backend` skill), 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/*'],
+}
+```
+
+## 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).
+- **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`.
+- 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, call a background function from the server (see the `netlify-functions` skill), or 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.
+
+```javascript
+import { onShutdown } from '@netlify/server'
+
+onShutdown(async ({ drained }) => {
+  wss.close()
+  await drained
+  await pool.end()
+})
+```
+
+## 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`):
+
+```javascript
+import express from 'express'
+import { getContext } from '@netlify/server'
+
+const app = express()
+
+app.get('/api/where', (req, res) => {
+  const context = getContext()
+  res.json({ city: context.geo?.city, country: context.geo?.country?.name })
+})
+
+app.listen(process.env.PORT)
+```
+
+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`
+
+On private projects and sites protected by Netlify team login, the context also carries the user who signed in through Netlify's SSO: `context.user` with `id`, `email`, and `expiresAt` (a `Date`). It is `undefined` when the request didn't come from such a user. Netlify verifies the visitor and sets it itself, so it can't be spoofed with request headers. This is the Netlify team member viewing the site, not a Netlify Identity user.
+
+```javascript
+app.get('/api/whoami', (req, res) => {
+  const { user } = getContext()
+  if (!user) return res.status(401).send('Unauthorized')
+  res.json({ id: user.id, email: user.email })
+})
+```
+
+See the [changelog post](https://www.netlify.com/changelog/2026-10-07-context-user-in-functions/).
+
+## AI inference: Netlify AI Gateway
+
+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.
+
+```javascript
+import OpenAI from 'openai'
+
+const client = new OpenAI()
+
+app.post('/api/chat', async (req, res) => {
+  // ...
+})
+```
+
+## 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.
+
+```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')
+})
+
+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, long background jobs, and event handlers.
+- 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.

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

@@ -9,17 +9,20 @@ 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 an experimental primitive. The rule for choosing it is strict:
+Netlify Server is in Early Access. 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: implement all API routes inside the server app, and do NOT create files in `netlify/functions/` alongside it.
+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.
 
 ## Quick start
 
-Create exactly one entrypoint at `netlify/server/index.mjs`. Any Node.js server works. It MUST listen on `process.env.PORT`.
+Create exactly one entrypoint at `netlify/server/index.mjs`.
 
 Express:
 
@@ -49,49 +52,87 @@ 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.
-- **Listen on `process.env.PORT`.** It is set before your code is imported. Do not hardcode a port.
+- **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.
 - **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
 
-The server receives every request that is not served as a static file:
+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).
 
-- 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.
+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.
 - 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.
-- There is no path prefix: the server sees `/`, `/api/anything`, and everything else, with the original paths.
+- 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/*'],
+}
+```
 
 ## Lifecycle: scale to zero
 
 This is the most important mental model for building correctly:
 
-- After a period with no traffic, the server is shut down. The next request starts a fresh process (a cold start).
+- After 5 minutes with no requests, 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).
-- In-flight requests are never cut off by the idle shutdown.
+- 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`.
 - 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): 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.
+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.
 
 ```javascript
-export const shutdown = async () => {
-  await flushPendingWrites()
-}
+import { onShutdown } from '@netlify/server'
+
+onShutdown(async ({ drained }) => {
+  wss.close()
+  await drained
+  await pool.end()
+})
 ```
 
 ## Request context: geolocation, cookies, site metadata
 
-Inside request handling, get the Netlify request context with `getContext` from the `@netlify/functions` package (add it to `package.json`):
+Inside request handling, get the Netlify request context with `getContext` from the `@netlify/server` package (add it to `package.json`):
 
 ```javascript
 import express from 'express'
-import { getContext } from '@netlify/functions'
+import { getContext } from '@netlify/server'
 
 const app = express()
 
@@ -107,6 +148,7 @@ 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`
 
@@ -126,52 +168,62 @@ 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.
 
-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.
+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.
 
 ```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 (the `listen` form). Attach the WebSocket server to the same HTTP server:
+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.
 
 ```javascript
 // netlify/server/index.mjs
+import { createServer } from 'node:http'
 import express from 'express'
 import { WebSocketServer } from 'ws'
 
 const app = express()
-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')
-  })
+const server = createServer(app)
+const wss = new WebSocketServer({ server, path: '/ws' })
+
+wss.on('connection', (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.
+- Creating `netlify/functions/` endpoints alongside the server. Put API routes in the server app; use functions only for scheduled jobs.
 - 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.
-- Constructing AI SDK clients (or calling `getContext()`) at module scope. Per-request state does not exist at import time.
+- 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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@netlify/agent-runner-cli",
   "type": "module",
-  "version": "2.17.0-PAW-612.0",
+  "version": "2.18.0-smtp.0",
   "description": "CLI tool for running Netlify agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -20,6 +20,7 @@
   "scripts": {
     "prebuild": "rm -rf dist",
     "build": "tsup",
+    "build:bundle": "tsup --no-dts",
     "dev": "tsup --watch",
     "prepare": "husky install node_modules/@netlify/eslint-config-node/.husky/",
     "prepublishOnly": "npm ci && npm test",
@@ -34,7 +35,7 @@
     "format:check:prettier": "prettier --check --ignore-path .gitignore --loglevel=warn \"{src,scripts,test,.github}/**/*.{js,ts,md,yml,json,html}\" \"*.{js,ts,yml,json,html}\" \".*.{js,ts,yml,json,html}\" \"!**/package-lock.json\" \"!package-lock.json\" \"!src/skills/**/*.md\" \"!src/lib/__fixtures__/**\"",
     "format:fix:prettier": "prettier --write --ignore-path .gitignore --loglevel=warn \"{src,scripts,test,.github}/**/*.{js,ts,md,yml,json,html}\" \"*.{js,ts,yml,json,html}\" \".*.{js,ts,yml,json,html}\" \"!**/package-lock.json\" \"!package-lock.json\" \"!src/skills/**/*.md\" \"!src/lib/__fixtures__/**\"",
     "test:dev": "run-s build test:dev:*",
-    "test:ci": "run-s build test:ci:*",
+    "test:ci": "run-s build:bundle test:ci:*",
     "test:dev:vitest": "LOG=0 vitest --exclude '**/integration/**'",
     "test:ci:vitest": "LOG=0 vitest run --coverage --exclude '**/integration/**'",
     "test:smoke": "node scripts/smoke-dist.js",
@@ -43,6 +44,7 @@
     "test:integration:claude": "vitest run test/integration/claude.test.ts",
     "test:integration:gemini": "vitest run test/integration/gemini.test.ts",
     "test:integration:opencode": "vitest run test/integration/opencode.test.ts",
+    "test:integration:antigravity": "vitest run test/integration/antigravity.test.ts",
     "test:integration:muse": "vitest run test/integration/muse.test.ts",
     "test:integration:skill-invocation": "vitest run test/integration/skill-invocation.test.ts",
     "check:types": "tsc --noEmit",
@@ -96,7 +98,7 @@
     "@google/gemini-cli": "0.63.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@netlify/cache-utils": "^6.0.5",
-    "@netlify/database-proxy": "^0.2.2",
+    "@netlify/database-proxy": "^0.2.3",
     "@netlify/otel": "^6.0.6",
     "@netlify/ts-cli": "^1.2.0",
     "@openai/codex": "0.162.0",