@primitivedotdev/cli 0.35.1 → 0.37.0

package/dist/oclif/index.js

@@ -1,4 +1,4 @@
-import { A as createConfig, C as chatStatePath, D as saveActiveChatState, E as loadChatConversationByLocalId, O as PrimitiveApiClient, S as saveCliCredentials, T as loadActiveChatState, _ as deleteCliCredentials, a as normalizeCliEnvironmentName, b as normalizeApiBaseUrl, c as resolveConfigEnvironment, d as validateCliHeaderName, f as validateCliHeaderValue, g as credentialsPath, h as credentialsLockPath, i as loadCliConfig, k as createClient, l as saveCliConfig, m as cliAccessTokenExpiresAt, n as deleteCliConfig, o as redactCliEnvironment, p as acquireCliCredentialsLock, r as emptyCliConfig, s as removeCliEnvironment, u as upsertCliEnvironment, v as deleteCliCredentialsLock, w as deleteChatState, x as resolveCliAuth, y as loadCliCredentials } from "../cli-config-DREZ2BxT.js";
+import { A as createClient, C as saveCliCredentials, D as loadChatConversationByLocalId, E as loadActiveChatState, O as saveActiveChatState, S as resolveCliAuth, T as deleteChatState, _ as deleteCliCredentials, a as normalizeCliEnvironmentName, b as loadCliCredentials, c as resolveConfigEnvironment, d as validateCliHeaderName, f as validateCliHeaderValue, g as credentialsPath, h as credentialsLockPath, i as loadCliConfig, j as createConfig, k as PrimitiveApiClient, l as saveCliConfig, m as cliAccessTokenExpiresAt, n as deleteCliConfig, o as redactCliEnvironment, p as acquireCliCredentialsLock, r as emptyCliConfig, s as removeCliEnvironment, u as upsertCliEnvironment, v as deleteCliCredentialsLock, w as chatStatePath, x as normalizeApiBaseUrl, y as detectPrimitiveKeyEnvMisname } from "../cli-config-D7wN_PBc.js";
 import { Args, Command, Errors, Flags, ux } from "@oclif/core";
 import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
