@netlify/agent-runner-cli 1.132.0 → 1.133.0-ex-2327.0

package/dist/skills/netlify-functions/SKILL.md

@@ -109,6 +109,7 @@ export const config: Config = {
 | `preferStatic` | `boolean` | If `true`, static file takes precedence over function |
 | `method` | `string \| string[]` | HTTP method(s) to match (`GET`, `POST`, etc.) |
 | `schedule` | `string` | Cron expression for scheduled functions |
+| `background` | `boolean` | If `true`, run in background mode (fire-and-forget) |
 
 `path` and `excludedPath` support substring patterns or the URLPattern syntax from the web platform.
 
@@ -261,11 +262,11 @@ Returns `null` outside a function invocation.
 Background functions operate the same as standard serverless functions and are syntactically the same. They run for up
 to 15 minutes without blocking the client. The client receives an immediate 202 response.
 
-**Naming convention:** Append `-background` to the filename.
+Enable background mode by setting `background: true` in the function's config:
 
 ```typescript
-// netlify/functions/process-data-background.mts
-import type { Context } from '@netlify/functions'
+// netlify/functions/process-data.mts
+import type { Config, Context } from '@netlify/functions'
 
 export default async (req: Request, context: Context) => {
   const data = await req.json()
@@ -277,10 +278,14 @@ export default async (req: Request, context: Context) => {
 
   // Return value is ignored - client already received 202
 }
+
+export const config: Config = {
+  background: true,
+}
 ```
 
 ```javascript
-// netlify/functions/process-data-background.mjs
+// netlify/functions/process-data.mjs
 export default async (req, context) => {
   const data = await req.json()
 
@@ -288,6 +293,10 @@ export default async (req, context) => {
     await processItem(item)
   }
 }
+
+export const config = {
+  background: true,
+}
 ```
 
 **Key behavior:**
@@ -295,15 +304,14 @@ export default async (req, context) => {
 - Function continues executing for up to 15 minutes
 - Response body is ignored
 - No streaming support
-- Cannot use `config.path` or `config.schedule`
+- Cannot use `config.schedule`
 - Retry logic: first retry after 1 minute, second retry after 2 minutes on failure
 - Any data background functions produce should be stored in Netlify Blobs or a database
 
-**Valid background function paths:**
-- `netlify/functions/hello-background.mts`
-- `netlify/functions/hello-background/index.mts`
+**Legacy filename convention:** Naming the file with a `-background` suffix (e.g., `process-data-background.mts`) is still
+supported and continues to work. New functions should prefer the `config.background` property above.
 
-Invoke like any function: `POST /.netlify/functions/process-data-background`
+Invoke like any function: `POST /.netlify/functions/process-data` (or use the `path` config property).
 
 ## Scheduled Functions
 
@@ -385,6 +393,30 @@ schedule = "@daily"
 netlify functions:invoke daily-cleanup
 ```
 
+## Region
+
+Functions deploy to `cmh` (Ohio) by default. This is a deliberate choice: US East is centrally located for an international audience, has a broad provider ecosystem, and gives most projects the lowest overall latency without any configuration.
+
+Do NOT override `config.region` unless the user has stated a specific reason — for example, a database or backend service in another region with measurable roundtrip savings, a data-residency requirement, or an audience concentrated in one region whose compute dependencies (database, backend services) also live in that region.
+
+Two constraints to be aware of before adding `config.region`:
+
+- A function runs in exactly one region. Don't try to deploy the same function to multiple regions — if the user wants geo-routing, route between distinct functions with an edge function instead.
+- For framework adapter–generated functions (Next.js, Astro, Nuxt, etc.) the region must be set site-wide in the Netlify UI, not via `config.region` in code. The generated files can't carry per-function config.
+
+See [Region](https://docs.netlify.com/build/functions/configuration#region) for the full list of supported regions and details.
+
+## Memory or vCPU
+
+Functions run with 1024 MB of memory and a proportional amount of compute by default. The default fits most workloads, and raising it has a direct cost impact: function billing scales linearly with the configured size.
+
+Do NOT set `config.memory` or `config.vcpu` speculatively. Only reach for them when:
+
+- The workload is known to be memory- or compute-intensive (AI inference, image/PDF manipulation, large payload processing, CPU-bound work).
+- The function is hitting out-of-memory errors or timeouts caused by the function's own work, rather than by waiting on an external service or database.
+
+`memory` and `vcpu` configure the same underlying resource and are mutually exclusive — set one, not both. See [Memory or vCPU](https://docs.netlify.com/build/functions/configuration#memory-or-vcpu) for accepted values and the exact mapping.
+
 ## Response Streaming
 
 Synchronous functions can stream responses for large payloads (up to 20 MB):
@@ -405,6 +437,70 @@ export default async (req: Request) => {
 }
 ```
 
+## Event Handlers
+
+A function can subscribe to platform events by exporting an object instead of a function as its default. Each event has
+a named handler property.
+
+```typescript
+import type { DeploySucceededEvent, UserSignupEvent } from '@netlify/functions'
+
+export default {
+  deploySucceeded(event: DeploySucceededEvent) {
+    console.log(`Deploy ${event.deploy.id} succeeded`)
+  },
+
+  userSignup(event: UserSignupEvent) {
+    return {
+      user: {
+        ...event.user,
+        appMetadata: { ...event.user.appMetadata, roles: ['member'] },
+      },
+    }
+  },
+}
+```
+
+A single function can declare multiple handlers; multiple functions can also subscribe to the same event — both will run.
+
+The default export can also be an object with a `fetch` method instead of a bare function. Prefer the bare default export shown in [Handler Signature](#handler-signature); reach for the object form only if (1) other functions in the project already use it, or (2) the same function handles HTTP requests AND subscribes to one or more platform events:
+
+```typescript
+export default {
+  fetch(req: Request, context: Context) {
+    return new Response('Hello')
+  },
+}
+```
+
+**Available handlers:**
+
+| Handler | Trigger |
+|---|---|
+| `fetch` | HTTP request (equivalent to a bare function default export) |
+| `deployBuilding`, `deploySucceeded`, `deployFailed`, `deployDeleted`, `deployLocked`, `deployUnlocked` | Deploy lifecycle |
+| `userSignup`, `userLogin`, `userValidate`, `userModified`, `userDeleted` | Identity lifecycle |
+| `formSubmitted` | Form submission verified |
+
+### Identity handlers: deny an action
+
+`userSignup`, `userLogin`, `userValidate`, and `userModified` can reject the action by calling `event.deny()`. The end user
+receives a 401. Do NOT throw — `event.deny()` is the canonical denial mechanism and does not produce an error in observability.
+
+```typescript
+import type { UserLoginEvent } from '@netlify/functions'
+
+export default {
+  userLogin(event: UserLoginEvent) {
+    if (!event.user.email?.endsWith('@example.com')) {
+      return event.deny()
+    }
+  },
+}
+```
+
+If multiple functions subscribe to the same event, the first to call `event.deny()` aborts the chain.
+
 ## Limits
 
 | Resource | Limit |
@@ -418,8 +514,6 @@ export default async (req: Request) => {
 | Streaming response payload | 20 MB |
 | Functions per site | Unlimited |
 
-**Default deployment region:** `us-east-2` (configurable on Pro/Enterprise plans)
-
 ## Common Errors & Solutions
 
 ### "Function not found" (404)

package/dist/skills/netlify-identity/SKILL.md

@@ -404,46 +404,69 @@ TanStack Start, and SvelteKit. Remix `redirect()` is safe because Remix actions
 
 ## Identity Event Functions
 
-Special serverless functions that trigger on Identity lifecycle events. These use the **legacy named `handler` export**
-(not the modern default export) because they receive `event.body` containing the user payload.
+Subscribe to Identity lifecycle events by exporting an object whose properties are named event handlers. See the
+**netlify-functions** skill for the full event-handler pattern.
 
-Always use the legacy named `handler` export (not default export) for Identity event functions. The filename must match
-the event name exactly (e.g., `netlify/functions/identity-signup.mts`).
+**Available identity handlers:**
 
-**Event names:** `identity-validate`, `identity-signup`, `identity-login`
+| Handler | Trigger |
+|---|---|
+| `userValidate` | A user attempts to sign up. Can deny the signup. |
+| `userSignup` | A user completes signup. Can deny or mutate. |
+| `userLogin` | A user logs in. Can deny or mutate. |
+| `userModified` | A user's profile is updated. Can deny or mutate. |
+| `userDeleted` | A user is deleted. Notification only. |
 
-- `identity-signup` - fires when a new user signs up (email/password or OAuth)
-- `identity-login` - fires on each login
-- `identity-validate` - fires during signup before the user is created; return a non-200 status to reject
+Each handler receives a typed event with a parsed `user` object (camelCase fields: `appMetadata`, `userMetadata`,
+`confirmedAt`, etc.).
 
 ### Example: Assign Default Role on Signup
 
+Return `{ user: ... }` to substitute the user record before it's persisted.
+
 ```typescript
-// netlify/functions/identity-signup.mts
-import type { Handler, HandlerEvent, HandlerContext } from '@netlify/functions'
-
-const handler: Handler = async (event: HandlerEvent, context: HandlerContext) => {
-  const { user } = JSON.parse(event.body || '{}')
-
-  return {
-    statusCode: 200,
-    body: JSON.stringify({
-      app_metadata: {
-        ...user.app_metadata,
-        roles: ['member'],
+// netlify/functions/identity.mts
+import type { UserSignupEvent } from '@netlify/functions'
+
+export default {
+  userSignup(event: UserSignupEvent) {
+    return {
+      user: {
+        ...event.user,
+        appMetadata: {
+          ...event.user.appMetadata,
+          roles: ['member'],
+        },
       },
-    }),
-  }
+    }
+  },
 }
+```
+
+### Deny an Action
+
+Call `event.deny()` to reject a signup, login, validation, or modification. The end user receives a 401. Do NOT throw —
+`event.deny()` is the canonical denial mechanism and does not produce an error in observability.
 
-export { handler }
+```typescript
+import type { UserValidateEvent } from '@netlify/functions'
+
+export default {
+  userValidate(event: UserValidateEvent) {
+    if (!event.user.email?.endsWith('@example.com')) {
+      return event.deny()
+    }
+  },
+}
 ```
 
-The response body replaces `app_metadata` and/or `user_metadata` on the user record - include all fields you want to
-keep, not just new ones.
+If multiple functions subscribe to the same event, the first to call `event.deny()` aborts the chain.
+
+For bulk user management or role changes outside lifecycle events, use the `admin` API instead of Identity event functions.
 
-For bulk user management or role changes outside lifecycle events, use the `admin` API instead of Identity event
-functions.
+**Legacy filename convention:** The previous syntax — files named `identity-validate.ts`, `identity-signup.ts`, or
+`identity-login.ts` (with a `-background` suffix for background mode), exporting `handler` and signaling denial via a
+non-2xx response — still works. New functions should prefer the typed handler syntax above.
 
 ## Roles and Authorization
 
@@ -456,7 +479,7 @@ The first admin user cannot be created through code alone. You must direct the u
 3. After the user accepts the invite, click the user in the Identity list to open their detail page
 4. In the **Roles** field, add the `admin` role and save
 
-Once the first admin exists, subsequent users can be managed programmatically using Identity event functions (e.g., assigning roles in `identity-signup`) or role-based redirects.
+Once the first admin exists, subsequent users can be managed programmatically using Identity event functions (e.g., assigning roles in the `userSignup` handler) or role-based redirects.
 
 ### Metadata Types
 
@@ -542,13 +565,15 @@ if (newToken) {
 
 ### Identity event function not triggering
 
-**Cause:** Filename or export format does not match expected convention.
+**Cause:** Export shape does not match the expected pattern.
 
 **Fix:**
 
-1. Verify filename matches exactly: `identity-signup`, `identity-validate`, or `identity-login`
-2. Place in `netlify/functions/` with `.mts` or `.mjs` extension
-3. Use named `handler` export (not default export)
+1. Use the typed handler syntax: default export an object with `userSignup`, `userLogin`, `userValidate`, `userModified`,
+   or `userDeleted` methods
+2. Place the function in `netlify/functions/` with `.mts` or `.mjs` extension
+3. If using the legacy filename convention, verify the filename matches the event exactly (`identity-signup.mts`,
+   `identity-validate.mts`, or `identity-login.mts`) and that the file exports a named `handler`
 
 ### `MissingIdentityError`
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@netlify/agent-runner-cli",
   "type": "module",
-  "version": "1.132.0",
+  "version": "1.133.0-ex-2327.0",
   "description": "CLI tool for running Netlify agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -59,7 +59,7 @@
     "@commitlint/config-conventional": "^20.0.0",
     "@eslint/compat": "^2.0.0",
     "@eslint/js": "^9.35.0",
-    "@netlify/axis": "^1.15.0",
+    "@netlify/axis": "^1.17.0",
     "@netlify/eslint-config-node": "^7.0.1",
     "@types/node": "^24.5.0",
     "@typescript-eslint/eslint-plugin": "^8.0.0",