@@ -44,8 +44,10 @@ var sdk_gen_exports = /* @__PURE__ */ __exportAll({
 	getConversation: () => getConversation,
 	getEmail: () => getEmail,
 	getFunction: () => getFunction,
+	getFunctionRouting: () => getFunctionRouting,
 	getFunctionTestRunTrace: () => getFunctionTestRunTrace,
 	getInboxStatus: () => getInboxStatus,
+	getOrgRoutingTopology: () => getOrgRoutingTopology,
 	getSendPermissions: () => getSendPermissions,
 	getSentEmail: () => getSentEmail,
 	getStorageStats: () => getStorageStats,
@@ -70,12 +72,14 @@ var sdk_gen_exports = /* @__PURE__ */ __exportAll({
 	searchEmails: () => searchEmails,
 	semanticSearch: () => semanticSearch,
 	sendEmail: () => sendEmail,
+	setFunctionRoute: () => setFunctionRoute,
 	setFunctionSecret: () => setFunctionSecret,
 	startAgentSignup: () => startAgentSignup,
 	startCliLogin: () => startCliLogin,
 	startCliSignup: () => startCliSignup,
 	testEndpoint: () => testEndpoint,
 	testFunction: () => testFunction,
+	unsetFunctionRoute: () => unsetFunctionRoute,
 	updateAccount: () => updateAccount,
 	updateDomain: () => updateDomain,
 	updateEndpoint: () => updateEndpoint,
@@ -1102,11 +1106,13 @@ const listFunctions = (options) => (options?.client ?? client).get({
 * attempt, and sent to the runtime so stack traces can resolve to
 * original source files.
 *
-* **Auto-wiring.** On successful deploy, Primitive automatically
-* creates a webhook endpoint that delivers inbound mail to the
-* function. There is nothing to configure on the Endpoints API
-* for this to work; the internal runtime URL is not returned by
-* the API and is not a customer-facing integration surface.
+* **Routing.** On successful deploy, the function code is live
+* in the runtime, but inbound mail will not reach it until at
+* least one route is bound. Routes are managed from the Primitive
+* dashboard. A `deploy_status` of `deployed` means the script is
+* installed, not that the function is receiving mail. The
+* internal runtime URL is not returned by the API and is not a
+* customer-facing integration surface.
 *
 * **Secrets.** New functions ship with the managed secrets
 * (`PRIMITIVE_WEBHOOK_SECRET`, `PRIMITIVE_API_KEY`,
@@ -1131,7 +1137,7 @@ const createFunction = (options) => (options.client ?? client).post({
 * Delete a function
 *
 * Soft-deletes the function row, removes the script from the edge
-* runtime, and deactivates the auto-wired webhook endpoint so no
+* runtime, and deactivates any route bound to this function so no
 * further inbound mail is delivered. Past deploy history,
 * invocations, and logs are retained.
 *
@@ -1248,6 +1254,80 @@ const getFunctionTestRunTrace = (options) => (options.client ?? client).get({
 	...options
 });
 /**
+* Get the org's function routing topology
+*
+* Returns a single snapshot of how inbound mail is routed across
+* this org's active domains and functions: which active domain has
+* which function bound, the org's fallback function (if any), and
+* every deployed function with no route bound. Use this to answer
+* "which of my functions actually receive mail?" diagnostically.
+*
+*/
+const getOrgRoutingTopology = (options) => (options?.client ?? client).get({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/functions/routing-topology",
+	...options
+});
+/**
+* Get a function's current route binding
+*
+* Returns the endpoint binding for the function, or null when no
+* route is currently bound. The binding identifies whether the
+* function receives mail for a specific domain (scoped) or for any
+* active domain that has no scoped binding (fallback).
+*
+*/
+const getFunctionRouting = (options) => (options.client ?? client).get({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/functions/{id}/routing",
+	...options
+});
+/**
+* Unbind any route from a function
+*
+* Deactivates every active endpoint bound to this function. The
+* function stays deployed but stops receiving inbound mail. Safe
+* to call when no route is currently bound (no-op).
+*
+*/
+const unsetFunctionRoute = (options) => (options.client ?? client).delete({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/functions/{id}/route",
+	...options
+});
+/**
+* Bind a route to a function
+*
+* Binds inbound mail to this function. The route target is either
+* a specific verified domain (scoped) or the org's fallback (any
+* active domain with no scoped binding). If another function is
+* already bound at the target, returns a `conflict` envelope
+* describing the holder; re-issue with `takeover: true` to
+* deactivate that prior binding and install this one.
+*
+*/
+const setFunctionRoute = (options) => (options.client ?? client).put({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/functions/{id}/route",
+	...options,
+	headers: {
+		...options.body !== void 0 && { "Content-Type": "application/json" },
+		...options.headers
+	}
+});
+/**
 * List a function's secrets
 *
 * Returns metadata for every secret bound to the function, with
@@ -3029,7 +3109,7 @@ const openapiDocument = {
 			"post": {
 				"operationId": "createFunction",
 				"summary": "Deploy a function",
-				"description": "Creates and deploys a new function. The handler must be a single\nESM module whose default export is an object with an async\n`fetch(request, env)` method (Workers-style). Primitive signs\neach delivery and forwards the `Primitive-Signature` header to\nthe handler. Verify the raw request body with\n`PRIMITIVE_WEBHOOK_SECRET` before parsing JSON; after verification\nthe request body parses to an `email.received` event (see\n`EmailReceivedEvent` and the Webhook payload section for the full\nschema). Code is bundled before being uploaded; ship a single\nself-contained file rather than relying on external imports.\n\n**Code limits.** `code` is capped at 1 MiB UTF-8. `sourceMap`\n(optional) is capped at 5 MiB UTF-8, stored with each deployment\nattempt, and sent to the runtime so stack traces can resolve to\noriginal source files.\n\n**Auto-wiring.** On successful deploy, Primitive automatically\ncreates a webhook endpoint that delivers inbound mail to the\nfunction. There is nothing to configure on the Endpoints API\nfor this to work; the internal runtime URL is not returned by\nthe API and is not a customer-facing integration surface.\n\n**Secrets.** New functions ship with the managed secrets\n(`PRIMITIVE_WEBHOOK_SECRET`, `PRIMITIVE_API_KEY`,\n`PRIMITIVE_API_BASE_URL`) already bound. Add user-set secrets via\n`POST /functions/{id}/secrets`; secret writes only land in the\nrunning handler on the next redeploy.\n",
+				"description": "Creates and deploys a new function. The handler must be a single\nESM module whose default export is an object with an async\n`fetch(request, env)` method (Workers-style). Primitive signs\neach delivery and forwards the `Primitive-Signature` header to\nthe handler. Verify the raw request body with\n`PRIMITIVE_WEBHOOK_SECRET` before parsing JSON; after verification\nthe request body parses to an `email.received` event (see\n`EmailReceivedEvent` and the Webhook payload section for the full\nschema). Code is bundled before being uploaded; ship a single\nself-contained file rather than relying on external imports.\n\n**Code limits.** `code` is capped at 1 MiB UTF-8. `sourceMap`\n(optional) is capped at 5 MiB UTF-8, stored with each deployment\nattempt, and sent to the runtime so stack traces can resolve to\noriginal source files.\n\n**Routing.** On successful deploy, the function code is live\nin the runtime, but inbound mail will not reach it until at\nleast one route is bound. Routes are managed from the Primitive\ndashboard. A `deploy_status` of `deployed` means the script is\ninstalled, not that the function is receiving mail. The\ninternal runtime URL is not returned by the API and is not a\ncustomer-facing integration surface.\n\n**Secrets.** New functions ship with the managed secrets\n(`PRIMITIVE_WEBHOOK_SECRET`, `PRIMITIVE_API_KEY`,\n`PRIMITIVE_API_BASE_URL`) already bound. Add user-set secrets via\n`POST /functions/{id}/secrets`; secret writes only land in the\nrunning handler on the next redeploy.\n",
 				"tags": ["Functions"],
 				"requestBody": {
 					"required": true,
@@ -3108,7 +3188,7 @@ const openapiDocument = {
 			"delete": {
 				"operationId": "deleteFunction",
 				"summary": "Delete a function",
-				"description": "Soft-deletes the function row, removes the script from the edge\nruntime, and deactivates the auto-wired webhook endpoint so no\nfurther inbound mail is delivered. Past deploy history,\ninvocations, and logs are retained.\n\nReturns 502 if the runtime delete fails partway; the function\nrow stays in place and the call is safe to retry until it\nsucceeds.\n",
+				"description": "Soft-deletes the function row, removes the script from the edge\nruntime, and deactivates any route bound to this function so no\nfurther inbound mail is delivered. Past deploy history,\ninvocations, and logs are retained.\n\nReturns 502 if the runtime delete fails partway; the function\nrow stays in place and the call is safe to retry until it\nsucceeds.\n",
 				"tags": ["Functions"],
 				"responses": {
 					"200": { "$ref": "#/components/responses/Deleted" },
@@ -3193,6 +3273,92 @@ const openapiDocument = {
 				}
 			}
 		},
+		"/functions/routing-topology": { "get": {
+			"operationId": "getOrgRoutingTopology",
+			"summary": "Get the org's function routing topology",
+			"description": "Returns a single snapshot of how inbound mail is routed across\nthis org's active domains and functions: which active domain has\nwhich function bound, the org's fallback function (if any), and\nevery deployed function with no route bound. Use this to answer\n\"which of my functions actually receive mail?\" diagnostically.\n",
+			"tags": ["Functions"],
+			"responses": {
+				"200": {
+					"description": "Routing topology",
+					"content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, {
+						"type": "object",
+						"properties": { "data": { "$ref": "#/components/schemas/RoutingTopology" } }
+					}] } } }
+				},
+				"401": { "$ref": "#/components/responses/Unauthorized" },
+				"403": { "$ref": "#/components/responses/Forbidden" }
+			}
+		} },
+		"/functions/{id}/routing": {
+			"parameters": [{ "$ref": "#/components/parameters/ResourceId" }],
+			"get": {
+				"operationId": "getFunctionRouting",
+				"summary": "Get a function's current route binding",
+				"description": "Returns the endpoint binding for the function, or null when no\nroute is currently bound. The binding identifies whether the\nfunction receives mail for a specific domain (scoped) or for any\nactive domain that has no scoped binding (fallback).\n",
+				"tags": ["Functions"],
+				"responses": {
+					"200": {
+						"description": "Function routing",
+						"content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, {
+							"type": "object",
+							"properties": { "data": { "oneOf": [{ "$ref": "#/components/schemas/FunctionRouting" }, { "type": "null" }] } }
+						}] } } }
+					},
+					"401": { "$ref": "#/components/responses/Unauthorized" },
+					"404": { "$ref": "#/components/responses/NotFound" }
+				}
+			}
+		},
+		"/functions/{id}/route": {
+			"parameters": [{ "$ref": "#/components/parameters/ResourceId" }],
+			"put": {
+				"operationId": "setFunctionRoute",
+				"summary": "Bind a route to a function",
+				"description": "Binds inbound mail to this function. The route target is either\na specific verified domain (scoped) or the org's fallback (any\nactive domain with no scoped binding). If another function is\nalready bound at the target, returns a `conflict` envelope\ndescribing the holder; re-issue with `takeover: true` to\ndeactivate that prior binding and install this one.\n",
+				"tags": ["Functions"],
+				"requestBody": {
+					"required": true,
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunctionRouteBody" } } }
+				},
+				"responses": {
+					"200": {
+						"description": "Route bound, or conflict requiring takeover",
+						"content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, {
+							"type": "object",
+							"properties": { "data": { "$ref": "#/components/schemas/FunctionRouteResult" } }
+						}] } } }
+					},
+					"400": { "$ref": "#/components/responses/ValidationError" },
+					"401": { "$ref": "#/components/responses/Unauthorized" },
+					"404": { "$ref": "#/components/responses/NotFound" }
+				}
+			},
+			"delete": {
+				"operationId": "unsetFunctionRoute",
+				"summary": "Unbind any route from a function",
+				"description": "Deactivates every active endpoint bound to this function. The\nfunction stays deployed but stops receiving inbound mail. Safe\nto call when no route is currently bound (no-op).\n",
+				"tags": ["Functions"],
+				"responses": {
+					"200": {
+						"description": "Route unbound",
+						"content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, {
+							"type": "object",
+							"properties": { "data": {
+								"type": "object",
+								"properties": { "unrouted": {
+									"type": "boolean",
+									"enum": [true]
+								} },
+								"required": ["unrouted"]
+							} }
+						}] } } }
+					},
+					"401": { "$ref": "#/components/responses/Unauthorized" },
+					"404": { "$ref": "#/components/responses/NotFound" }
+				}
+			}
+		},
 		"/functions/{id}/secrets": {
 			"parameters": [{ "$ref": "#/components/parameters/ResourceId" }],
 			"get": {
@@ -6718,6 +6884,178 @@ const openapiDocument = {
 					"trace_url"
 				]
 			},
+			"FunctionRouting": {
+				"type": "object",
+				"description": "A single route binding for a function. `domain` is null when the\nbinding is the org's fallback (any active domain without a scoped\nbinding); otherwise it carries the scoped domain. `rules` is\nreserved for future routing predicates.\n",
+				"properties": {
+					"endpoint_id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"enabled": { "type": "boolean" },
+					"domain": {
+						"type": ["object", "null"],
+						"properties": {
+							"id": {
+								"type": "string",
+								"format": "uuid"
+							},
+							"name": { "type": ["string", "null"] }
+						},
+						"required": ["id"]
+					},
+					"rules": {
+						"type": "object",
+						"description": "Future routing predicates. Currently empty."
+					},
+					"delivery_count": { "type": "integer" },
+					"success_count": { "type": "integer" },
+					"failure_count": { "type": "integer" },
+					"consecutive_fails": { "type": "integer" },
+					"last_delivery_at": {
+						"type": ["string", "null"],
+						"format": "date-time"
+					},
+					"last_success_at": {
+						"type": ["string", "null"],
+						"format": "date-time"
+					},
+					"last_failure_at": {
+						"type": ["string", "null"],
+						"format": "date-time"
+					}
+				},
+				"required": [
+					"endpoint_id",
+					"enabled",
+					"domain",
+					"rules"
+				]
+			},
+			"RoutingTopology": {
+				"type": "object",
+				"description": "Org-wide map of function routing: which domain points at which\nfunction, the org's fallback binding (if any), and every\ndeployed function with no route currently bound.\n",
+				"properties": {
+					"domains": {
+						"type": "array",
+						"items": {
+							"type": "object",
+							"properties": {
+								"domain_id": {
+									"type": "string",
+									"format": "uuid"
+								},
+								"domain": { "type": "string" },
+								"routed_function": {
+									"type": ["object", "null"],
+									"properties": {
+										"id": {
+											"type": "string",
+											"format": "uuid"
+										},
+										"name": { "type": "string" }
+									},
+									"required": ["id", "name"]
+								},
+								"endpoint_enabled": { "type": ["boolean", "null"] }
+							},
+							"required": [
+								"domain_id",
+								"domain",
+								"routed_function",
+								"endpoint_enabled"
+							]
+						}
+					},
+					"fallback_function": {
+						"type": ["object", "null"],
+						"properties": {
+							"id": {
+								"type": "string",
+								"format": "uuid"
+							},
+							"name": { "type": "string" }
+						},
+						"required": ["id", "name"]
+					},
+					"fallback_enabled": { "type": ["boolean", "null"] },
+					"unrouted_functions": {
+						"type": "array",
+						"items": {
+							"type": "object",
+							"properties": {
+								"id": {
+									"type": "string",
+									"format": "uuid"
+								},
+								"name": { "type": "string" }
+							},
+							"required": ["id", "name"]
+						}
+					}
+				},
+				"required": [
+					"domains",
+					"fallback_function",
+					"fallback_enabled",
+					"unrouted_functions"
+				]
+			},
+			"FunctionRouteBody": {
+				"type": "object",
+				"description": "Target for a route binding. Either a specific verified domain\n(scoped) or the org-wide fallback. Pass `takeover: true` to\ndeactivate any conflicting binding before installing this one.\n",
+				"properties": {
+					"target": { "oneOf": [{
+						"type": "object",
+						"properties": {
+							"kind": {
+								"type": "string",
+								"enum": ["domain"]
+							},
+							"domainId": {
+								"type": "string",
+								"format": "uuid"
+							}
+						},
+						"required": ["kind", "domainId"]
+					}, {
+						"type": "object",
+						"properties": { "kind": {
+							"type": "string",
+							"enum": ["fallback"]
+						} },
+						"required": ["kind"]
+					}] },
+					"takeover": {
+						"type": "boolean",
+						"description": "When true, deactivate any conflicting binding before installing this one."
+					}
+				},
+				"required": ["target"]
+			},
+			"FunctionRouteResult": {
+				"type": "object",
+				"description": "On success, carries the new `routing`. On conflict, carries\n`conflict` describing the binding holder so the caller can\nre-issue with `takeover: true`.\n",
+				"properties": {
+					"routing": { "oneOf": [{ "$ref": "#/components/schemas/FunctionRouting" }, { "type": "null" }] },
+					"conflict": {
+						"type": "object",
+						"properties": {
+							"kind": {
+								"type": "string",
+								"enum": ["http", "function"]
+							},
+							"functionId": {
+								"type": ["string", "null"],
+								"format": "uuid"
+							},
+							"functionName": { "type": ["string", "null"] },
+							"url": { "type": ["string", "null"] }
+						},
+						"required": ["kind"]
+					}
+				}
+			},
 			"FunctionTestRunState": {
 				"type": "string",
 				"description": "High-level state for a function test run trace:\n  - `send_failed`: the initial test email send failed.\n  - `waiting_for_send`: the test run was created but no send result has been recorded yet.\n  - `waiting_for_inbound`: the test send was queued and the matching inbound email has not arrived yet.\n  - `waiting_for_function`: the inbound email arrived and webhook/function processing is still in flight.\n  - `completed`: the function webhook completed successfully.\n  - `failed`: webhook delivery exhausted retries.\n",
@@ -10433,7 +10771,7 @@ const operationManifest = [
 		"binaryResponse": false,
 		"bodyRequired": true,
 		"command": "create-function",
-		"description": "Creates and deploys a new function. The handler must be a single\nESM module whose default export is an object with an async\n`fetch(request, env)` method (Workers-style). Primitive signs\neach delivery and forwards the `Primitive-Signature` header to\nthe handler. Verify the raw request body with\n`PRIMITIVE_WEBHOOK_SECRET` before parsing JSON; after verification\nthe request body parses to an `email.received` event (see\n`EmailReceivedEvent` and the Webhook payload section for the full\nschema). Code is bundled before being uploaded; ship a single\nself-contained file rather than relying on external imports.\n\n**Code limits.** `code` is capped at 1 MiB UTF-8. `sourceMap`\n(optional) is capped at 5 MiB UTF-8, stored with each deployment\nattempt, and sent to the runtime so stack traces can resolve to\noriginal source files.\n\n**Auto-wiring.** On successful deploy, Primitive automatically\ncreates a webhook endpoint that delivers inbound mail to the\nfunction. There is nothing to configure on the Endpoints API\nfor this to work; the internal runtime URL is not returned by\nthe API and is not a customer-facing integration surface.\n\n**Secrets.** New functions ship with the managed secrets\n(`PRIMITIVE_WEBHOOK_SECRET`, `PRIMITIVE_API_KEY`,\n`PRIMITIVE_API_BASE_URL`) already bound. Add user-set secrets via\n`POST /functions/{id}/secrets`; secret writes only land in the\nrunning handler on the next redeploy.\n",
+		"description": "Creates and deploys a new function. The handler must be a single\nESM module whose default export is an object with an async\n`fetch(request, env)` method (Workers-style). Primitive signs\neach delivery and forwards the `Primitive-Signature` header to\nthe handler. Verify the raw request body with\n`PRIMITIVE_WEBHOOK_SECRET` before parsing JSON; after verification\nthe request body parses to an `email.received` event (see\n`EmailReceivedEvent` and the Webhook payload section for the full\nschema). Code is bundled before being uploaded; ship a single\nself-contained file rather than relying on external imports.\n\n**Code limits.** `code` is capped at 1 MiB UTF-8. `sourceMap`\n(optional) is capped at 5 MiB UTF-8, stored with each deployment\nattempt, and sent to the runtime so stack traces can resolve to\noriginal source files.\n\n**Routing.** On successful deploy, the function code is live\nin the runtime, but inbound mail will not reach it until at\nleast one route is bound. Routes are managed from the Primitive\ndashboard. A `deploy_status` of `deployed` means the script is\ninstalled, not that the function is receiving mail. The\ninternal runtime URL is not returned by the API and is not a\ncustomer-facing integration surface.\n\n**Secrets.** New functions ship with the managed secrets\n(`PRIMITIVE_WEBHOOK_SECRET`, `PRIMITIVE_API_KEY`,\n`PRIMITIVE_API_BASE_URL`) already bound. Add user-set secrets via\n`POST /functions/{id}/secrets`; secret writes only land in the\nrunning handler on the next redeploy.\n",
 		"hasJsonBody": true,
 		"method": "POST",
 		"operationId": "createFunction",
@@ -10569,7 +10907,7 @@ const operationManifest = [
 		"binaryResponse": false,
 		"bodyRequired": false,
 		"command": "delete-function",
-		"description": "Soft-deletes the function row, removes the script from the edge\nruntime, and deactivates the auto-wired webhook endpoint so no\nfurther inbound mail is delivered. Past deploy history,\ninvocations, and logs are retained.\n\nReturns 502 if the runtime delete fails partway; the function\nrow stays in place and the call is safe to retry until it\nsucceeds.\n",
+		"description": "Soft-deletes the function row, removes the script from the edge\nruntime, and deactivates any route bound to this function so no\nfurther inbound mail is delivered. Past deploy history,\ninvocations, and logs are retained.\n\nReturns 502 if the runtime delete fails partway; the function\nrow stays in place and the call is safe to retry until it\nsucceeds.\n",
 		"hasJsonBody": false,
 		"method": "DELETE",
 		"operationId": "deleteFunction",
@@ -10693,62 +11031,133 @@ const operationManifest = [
 	{
 		"binaryResponse": false,
 		"bodyRequired": false,
-		"command": "get-function-test-run-trace",
-		"description": "Returns the current end-to-end trace for a function test run.\nThe trace is intentionally partial while the test is still in\nflight: callers can poll this endpoint and watch it fill in\nfrom send -> inbound -> webhook deliveries -> outbound\nrequests, logs, and replies.\n",
+		"command": "get-function-routing",
+		"description": "Returns the endpoint binding for the function, or null when no\nroute is currently bound. The binding identifies whether the\nfunction receives mail for a specific domain (scoped) or for any\nactive domain that has no scoped binding (fallback).\n",
 		"hasJsonBody": false,
 		"method": "GET",
-		"operationId": "getFunctionTestRunTrace",
-		"path": "/functions/{id}/test-runs/{run_id}/trace",
+		"operationId": "getFunctionRouting",
+		"path": "/functions/{id}/routing",
 		"pathParams": [{
 			"description": "Resource UUID",
 			"enum": null,
 			"name": "id",
 			"required": true,
 			"type": "string"
-		}, {
-			"description": "Function test run id returned by POST /functions/{id}/test.",
-			"enum": null,
-			"name": "run_id",
-			"required": true,
-			"type": "string"
 		}],
 		"queryParams": [],
 		"requestSchema": null,
-		"responseSchema": {
+		"responseSchema": { "oneOf": [{
 			"type": "object",
-			"description": "End-to-end trace for a `POST /functions/{id}/test` run. The\nshape is stable, but many nested sections are null or empty\nuntil the corresponding phase has happened.\n",
+			"description": "A single route binding for a function. `domain` is null when the\nbinding is the org's fallback (any active domain without a scoped\nbinding); otherwise it carries the scoped domain. `rules` is\nreserved for future routing predicates.\n",
 			"properties": {
-				"state": {
+				"endpoint_id": {
 					"type": "string",
-					"description": "High-level state for a function test run trace:\n  - `send_failed`: the initial test email send failed.\n  - `waiting_for_send`: the test run was created but no send result has been recorded yet.\n  - `waiting_for_inbound`: the test send was queued and the matching inbound email has not arrived yet.\n  - `waiting_for_function`: the inbound email arrived and webhook/function processing is still in flight.\n  - `completed`: the function webhook completed successfully.\n  - `failed`: webhook delivery exhausted retries.\n",
-					"enum": [
-						"send_failed",
-						"waiting_for_send",
-						"waiting_for_inbound",
-						"waiting_for_function",
-						"completed",
-						"failed"
-					]
+					"format": "uuid"
 				},
-				"test_run": {
-					"type": "object",
+				"enabled": { "type": "boolean" },
+				"domain": {
+					"type": ["object", "null"],
 					"properties": {
 						"id": {
 							"type": "string",
 							"format": "uuid"
 						},
-						"function_id": {
-							"type": "string",
-							"format": "uuid"
-						},
-						"inbound_domain": { "type": "string" },
-						"to": { "type": "string" },
-						"from": { "type": "string" },
-						"subject": { "type": "string" },
-						"poll_since": {
-							"type": "string",
-							"format": "date-time"
-						},
+						"name": { "type": ["string", "null"] }
+					},
+					"required": ["id"]
+				},
+				"rules": {
+					"type": "object",
+					"description": "Future routing predicates. Currently empty."
+				},
+				"delivery_count": { "type": "integer" },
+				"success_count": { "type": "integer" },
+				"failure_count": { "type": "integer" },
+				"consecutive_fails": { "type": "integer" },
+				"last_delivery_at": {
+					"type": ["string", "null"],
+					"format": "date-time"
+				},
+				"last_success_at": {
+					"type": ["string", "null"],
+					"format": "date-time"
+				},
+				"last_failure_at": {
+					"type": ["string", "null"],
+					"format": "date-time"
+				}
+			},
+			"required": [
+				"endpoint_id",
+				"enabled",
+				"domain",
+				"rules"
+			]
+		}, { "type": "null" }] },
+		"sdkName": "getFunctionRouting",
+		"summary": "Get a function's current route binding",
+		"tag": "Functions",
+		"tagCommand": "functions"
+	},
+	{
+		"binaryResponse": false,
+		"bodyRequired": false,
+		"command": "get-function-test-run-trace",
+		"description": "Returns the current end-to-end trace for a function test run.\nThe trace is intentionally partial while the test is still in\nflight: callers can poll this endpoint and watch it fill in\nfrom send -> inbound -> webhook deliveries -> outbound\nrequests, logs, and replies.\n",
+		"hasJsonBody": false,
+		"method": "GET",
+		"operationId": "getFunctionTestRunTrace",
+		"path": "/functions/{id}/test-runs/{run_id}/trace",
+		"pathParams": [{
+			"description": "Resource UUID",
+			"enum": null,
+			"name": "id",
+			"required": true,
+			"type": "string"
+		}, {
+			"description": "Function test run id returned by POST /functions/{id}/test.",
+			"enum": null,
+			"name": "run_id",
+			"required": true,
+			"type": "string"
+		}],
+		"queryParams": [],
+		"requestSchema": null,
+		"responseSchema": {
+			"type": "object",
+			"description": "End-to-end trace for a `POST /functions/{id}/test` run. The\nshape is stable, but many nested sections are null or empty\nuntil the corresponding phase has happened.\n",
+			"properties": {
+				"state": {
+					"type": "string",
+					"description": "High-level state for a function test run trace:\n  - `send_failed`: the initial test email send failed.\n  - `waiting_for_send`: the test run was created but no send result has been recorded yet.\n  - `waiting_for_inbound`: the test send was queued and the matching inbound email has not arrived yet.\n  - `waiting_for_function`: the inbound email arrived and webhook/function processing is still in flight.\n  - `completed`: the function webhook completed successfully.\n  - `failed`: webhook delivery exhausted retries.\n",
+					"enum": [
+						"send_failed",
+						"waiting_for_send",
+						"waiting_for_inbound",
+						"waiting_for_function",
+						"completed",
+						"failed"
+					]
+				},
+				"test_run": {
+					"type": "object",
+					"properties": {
+						"id": {
+							"type": "string",
+							"format": "uuid"
+						},
+						"function_id": {
+							"type": "string",
+							"format": "uuid"
+						},
+						"inbound_domain": { "type": "string" },
+						"to": { "type": "string" },
+						"from": { "type": "string" },
+						"subject": { "type": "string" },
+						"poll_since": {
+							"type": "string",
+							"format": "date-time"
+						},
 						"created_at": {
 							"type": "string",
 							"format": "date-time"
@@ -11123,6 +11532,92 @@ const operationManifest = [
 		"tag": "Functions",
 		"tagCommand": "functions"
 	},
+	{
+		"binaryResponse": false,
+		"bodyRequired": false,
+		"command": "get-org-routing-topology",
+		"description": "Returns a single snapshot of how inbound mail is routed across\nthis org's active domains and functions: which active domain has\nwhich function bound, the org's fallback function (if any), and\nevery deployed function with no route bound. Use this to answer\n\"which of my functions actually receive mail?\" diagnostically.\n",
+		"hasJsonBody": false,
+		"method": "GET",
+		"operationId": "getOrgRoutingTopology",
+		"path": "/functions/routing-topology",
+		"pathParams": [],
+		"queryParams": [],
+		"requestSchema": null,
+		"responseSchema": {
+			"type": "object",
+			"description": "Org-wide map of function routing: which domain points at which\nfunction, the org's fallback binding (if any), and every\ndeployed function with no route currently bound.\n",
+			"properties": {
+				"domains": {
+					"type": "array",
+					"items": {
+						"type": "object",
+						"properties": {
+							"domain_id": {
+								"type": "string",
+								"format": "uuid"
+							},
+							"domain": { "type": "string" },
+							"routed_function": {
+								"type": ["object", "null"],
+								"properties": {
+									"id": {
+										"type": "string",
+										"format": "uuid"
+									},
+									"name": { "type": "string" }
+								},
+								"required": ["id", "name"]
+							},
+							"endpoint_enabled": { "type": ["boolean", "null"] }
+						},
+						"required": [
+							"domain_id",
+							"domain",
+							"routed_function",
+							"endpoint_enabled"
+						]
+					}
+				},
+				"fallback_function": {
+					"type": ["object", "null"],
+					"properties": {
+						"id": {
+							"type": "string",
+							"format": "uuid"
+						},
+						"name": { "type": "string" }
+					},
+					"required": ["id", "name"]
+				},
+				"fallback_enabled": { "type": ["boolean", "null"] },
+				"unrouted_functions": {
+					"type": "array",
+					"items": {
+						"type": "object",
+						"properties": {
+							"id": {
+								"type": "string",
+								"format": "uuid"
+							},
+							"name": { "type": "string" }
+						},
+						"required": ["id", "name"]
+					}
+				}
+			},
+			"required": [
+				"domains",
+				"fallback_function",
+				"fallback_enabled",
+				"unrouted_functions"
+			]
+		},
+		"sdkName": "getOrgRoutingTopology",
+		"summary": "Get the org's function routing topology",
+		"tag": "Functions",
+		"tagCommand": "functions"
+	},
 	{
 		"binaryResponse": false,
 		"bodyRequired": false,
@@ -11342,6 +11837,130 @@ const operationManifest = [
 		"tag": "Functions",
 		"tagCommand": "functions"
 	},
+	{
+		"binaryResponse": false,
+		"bodyRequired": true,
+		"command": "set-function-route",
+		"description": "Binds inbound mail to this function. The route target is either\na specific verified domain (scoped) or the org's fallback (any\nactive domain with no scoped binding). If another function is\nalready bound at the target, returns a `conflict` envelope\ndescribing the holder; re-issue with `takeover: true` to\ndeactivate that prior binding and install this one.\n",
+		"hasJsonBody": true,
+		"method": "PUT",
+		"operationId": "setFunctionRoute",
+		"path": "/functions/{id}/route",
+		"pathParams": [{
+			"description": "Resource UUID",
+			"enum": null,
+			"name": "id",
+			"required": true,
+			"type": "string"
+		}],
+		"queryParams": [],
+		"requestSchema": {
+			"type": "object",
+			"description": "Target for a route binding. Either a specific verified domain\n(scoped) or the org-wide fallback. Pass `takeover: true` to\ndeactivate any conflicting binding before installing this one.\n",
+			"properties": {
+				"target": { "oneOf": [{
+					"type": "object",
+					"properties": {
+						"kind": {
+							"type": "string",
+							"enum": ["domain"]
+						},
+						"domainId": {
+							"type": "string",
+							"format": "uuid"
+						}
+					},
+					"required": ["kind", "domainId"]
+				}, {
+					"type": "object",
+					"properties": { "kind": {
+						"type": "string",
+						"enum": ["fallback"]
+					} },
+					"required": ["kind"]
+				}] },
+				"takeover": {
+					"type": "boolean",
+					"description": "When true, deactivate any conflicting binding before installing this one."
+				}
+			},
+			"required": ["target"]
+		},
+		"responseSchema": {
+			"type": "object",
+			"description": "On success, carries the new `routing`. On conflict, carries\n`conflict` describing the binding holder so the caller can\nre-issue with `takeover: true`.\n",
+			"properties": {
+				"routing": { "oneOf": [{
+					"type": "object",
+					"description": "A single route binding for a function. `domain` is null when the\nbinding is the org's fallback (any active domain without a scoped\nbinding); otherwise it carries the scoped domain. `rules` is\nreserved for future routing predicates.\n",
+					"properties": {
+						"endpoint_id": {
+							"type": "string",
+							"format": "uuid"
+						},
+						"enabled": { "type": "boolean" },
+						"domain": {
+							"type": ["object", "null"],
+							"properties": {
+								"id": {
+									"type": "string",
+									"format": "uuid"
+								},
+								"name": { "type": ["string", "null"] }
+							},
+							"required": ["id"]
+						},
+						"rules": {
+							"type": "object",
+							"description": "Future routing predicates. Currently empty."
+						},
+						"delivery_count": { "type": "integer" },
+						"success_count": { "type": "integer" },
+						"failure_count": { "type": "integer" },
+						"consecutive_fails": { "type": "integer" },
+						"last_delivery_at": {
+							"type": ["string", "null"],
+							"format": "date-time"
+						},
+						"last_success_at": {
+							"type": ["string", "null"],
+							"format": "date-time"
+						},
+						"last_failure_at": {
+							"type": ["string", "null"],
+							"format": "date-time"
+						}
+					},
+					"required": [
+						"endpoint_id",
+						"enabled",
+						"domain",
+						"rules"
+					]
+				}, { "type": "null" }] },
+				"conflict": {
+					"type": "object",
+					"properties": {
+						"kind": {
+							"type": "string",
+							"enum": ["http", "function"]
+						},
+						"functionId": {
+							"type": ["string", "null"],
+							"format": "uuid"
+						},
+						"functionName": { "type": ["string", "null"] },
+						"url": { "type": ["string", "null"] }
+					},
+					"required": ["kind"]
+				}
+			}
+		},
+		"sdkName": "setFunctionRoute",
+		"summary": "Bind a route to a function",
+		"tag": "Functions",
+		"tagCommand": "functions"
+	},
 	{
 		"binaryResponse": false,
 		"bodyRequired": true,
@@ -11495,6 +12114,37 @@ const operationManifest = [
 		"tag": "Functions",
 		"tagCommand": "functions"
 	},
+	{
+		"binaryResponse": false,
+		"bodyRequired": false,
+		"command": "unset-function-route",
+		"description": "Deactivates every active endpoint bound to this function. The\nfunction stays deployed but stops receiving inbound mail. Safe\nto call when no route is currently bound (no-op).\n",
+		"hasJsonBody": false,
+		"method": "DELETE",
+		"operationId": "unsetFunctionRoute",
+		"path": "/functions/{id}/route",
+		"pathParams": [{
+			"description": "Resource UUID",
+			"enum": null,
+			"name": "id",
+			"required": true,
+			"type": "string"
+		}],
+		"queryParams": [],
+		"requestSchema": null,
+		"responseSchema": {
+			"type": "object",
+			"properties": { "unrouted": {
+				"type": "boolean",
+				"enum": [true]
+			} },
+			"required": ["unrouted"]
+		},
+		"sdkName": "unsetFunctionRoute",
+		"summary": "Unbind any route from a function",
+		"tag": "Functions",
+		"tagCommand": "functions"
+	},
 	{
 		"binaryResponse": false,
 		"bodyRequired": true,
@@ -13415,6 +14065,10 @@ async function createAuthenticatedCliApiClient(params) {
 		apiBaseUrl: requestConfig.apiBaseUrl,
 		configDir: params.configDir
 	});
+	if (auth.apiKey === void 0) {
+		const hint = detectPrimitiveKeyEnvMisname(params.env ?? process.env);
+		if (hint) process.stderr.write(`${hint}\n`);
+	}
 	if (auth.source === "stored" && auth.credentials) {
 		const refreshed = await refreshStoredCliCredentials({
 			apiBaseUrl: auth.apiBaseUrl,
@@ -13810,8 +14464,11 @@ const RESERVED_FLAG_NAMES = new Set([
 	"envelope",
 	"output"
 ]);
-function bodyFieldFlag(field) {
-	const common = { description: field.description || field.name };
+function bodyFieldFlag(field, aliases) {
+	const common = {
+		description: field.description || field.name,
+		...aliases && aliases.length > 0 ? { aliases } : {}
+	};
 	if (field.kind === "boolean") return Flags.boolean({
 		...common,
 		allowNo: true
@@ -13853,12 +14510,13 @@ function buildFlags(operation) {
 		flags["raw-body"] = Flags.string({ description: "Full request body as raw JSON. Escape hatch for nested or complex fields (e.g. arrays); prefer per-field flags (e.g. --to, --from, --body-text) when available." });
 		flags["body-file"] = Flags.string({ description: "Path to a JSON file used as the request body. Same role as --raw-body for callers passing a saved payload." });
 		const bodyFields = extractBodyFields(operation.requestSchema);
+		const aliasesForOperation = OPERATION_FLAG_ALIASES[operation.sdkName];
 		for (const field of bodyFields) {
 			if (field.kind === "complex") continue;
 			const name = flagName(field.name);
 			if (RESERVED_FLAG_NAMES.has(name)) continue;
 			if (flags[name] !== void 0) continue;
-			flags[name] = bodyFieldFlag(field);
+			flags[name] = bodyFieldFlag(field, aliasesForOperation?.[field.name]);
 			bodyFieldFlagToProperty.set(name, field.name);
 		}
 	}
@@ -13907,8 +14565,11 @@ const OPERATION_HINTS = {
 	createFunction: "Tip: prefer `primitive functions deploy --name <name> --file <bundle>` for file-input ergonomics. This raw command exists for callers passing JSON.",
 	updateFunction: "Tip: prefer `primitive functions redeploy --id <id> --file <bundle>` for file-input ergonomics. This raw command exists for callers passing JSON.",
 	createFunctionSecret: "Tip: prefer `primitive functions set-secret --id <id> --key <KEY> --value <value> [--redeploy]` for secret writes that also push the binding live. This raw command exists for callers passing JSON.",
-	setFunctionSecret: "Tip: prefer `primitive functions set-secret --id <id> --key <KEY> --value <value> [--redeploy]` for secret writes that also push the binding live. This raw command exists for callers passing JSON."
+	setFunctionSecret: "Tip: prefer `primitive functions set-secret --id <id> --key <KEY> --value <value> [--redeploy]` for secret writes that also push the binding live. This raw command exists for callers passing JSON.",
+	startAgentSignup: "Tip: also pass --signup-code <code> (request from Primitive; invite-only during the agent beta) and --terms-accepted. Capture the signup_token from the response and feed it to `primitive agent verify-agent-signup --signup-token <token> --verification-code <6-digit-code>` (the verify flag accepts --code as an alias). The high-level `primitive signup <email>` command walks an interactive user through both steps with friendlier prompts.",
+	verifyAgentSignup: "Tip: pass --verification-code <code> (or --code; both work). The response carries OAuth tokens but not your assigned inbox domain; run `primitive domains list` (or `primitive whoami`) after success to see the managed *.primitive.email address that routes to this account."
 };
+const OPERATION_FLAG_ALIASES = { verifyAgentSignup: { verification_code: ["code"] } };
 function createOperationCommand(operation) {
 	const { flags, bodyFieldFlagToProperty } = buildFlags(operation);
 	const baseDescription = operation.description !== null && operation.description !== void 0 ? canonicalizeCliReferences(operation.description) : `${operation.method} ${operation.path}`;
@@ -15374,9 +16035,7 @@ function checkApiKey(opts) {
 		message: "provided but does not start with prim_",
 		hint: "Verify the key is a Primitive API key, not a value from another service."
 	};
-	const primitiveKey = env.PRIMITIVE_KEY;
-	const primitiveApiKey = env.PRIMITIVE_API_KEY;
-	if ((primitiveKey?.length ?? 0) > 0 && (primitiveApiKey?.length ?? 0) === 0) return {
+	if (detectPrimitiveKeyEnvMisname(env)) return {
 		status: "fail",
 		message: "PRIMITIVE_KEY is set but the CLI reads PRIMITIVE_API_KEY",
 		hint: "Rename your env var, or re-run with PRIMITIVE_API_KEY=$PRIMITIVE_KEY."
@@ -16603,6 +17262,18 @@ const SECRET_SOURCE_FLAGS_DESCRIPTION = "Safe sources: --secret-from-env KEY rea
 const SINGLE_SECRET_VALUE_SOURCE_DESCRIPTION = "Instead of --value, use --value-from-env ENV_VAR, --value-file PATH, --value-from-env-file FILE[:KEY], or --stdin to avoid putting the secret value in shell history or process argv. If KEY is omitted from --value-from-env-file, the command's --key is used.";
 //#endregion
 //#region src/oclif/commands/functions-deploy.ts
+async function writeRouteStatusHint(apiClient, functionId) {
+	try {
+		const result = await getFunctionRouting({
+			client: apiClient.client,
+			path: { id: functionId },
+			responseStyle: "fields"
+		});
+		if (result.error) return;
+		if (result.data?.data) process.stderr.write("Route bound. Function will receive inbound mail.\n");
+		else process.stderr.write(`Deployed but no route is bound. Inbound mail will not reach this function until you bind one: primitive functions route-set --id ${functionId} --domain <domain-id>  (or --fallback)\n`);
+	} catch {}
+}
 async function runDeployWithSecrets(api, params) {
 	const createResult = await api.createFunction({
 		code: params.code,
@@ -16902,10 +17573,11 @@ var FunctionsDeployCommand = class FunctionsDeployCommand extends Command {
 					const detail = waitResult.function.deploy_error ? `: ${waitResult.function.deploy_error}` : ".";
 					process.stderr.write(`Function ${payload.id} deploy failed${detail}\n`);
 					process.exitCode = 1;
-				}
+				} else await writeRouteStatusHint(apiClient, payload.id);
 				return;
 			}
 			this.log(JSON.stringify(payload, null, 2));
+			await writeRouteStatusHint(apiClient, payload.id);
 		});
 	}
 	async runSourceMode(flags, sourceDir) {
@@ -16997,10 +17669,11 @@ var FunctionsDeployCommand = class FunctionsDeployCommand extends Command {
 				const detail = waitResult.function.deploy_error ? `: ${waitResult.function.deploy_error}` : ".";
 				process.stderr.write(`Function ${payload.id} deploy failed${detail}\n`);
 				process.exitCode = 1;
-			}
+			} else await writeRouteStatusHint(apiClient, payload.id);
 			return;
 		}
 		this.log(JSON.stringify(payload, null, 2));
+		await writeRouteStatusHint(apiClient, payload.id);
 	}
 };
 //#endregion
@@ -17011,8 +17684,8 @@ const PRIMITIVE_TEAM_AUTHOR = {
 	name: "Primitive Team",
 	url: "https://primitive.dev"
 };
-const SDK_VERSION_RANGE = "^0.35.1";
-const CLI_VERSION_RANGE = "^0.35.1";
+const SDK_VERSION_RANGE = "^0.37.0";
+const CLI_VERSION_RANGE = "^0.37.0";
 const ESBUILD_VERSION_RANGE = "^0.27.0";
 function renderHandler() {
 	return `// env.PRIMITIVE_API_KEY, env.PRIMITIVE_WEBHOOK_SECRET, and
@@ -17087,22 +17760,50 @@ function inboundRecipientDomains(event: EmailReceivedEvent): Set<string> {
 // SMTP recipients instead.
 //
 // The default check skips:
+//   - bounce notifications, which RFC 5321 requires to use an empty
+//     SMTP envelope sender (MAIL FROM:<>). Replying to a null sender
+//     is forbidden and would itself bounce, producing a
+//     bounce-of-bounce chain. The body header on a bounce typically
+//     reads "From: MAILER-DAEMON@..." which a naive From-only check
+//     would treat as a normal sender, so we gate on the envelope here.
 //   - direct self-mail where From equals one of the inbound recipients;
-//   - mailer-daemon/postmaster bounces from the same domain as the inbound;
+//   - mailer-daemon/postmaster bounces from the same domain as the
+//     inbound, as a backup for bounces that arrive with a non-empty
+//     envelope sender;
 //   - any address explicitly listed in EXTRA_SELF_ADDRESSES.
 //
-// Extend this helper if you need stricter detection. Common additions:
-//   - Honor RFC 3834 auto-response headers: skip when
-//     event.email.headers["auto-submitted"] is anything other than "no",
-//     or when a List-Unsubscribe / Precedence: bulk header is present.
+// Anything with no identifiable sender at all (envelope + From both
+// empty) is treated as a loop terminator: better to drop one ambiguous
+// message than to reply blindly and loop on a bounce.
+//
+// Extend this helper if you need stricter detection. Common additions
+// not implemented here today:
+//   - Honor RFC 3834 auto-response headers: skip when an
+//     auto-submitted header is anything other than "no", or when a
+//     list-unsubscribe / precedence: bulk header is present. The
+//     EmailReceivedEvent.email.headers shape does not currently surface
+//     these, so detection requires either a parsed-headers field on
+//     the event or a parse of the raw RFC 822 body.
 //   - Track Message-ID / In-Reply-To chains to break ping-pong loops
 //     between two cooperating handlers on different domains.
+//   - Rate-limit replies per sender per hour as a safety net.
 export function isLoop(event: EmailReceivedEvent): boolean {
+  // RFC 5321: bounce notifications use the null MAIL FROM (envelope
+  // sender = empty string). Some MTAs report this as "<>" verbatim.
+  // Treat either as an unambiguous bounce signal.
+  const envelopeSender = (event.email.smtp.mail_from || "").trim();
+  if (envelopeSender === "" || envelopeSender === "<>") return true;
+
   const fromAddresses = [
     ...extractEmailAddresses(event.email.headers.from),
     ...extractEmailAddresses(event.email.smtp.mail_from),
   ];
-  if (fromAddresses.length === 0) return false;
+  // No identifiable sender across either envelope or header: treat as
+  // a loop terminator. Was return false in the original template; that
+  // returned mail with empty headers straight back into the handler
+  // and let bounces with malformed bodies slip past the bounce guard
+  // above.
+  if (fromAddresses.length === 0) return true;
 
   const inboundAddresses = new Set(inboundRecipientAddresses(event));
   const inboundDomains = inboundRecipientDomains(event);
@@ -17319,6 +18020,23 @@ After the first deploy, copy the returned function id into your shell:
 export PRIMITIVE_FUNCTION_ID=<fn-id>
 \`\`\`
 
+## Bind a route
+
+A deployed Function does not receive inbound mail until a route is
+bound to it. Without this step, the Function is installed in the
+runtime but unreachable, and \`functions test\` will refuse to send
+(returns 422 \`no_endpoint\`).
+
+\`\`\`
+primitive functions route-set --id "$PRIMITIVE_FUNCTION_ID" --domain <domain-id>
+\`\`\`
+
+Use \`--fallback\` instead of \`--domain\` to bind the Function as the
+org-wide fallback for any active domain that has no scoped binding.
+Run \`primitive functions route-get --id "$PRIMITIVE_FUNCTION_ID"\` to
+inspect the current binding, or \`primitive functions routing-topology\`
+for the org-wide view of which domain points at which Function.
+
 ## Prove it works
 
 \`\`\`
@@ -17561,6 +18279,25 @@ function emitLogRows(rows, jsonl) {
 		process.stdout.write(`${line}\n`);
 	}
 }
+async function readFunctionInvocations(client, id) {
+	try {
+		const result = await getFunction({
+			client,
+			path: { id },
+			responseStyle: "fields",
+			signal: AbortSignal.timeout(3e3)
+		});
+		if (result.error) return null;
+		const fn = result.data?.data;
+		if (!fn) return null;
+		return {
+			invocations_total: typeof fn.invocations_total === "number" ? fn.invocations_total : 0,
+			invocations_24h: typeof fn.invocations_24h === "number" ? fn.invocations_24h : 0
+		};
+	} catch {
+		return null;
+	}
+}
 var FunctionsLogsCommand = class FunctionsLogsCommand extends Command {
 	static description = "List or follow function execution logs. Defaults to compact text output; use --jsonl for one JSON object per log row.";
 	static summary = "List or follow a function's execution logs";
@@ -17659,7 +18396,14 @@ var FunctionsLogsCommand = class FunctionsLogsCommand extends Command {
 					cursor = page.next_cursor;
 				}
 				if (rows.length === 0 && !wroteEmptyHint) {
-					process.stderr.write(flags.follow ? hasObservedLogs ? "Waiting for new function logs...\n" : "No function logs yet. Waiting for new rows...\n" : "No function logs yet. Trigger the function, then run this command again.\n");
+					let emptyHint;
+					if (flags.follow) emptyHint = hasObservedLogs ? "Waiting for new function logs...\n" : "No function logs yet. Waiting for new rows...\n";
+					else if (flags.cursor) emptyHint = "No more function logs after this cursor.\n";
+					else {
+						const fnInvocations = await readFunctionInvocations(apiClient.client, flags.id);
+						emptyHint = fnInvocations && fnInvocations.invocations_total > 0 ? `No function logs yet, but this function has been invoked ${fnInvocations.invocations_total} time(s) (${fnInvocations.invocations_24h} in the last 24h). Your handler likely has no console.log/console.error calls on the path that fired. Add logging and redeploy to surface details.\n` : "No function logs yet. Trigger the function, then run this command again.\n";
+					}
+					process.stderr.write(emptyHint);
 					wroteEmptyHint = true;
 				}
 				emitLogRows(rows, flags.jsonl);
@@ -17929,6 +18673,239 @@ var FunctionsRedeployCommand = class FunctionsRedeployCommand extends Command {
 	}
 };
 //#endregion
+//#region src/oclif/commands/functions-route-get.ts
+var FunctionsRouteGetCommand = class FunctionsRouteGetCommand extends Command {
+	static description = `Show the current route binding for a function. Returns the binding (domain or fallback, with delivery counters) or null when no route is bound.`;
+	static summary = "Show a function's current route binding";
+	static examples = ["<%= config.bin %> functions route-get --id <fn-id>"];
+	static flags = {
+		"api-key": Flags.string({
+			description: "Primitive API key override (defaults to PRIMITIVE_API_KEY or saved OAuth login credentials)",
+			env: "PRIMITIVE_API_KEY"
+		}),
+		"api-base-url": Flags.string({
+			description: API_BASE_URL_FLAG_DESCRIPTION,
+			env: "PRIMITIVE_API_BASE_URL",
+			hidden: true
+		}),
+		id: Flags.string({
+			description: "Function id (UUID) whose route binding to show.",
+			required: true
+		}),
+		time: Flags.boolean({ description: TIME_FLAG_DESCRIPTION })
+	};
+	async run() {
+		const { flags } = await this.parse(FunctionsRouteGetCommand);
+		const { apiClient, auth, baseUrlOverridden } = await createAuthenticatedCliApiClient({
+			apiKey: flags["api-key"],
+			apiBaseUrl: flags["api-base-url"],
+			configDir: this.config.configDir
+		});
+		await runWithTiming(flags.time, async () => {
+			const result = await getFunctionRouting({
+				client: apiClient.client,
+				path: { id: flags.id },
+				responseStyle: "fields"
+			});
+			if (result.error) {
+				const payload = extractErrorPayload(result.error);
+				writeErrorWithHints(payload);
+				surfaceUnauthorizedHint({
+					auth,
+					baseUrlOverridden,
+					configDir: this.config.configDir,
+					payload
+				});
+				process.exitCode = 1;
+				return;
+			}
+			this.log(JSON.stringify(result.data.data, null, 2));
+		});
+	}
+};
+//#endregion
+//#region src/oclif/commands/functions-route-set.ts
+var FunctionsRouteSetCommand = class FunctionsRouteSetCommand extends Command {
+	static description = `Bind inbound mail to a function by setting its route target.
+
+  Exactly one of --domain or --fallback is required. --domain scopes the
+  binding to a single verified inbound domain. --fallback binds the
+  function to any active domain that has no scoped binding of its own.
+
+  If another function is already bound at the target, the API returns a
+  conflict envelope rather than overwriting; re-run with --takeover to
+  deactivate the prior binding before installing this one.`;
+	static summary = "Bind inbound mail to a function";
+	static examples = [
+		"<%= config.bin %> functions route-set --id <fn-id> --domain <domain-id>",
+		"<%= config.bin %> functions route-set --id <fn-id> --fallback",
+		"<%= config.bin %> functions route-set --id <fn-id> --domain <domain-id> --takeover"
+	];
+	static flags = {
+		"api-key": Flags.string({
+			description: "Primitive API key override (defaults to PRIMITIVE_API_KEY or saved OAuth login credentials)",
+			env: "PRIMITIVE_API_KEY"
+		}),
+		"api-base-url": Flags.string({
+			description: API_BASE_URL_FLAG_DESCRIPTION,
+			env: "PRIMITIVE_API_BASE_URL",
+			hidden: true
+		}),
+		id: Flags.string({
+			description: "Function id (UUID) to bind a route to.",
+			required: true
+		}),
+		domain: Flags.string({
+			description: "Verified inbound domain id (UUID) to scope this function to. Mutually exclusive with --fallback.",
+			exclusive: ["fallback"]
+		}),
+		fallback: Flags.boolean({
+			description: "Bind this function as the org fallback (any active domain without a scoped binding). Mutually exclusive with --domain.",
+			exclusive: ["domain"]
+		}),
+		takeover: Flags.boolean({ description: "Deactivate any conflicting binding before installing this one. Without this flag, the API returns a `conflict` envelope when another function is already bound at the target." }),
+		time: Flags.boolean({ description: TIME_FLAG_DESCRIPTION })
+	};
+	async run() {
+		const { flags } = await this.parse(FunctionsRouteSetCommand);
+		if (!flags.domain && !flags.fallback) {
+			process.stderr.write("Provide exactly one of --domain (scoped binding) or --fallback (org fallback).\n");
+			process.exitCode = 1;
+			return;
+		}
+		const { apiClient, auth, baseUrlOverridden } = await createAuthenticatedCliApiClient({
+			apiKey: flags["api-key"],
+			apiBaseUrl: flags["api-base-url"],
+			configDir: this.config.configDir
+		});
+		await runWithTiming(flags.time, async () => {
+			const target = flags.domain ? {
+				kind: "domain",
+				domainId: flags.domain
+			} : { kind: "fallback" };
+			const result = await setFunctionRoute({
+				client: apiClient.client,
+				path: { id: flags.id },
+				body: {
+					target,
+					...flags.takeover ? { takeover: true } : {}
+				},
+				responseStyle: "fields"
+			});
+			if (result.error) {
+				const payload = extractErrorPayload(result.error);
+				writeErrorWithHints(payload);
+				surfaceUnauthorizedHint({
+					auth,
+					baseUrlOverridden,
+					configDir: this.config.configDir,
+					payload
+				});
+				process.exitCode = 1;
+				return;
+			}
+			this.log(JSON.stringify(result.data.data, null, 2));
+		});
+	}
+};
+//#endregion
+//#region src/oclif/commands/functions-route-unset.ts
+var FunctionsRouteUnsetCommand = class FunctionsRouteUnsetCommand extends Command {
+	static description = `Unbind every active route from a function. The function stays deployed but stops receiving inbound mail. Safe to call when no route is currently bound.`;
+	static summary = "Unbind any route from a function";
+	static examples = ["<%= config.bin %> functions route-unset --id <fn-id>"];
+	static flags = {
+		"api-key": Flags.string({
+			description: "Primitive API key override (defaults to PRIMITIVE_API_KEY or saved OAuth login credentials)",
+			env: "PRIMITIVE_API_KEY"
+		}),
+		"api-base-url": Flags.string({
+			description: API_BASE_URL_FLAG_DESCRIPTION,
+			env: "PRIMITIVE_API_BASE_URL",
+			hidden: true
+		}),
+		id: Flags.string({
+			description: "Function id (UUID) whose routes should be unbound.",
+			required: true
+		}),
+		time: Flags.boolean({ description: TIME_FLAG_DESCRIPTION })
+	};
+	async run() {
+		const { flags } = await this.parse(FunctionsRouteUnsetCommand);
+		const { apiClient, auth, baseUrlOverridden } = await createAuthenticatedCliApiClient({
+			apiKey: flags["api-key"],
+			apiBaseUrl: flags["api-base-url"],
+			configDir: this.config.configDir
+		});
+		await runWithTiming(flags.time, async () => {
+			const result = await unsetFunctionRoute({
+				client: apiClient.client,
+				path: { id: flags.id },
+				responseStyle: "fields"
+			});
+			if (result.error) {
+				const payload = extractErrorPayload(result.error);
+				writeErrorWithHints(payload);
+				surfaceUnauthorizedHint({
+					auth,
+					baseUrlOverridden,
+					configDir: this.config.configDir,
+					payload
+				});
+				process.exitCode = 1;
+				return;
+			}
+			this.log(JSON.stringify(result.data.data, null, 2));
+		});
+	}
+};
+//#endregion
+//#region src/oclif/commands/functions-routing-topology.ts
+var FunctionsRoutingTopologyCommand = class FunctionsRoutingTopologyCommand extends Command {
+	static description = `Show the org-wide function routing topology. Lists every active domain with its bound function (if any), the org fallback function (if any), and every deployed function with no route currently bound.`;
+	static summary = "Show the org-wide function routing topology";
+	static examples = ["<%= config.bin %> functions routing-topology"];
+	static flags = {
+		"api-key": Flags.string({
+			description: "Primitive API key override (defaults to PRIMITIVE_API_KEY or saved OAuth login credentials)",
+			env: "PRIMITIVE_API_KEY"
+		}),
+		"api-base-url": Flags.string({
+			description: API_BASE_URL_FLAG_DESCRIPTION,
+			env: "PRIMITIVE_API_BASE_URL",
+			hidden: true
+		}),
+		time: Flags.boolean({ description: TIME_FLAG_DESCRIPTION })
+	};
+	async run() {
+		const { flags } = await this.parse(FunctionsRoutingTopologyCommand);
+		const { apiClient, auth, baseUrlOverridden } = await createAuthenticatedCliApiClient({
+			apiKey: flags["api-key"],
+			apiBaseUrl: flags["api-base-url"],
+			configDir: this.config.configDir
+		});
+		await runWithTiming(flags.time, async () => {
+			const result = await getOrgRoutingTopology({
+				client: apiClient.client,
+				responseStyle: "fields"
+			});
+			if (result.error) {
+				const payload = extractErrorPayload(result.error);
+				writeErrorWithHints(payload);
+				surfaceUnauthorizedHint({
+					auth,
+					baseUrlOverridden,
+					configDir: this.config.configDir,
+					payload
+				});
+				process.exitCode = 1;
+				return;
+			}
+			this.log(JSON.stringify(result.data.data, null, 2));
+		});
+	}
+};
+//#endregion
 //#region src/oclif/commands/functions-set-secret.ts
 async function runSetSecret(api, params) {
 	const setResult = await api.setSecret({
@@ -18106,6 +19083,7 @@ var FunctionsSetSecretCommand = class FunctionsSetSecretCommand extends Command
 				return;
 			}
 			this.log(JSON.stringify(outcome.result, null, 2));
+			if (outcome.result.redeploy === void 0) process.stderr.write(`Secret ${flags.key} saved. Not live until redeploy. Re-run with --redeploy, or run \`primitive functions redeploy --id ${flags.id} --file <bundle.js>\`.\n`);
 		});
 	}
 };
@@ -18230,7 +19208,7 @@ async function maybeWriteEndpointNoiseWarning(params) {
 	} catch {}
 }
 var FunctionsTestFunctionCommand = class FunctionsTestFunctionCommand extends Command {
-	static description = "Send a real test email through MX to trigger this function. With --wait, blocks until the function has processed the inbound; with --show-sends, also prints any outbound sends the function emitted in response.";
+	static description = "Send a real test email through MX to trigger this function. The function must have an active route bound (see `functions route-set`); without one the API returns a 422 immediately so no doomed test send is queued. With --wait, blocks until the function has processed the inbound; with --show-sends, also prints any outbound sends the function emitted in response.";
 	static summary = "Trigger a test invocation; with --wait, watch it land";
 	static examples = [
 		"<%= config.bin %> functions test --id <fn-id>",
@@ -18336,13 +19314,35 @@ var FunctionsTestFunctionCommand = class FunctionsTestFunctionCommand extends Co
 					return;
 				}
 				const fetched = result.data.data;
+				if (fetched.inbound_email && Array.isArray(fetched.deliveries) && fetched.deliveries.length === 0 && Date.now() - startedAt > 15e3) {
+					writeFunctionTestProgress(`Inbound email arrived but no route matched. Bind one with: primitive functions route-set --id ${flags.id} --domain <domain-id> (or --fallback), then retry.`);
+					process.exitCode = 1;
+					return;
+				}
 				if (TERMINAL_TEST_TRACE_STATES.has(fetched.state)) {
 					trace = fetched;
 					break;
 				}
 				await sleep$1(pollIntervalMs);
 			}
-			if (!trace) this.error(`Timed out after ${flags.timeout}s waiting for function test run ${invocation.test_run_id} to complete. Browse ${invocation.watch_url} for the live view, or inspect ${invocation.trace_url}.`, { exit: 2 });
+			if (!trace) {
+				const finalTrace = ((await getFunctionTestRunTrace({
+					client: apiClient.client,
+					path: {
+						id: flags.id,
+						run_id: invocation.test_run_id
+					},
+					responseStyle: "fields"
+				}).catch(() => null))?.data)?.data;
+				const inboundLanded = Boolean(finalTrace?.inbound_email);
+				const deliveryCount = finalTrace?.deliveries?.length ?? 0;
+				const logCount = finalTrace?.logs?.length ?? 0;
+				const replyCount = finalTrace?.replies?.length ?? 0;
+				const webhookStatus = finalTrace?.inbound_email?.webhook_status ?? "n/a";
+				writeFunctionTestProgress(`Timed out after ${flags.timeout}s. Trace summary: inbound_landed=${inboundLanded} deliveries=${deliveryCount} logs=${logCount} replies=${replyCount} webhook_status=${webhookStatus}. Browse ${invocation.watch_url} for the live view, or inspect ${invocation.trace_url}.`);
+				process.exitCode = 2;
+				return;
+			}
 			const outcome = buildFunctionTestOutcome({
 				elapsedSeconds: Math.round((Date.now() - startedAt) / 1e3),
 				functionId: flags.id,
@@ -20565,12 +21565,14 @@ var OtpResendCommand = class extends SigninOtpResendCommand {
 };
 //#endregion
 //#region src/oclif/commands/whoami.ts
-function formatWhoamiSummary(account) {
-	return [
+function formatWhoamiSummary(account, managedInboxDomain) {
+	const lines = [
 		`Authenticated as ${account.email}`,
 		`Account id: ${account.id}`,
 		`Plan: ${account.plan}`
-	].join("\n");
+	];
+	if (managedInboxDomain) lines.push(`Managed inbox: any-local-part@${managedInboxDomain}`);
+	return lines.join("\n");
 }
 var WhoamiCommand = class WhoamiCommand extends Command {
 	static description = `Print the account currently authenticated by saved OAuth credentials or an explicit API key. Useful as a credentials smoke test: confirms auth is live and shows which account it belongs to.
@@ -20624,11 +21626,22 @@ var WhoamiCommand = class WhoamiCommand extends Command {
 				process.stderr.write("Server returned an empty account body; this should not happen for a valid key.\n");
 				throw new Errors.CLIError("unexpected empty response");
 			}
+			let managedInboxDomain = null;
+			try {
+				const domainsResult = await listDomains({
+					client: apiClient.client,
+					responseStyle: "fields"
+				});
+				if (!domainsResult.error) managedInboxDomain = (domainsResult.data?.data ?? []).find((row) => row.verified && row.managed_zone !== null)?.domain ?? null;
+			} catch {}
 			if (flags.json) {
-				this.log(JSON.stringify(account, null, 2));
+				this.log(JSON.stringify({
+					...account,
+					managed_inbox_domain: managedInboxDomain
+				}, null, 2));
 				return;
 			}
-			this.log(formatWhoamiSummary(account));
+			this.log(formatWhoamiSummary(account, managedInboxDomain));
 		});
 	}
 };
@@ -20944,6 +21957,10 @@ const COMMANDS = {
 	"functions:set-secret": FunctionsSetSecretCommand,
 	"functions:test": FunctionsTestFunctionCommand,
 	"functions:test-function": FunctionsTestFunctionCommand,
+	"functions:route-set": FunctionsRouteSetCommand,
+	"functions:route-unset": FunctionsRouteUnsetCommand,
+	"functions:route-get": FunctionsRouteGetCommand,
+	"functions:routing-topology": FunctionsRoutingTopologyCommand,
 	...Object.fromEntries(Object.entries(CANONICAL_OPERATION_ALIASES).map(([alias, target]) => {
 		const command = generatedCommands[target];
 		if (!command) throw new Error(`Missing generated command target for alias ${alias}`);