@mediamonks/canopy-cli 0.7.39 → 0.7.41

package/dist/{ai-EyrXJC5z.mjs → ai-PXXMv7kO.mjs}

@@ -1,5 +1,5 @@
-import { a as apiRequest, l as withContext } from "./api-ArfD6-t5.mjs";
-import { r as reportErrors } from "./ui-CaHgvvkJ.mjs";
+import { a as apiRequest, l as withContext } from "./api-BHzCvDcY.mjs";
+import { r as reportErrors } from "./ui-SBUdC9rX.mjs";
 import { defineCommand } from "citty";
 //#region src/ai.ts
 /**

package/dist/{api-ArfD6-t5.mjs → api-BHzCvDcY.mjs}

@@ -156,6 +156,18 @@ const ERROR_COPY = {
 		why: "the schedule was saved but syncing it to the platform scheduler failed",
 		fix: "Retry the same command — it re-syncs the saved schedule."
 	},
+	fixed_ip_hosts_required: {
+		why: "routing listed hosts through the fixed addresses needs at least one host",
+		fix: "Add a host with `canopy egress fixed-ip add <host>`, or turn it off with `canopy egress fixed-ip off`."
+	},
+	fixed_ip_not_optional: {
+		why: "every request on this site already leaves from the fixed addresses",
+		fix: "There is nothing to set here — `canopy egress fixed-ip` shows the addresses to register."
+	},
+	invalid_fixed_ip_mode: {
+		why: "the fixed outbound address mode must be off, hosts or all",
+		fix: "Use `canopy egress fixed-ip add <host>`, `canopy egress fixed-ip all` or `canopy egress fixed-ip off`."
+	},
 	worker_egress_sync_failed: {
 		why: "the list was saved but redeploying the running worker with it failed",
 		fix: "Retry, or redeploy the project (`canopy deploy`) to apply the new allowlist."

package/dist/{browse-DEhnJAPT.mjs → browse-DRz1DowL.mjs}

@@ -1,5 +1,5 @@
 import { d as tryResolveProject, n as siteConfig } from "./site-DM2J10CB.mjs";
-import { a as apiRequest, t as ApiError } from "./api-ArfD6-t5.mjs";
+import { a as apiRequest, t as ApiError } from "./api-BHzCvDcY.mjs";
 import { defineCommand } from "citty";
 //#region src/browse.ts
 /**

package/dist/{db-DGrCgj-R.mjs → db-5LfBG6N7.mjs}

@@ -1,7 +1,7 @@
 import { c as resolveProject, o as projectFlagArgs } from "./site-DM2J10CB.mjs";
-import { a as apiRequest, l as withContext, r as apiDataRequest } from "./api-ArfD6-t5.mjs";
-import { a as unwrap, i as requireTty, r as reportErrors } from "./ui-CaHgvvkJ.mjs";
-import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-CG_O5Ghw.mjs";
+import { a as apiRequest, l as withContext, r as apiDataRequest } from "./api-BHzCvDcY.mjs";
+import { a as unwrap, i as requireTty, r as reportErrors } from "./ui-SBUdC9rX.mjs";
+import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-DDJ5JJqj.mjs";
 import { defineCommand } from "citty";
 import { readFileSync, writeFileSync } from "node:fs";
 import * as p from "@clack/prompts";

package/dist/{deploy-B7KItUnh.mjs → deploy-6rYq1Iq8.mjs}

@@ -1,7 +1,7 @@
 import { a as projectDirArgs, c as resolveProject, l as stagingUrl, n as siteConfig, o as projectFlagArgs, s as projectUrl, u as tryReadCanopyJson } from "./site-DM2J10CB.mjs";
-import { a as apiRequest, i as apiDownload, l as withContext, r as apiDataRequest } from "./api-ArfD6-t5.mjs";
-import { a as unwrap, r as reportErrors, t as formatDateTime } from "./ui-CaHgvvkJ.mjs";
-import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-CG_O5Ghw.mjs";
+import { a as apiRequest, i as apiDownload, l as withContext, r as apiDataRequest } from "./api-BHzCvDcY.mjs";
+import { a as unwrap, r as reportErrors, t as formatDateTime } from "./ui-SBUdC9rX.mjs";
+import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-DDJ5JJqj.mjs";
 import { builtinModules } from "node:module";
 import { defineCommand } from "citty";
 import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";

package/dist/dev-D38FQ2LD.mjs

@@ -0,0 +1,2 @@
+import { n as devCommand } from "./dev-D_gyIeUq.mjs";
+export { devCommand };

package/dist/{dev-BMWj4NDZ.mjs → dev-D_gyIeUq.mjs}

@@ -1,8 +1,8 @@
 import { a as projectDirArgs, c as resolveProject, i as projectDialect, n as siteConfig, u as tryReadCanopyJson } from "./site-DM2J10CB.mjs";
-import { a as apiRequest, l as withContext, t as ApiError } from "./api-ArfD6-t5.mjs";
-import { r as reportErrors, t as formatDateTime } from "./ui-CaHgvvkJ.mjs";
-import { r as readMigrationFiles } from "./migrations-CG_O5Ghw.mjs";
-import { i as stampWorkerHeaders, n as WORKER_ATTEST_HEADER } from "./src-CxzGOEhP.mjs";
+import { a as apiRequest, l as withContext, t as ApiError } from "./api-BHzCvDcY.mjs";
+import { r as reportErrors, t as formatDateTime } from "./ui-SBUdC9rX.mjs";
+import { r as readMigrationFiles } from "./migrations-DDJ5JJqj.mjs";
+import { i as stampWorkerHeaders, n as WORKER_ATTEST_HEADER } from "./src-RUf3Gfuh.mjs";
 import { n as writeDevServerRecord } from "./dev-server-file-Dk9pk4AR.mjs";
 import { createRequire } from "node:module";
 import { defineCommand } from "citty";
@@ -41,7 +41,7 @@ async function workerPlugin(flags, slug, workerAttest, remoteUser) {
 		console.log(`note: canopy.json points "worker" at ${entry}, which does not exist — skipping.`);
 		return;
 	}
-	const { missingSecretNames, readDevVars, workerDevPlugin } = await import("./dev-worker-CpSB_Okh.mjs");
+	const { missingSecretNames, readDevVars, workerDevPlugin } = await import("./dev-worker-D78leKBJ.mjs");
 	const secrets = readDevVars(flags.dir);
 	const email = siteConfig().email;
 	const user = await remoteUser?.() ?? (email ? {
@@ -251,7 +251,7 @@ async function devRemote(flags, slug) {
 async function devLocal(flags, slug) {
 	let dump;
 	if (flags.pull) {
-		const { fetchProjectDump } = await import("./local-BnfAEwso.mjs");
+		const { fetchProjectDump } = await import("./local-Dshy0NsJ.mjs");
 		console.log(`Pulling a fresh export of ${slug}${flags.staging ? " [staging]" : ""}…`);
 		dump = await fetchProjectDump(slug, flags.staging ? "staging" : "live");
 	}
@@ -267,7 +267,7 @@ async function devLocal(flags, slug) {
 		console.log(`Note: ai/services will be unavailable — could not reach the platform (${reason}).`);
 	}
 	const workerAttest = randomBytes(24).toString("base64url");
-	const { createSandbox } = await import("./local-BnfAEwso.mjs");
+	const { createSandbox } = await import("./local-Dshy0NsJ.mjs");
 	const sandbox = await createSandbox({
 		slug,
 		persistDir: join(flags.dir, ".canopy", "local"),

package/dist/{dev-worker-CpSB_Okh.mjs → dev-worker-D78leKBJ.mjs}

@@ -1,4 +1,4 @@
-import { i as stampWorkerHeaders, n as WORKER_ATTEST_HEADER, r as redactCanopyCredentials, t as CALLER_HEADER } from "./src-CxzGOEhP.mjs";
+import { i as stampWorkerHeaders, n as WORKER_ATTEST_HEADER, r as redactCanopyCredentials, t as CALLER_HEADER } from "./src-RUf3Gfuh.mjs";
 import { readFileSync } from "node:fs";
 import { relative, resolve, sep } from "node:path";
 //#region src/dev-worker.ts
@@ -200,6 +200,31 @@ function userFromHeaders(headers, fallback) {
 	};
 }
 /**
+* The caller in dev: stamped caller headers when a request poses as one
+* (a client-password visitor, say), else the same monk env.USER resolves to —
+* the developer, since no company login fronts a local server.
+*/
+function callerFromHeaders(headers, fallback) {
+	const kind = (headers.get("x-canopy-identity-kind") ?? "").trim();
+	const id = (headers.get("x-canopy-identity-id") ?? "").trim();
+	const agent = headers.get("x-canopy-caller") === "agent";
+	if ((kind === "monk" || kind === "external") && id) return {
+		kind,
+		id,
+		email: (headers.get("x-canopy-identity-email") ?? "").trim(),
+		name: (headers.get("x-canopy-identity-name") ?? "").trim(),
+		agent
+	};
+	const user = userFromHeaders(headers, fallback);
+	return user ? {
+		kind: "monk",
+		id: user.sub,
+		email: user.email,
+		name: user.name,
+		agent
+	} : null;
+}
+/**
 * The env object the worker sees, in the shim's own key order: secrets first,
 * platform keys after, so a stray `.dev.vars` entry can never shadow
 * `CANOPY`/`DB`/`USER` (the dashboard rejects those names outright —
@@ -207,12 +232,14 @@ function userFromHeaders(headers, fallback) {
 */
 function buildWorkerEnv(options, request, parts) {
 	const blobPrefix = `projects/${options.slug}/`;
+	const caller = callerFromHeaders(request.headers, options.user);
 	return {
 		...options.secrets,
 		CANOPY: { fetch: parts.canopyFetch },
 		DB: parts.db,
 		BLOB: parts.blob,
-		USER: userFromHeaders(request.headers, options.user),
+		USER: caller?.kind === "external" ? null : userFromHeaders(request.headers, options.user),
+		CALLER: caller,
 		PROJECT_SLUG: options.slug,
 		BLOB_PREFIX: blobPrefix,
 		CANOPY_CHANNEL: options.channel
@@ -316,6 +343,7 @@ function workerDevPlugin(options) {
 							return;
 						}
 						env.USER = null;
+						env.CALLER = null;
 						await worker.scheduled({
 							name,
 							cron: typeof body.cron === "string" ? body.cron : "",

package/dist/docs/cli-dev.md

@@ -39,7 +39,7 @@ With the lock in place, `--local` runs on an embedded SQLite engine instead —
 
 **Your backend worker.** If `canopy.json` names a `worker` entry (the worker scaffold does), `canopy dev` serves it too: requests to `/api/*` go to your worker, everything else to the SPA — the same split the platform makes once you deploy. There's no build step; save the file and the next request runs the new code.
 
-Your worker gets the same `env` it gets in production: `env.CANOPY.fetch` for the SDK, `env.DB` and `env.BLOB` for raw database and file access, `env.USER` for the signed-in person, `env.PROJECT_SLUG`. They all follow the mode you're in — live project data by default, your sandbox under `--local`. Two differences worth knowing: `env.USER` is you (the account you logged in with), since there's no company login in front of a local server, and a write through `env.DB` reports no row count locally.
+Your worker gets the same `env` it gets in production: `env.CANOPY.fetch` for the SDK, `env.DB` and `env.BLOB` for raw database and file access, `env.CALLER` and `env.USER` for whoever is calling, `env.PROJECT_SLUG`. They all follow the mode you're in — live project data by default, your sandbox under `--local`. Two differences worth knowing: `env.CALLER` and `env.USER` are you (the account you logged in with), since there's no company login in front of a local server, and a write through `env.DB` reports no row count locally.
 
 To tick a schedule by hand, post its name to the same path the platform uses:
 

package/dist/docs/cli-feedback.md

@@ -17,6 +17,7 @@ canopy feedback note <id> "stack trace and table names for the team"
 canopy feedback status <id> investigated --comment "root cause: the grant expires too early"
 canopy feedback list --status accepted
 canopy feedback status <id> resolved --comment "fixed in v42"
+canopy feedback status <id> declined --comment "works as intended: drafts are private"
 canopy feedback mine
 canopy feedback watch --project my-project
 canopy feedback report "canopy deploy exits 1 after upload" --command "canopy deploy"
@@ -107,9 +108,10 @@ queries — goes in `note <id> "<detail>"`, which only project
 members see. An internal note counts as findings for `investigated`.
 
 **Build:** `list --status accepted` is what a person has asked for. Do the
-work, then `resolve` with a note, or `declined` if it turns out to be a bad
-idea. Set `accepted` yourself only when the person you are working with told
-you to.
+work, then `status <id> resolved --comment "<what changed>"`, or
+`status <id> declined --comment "<why>"` if it turns out to be a bad idea.
+Set `accepted` yourself only when the person you are working with told you
+to.
 
 When a `canopy` command itself fails: rule out user error, check
 `canopy feedback mine` for a duplicate, then `report` with the exact command

package/dist/docs/developers-architecture.md

@@ -67,17 +67,29 @@ else is still static serving. A few things to know:
 
 - **Requests arrive authenticated.** The worker sits behind the same gateway
   wall as the frontend.
-- **The caller is already identified.** `c.env.USER` is the signed-in person
-  (`null` during a scheduled run) — no round-trip needed:
+- **The caller is already identified.** `c.env.CALLER` is whoever the
+  platform let in, with no round-trip needed: a signed-in Monk
+  (`kind: "monk"`) or a visitor who used the project's
+  [client password](https://docs.canopy.website/platform/client-access) (`kind: "external"`). It is
+  `null` only when nobody called, such as during a scheduled run:
 
   ```ts
   app.get("/api/hello", (c) => {
-    const user = c.env.USER;
-    if (!user) return c.json({ error: "unauthenticated" }, 401);
-    return c.json({ message: `Hello, ${user.name}!` });
+    const caller = c.env.CALLER;
+    if (!caller) return c.json({ error: "no caller" }, 400); // a scheduled run
+    if (caller.kind === "external") return c.json({ message: "Hello!" });
+    return c.json({ message: `Hello, ${caller.name}!` });
   });
   ```
 
+  `c.env.USER` is the shorter Monk-only form: the signed-in Monk, or `null`
+  for client-password visitors and scheduled runs. Use it when a route is for
+  Monks only, and don't read a `null` `USER` as "nobody is here".
+
+  A backend gets `CALLER` from its next deploy. One deployed before then can
+  ask the platform instead: `await canopy.auth.user()` through the `CANOPY`
+  binding (below) answers for every visitor.
+
 - **Platform access goes through the same SDK**, via the `CANOPY` service
   binding — same budgets, same data isolation as the browser:
 

package/dist/docs/platform-client-access.md

@@ -46,6 +46,14 @@ immediately, unlocked browsers included.
 > wrong for anything sensitive. Anyone who has it can view the app and share it further, so rotate
 > it when a review round ends.
 
+## Clients and your backend
+
+A client who unlocks the project with the password can use its backend
+routes too, as an anonymous visitor. The worker sees them on `env.CALLER`
+with `kind: "external"`, while `env.USER` (Monks only) is `null` for them. So a
+route that should serve clients checks `env.CALLER`, not `env.USER`. See
+[Auth](https://docs.canopy.website/sdk/auth#in-a-backend-worker).
+
 ## Playing well with other access controls
 
 Client access is independent of

package/dist/docs/platform-egress.md

@@ -112,12 +112,11 @@ Switching back is one command (`canopy egress mode allowlist`), and the
 dashboard offers to **seed the allowlist from the observed hosts** so
 tightening up later doesn't break the app.
 
-## Allowlisting Canopy on the other side
+## Fixed outbound addresses
 
 Some external services only accept calls from IP addresses you register with
-them first — a partner API, a corporate database, a payment provider's
-allowlist. Projects hosted on **Google Cloud** (the `gcp-pilot` site,
-`canopy.monks.zone`) make every outbound request from a fixed pair of
+them first: a partner API, a corporate database, a payment provider's
+allowlist. Canopy can send your backend's requests from a fixed pair of
 addresses, so you can hand them over:
 
 | Address          |
@@ -126,16 +125,74 @@ addresses, so you can hand them over:
 | `34.158.168.43`  |
 
 Register **both**. Traffic may leave from either one, and the second gives the
-platform room to grow without asking you to update your allowlist. These
-addresses are shared by every project on that site, so registering them lets
-any Canopy project on Google Cloud reach the service — the other service's own
-authentication (API keys, tokens) still decides who gets in.
+platform room to grow without asking you to update the other side. These
+addresses are shared by every project that uses them, so registering them lets
+any Canopy project reach the service. The other service's own authentication
+(API keys, tokens) still decides who gets in.
 
 The addresses are a platform commitment: they will not change without notice
-and a migration period. Projects hosted on Cloudflare have **no** fixed
-outbound address (requests leave from Cloudflare's shared edge), so if a
-service you depend on insists on IP allowlisting, run that project on the
-Google Cloud site.
+and a migration period.
+
+### Route a partner's host
+
+By default requests leave normally, not from these addresses. Route the hosts
+that need them:
+
+```bash
+canopy egress fixed-ip add api.partner.com
+canopy egress fixed-ip              # show the setting and the addresses
+canopy egress fixed-ip remove api.partner.com
+canopy egress fixed-ip off
+```
+
+or in the dashboard: **Backend → Outbound hosts → Fixed outbound addresses**.
+Entries follow the same rules as the allowlist (a bare host or a `*.`
+subdomain wildcard, up to 32). Each request is routed by its own host, so if
+the partner redirects you to a CDN that isn't listed, that second request
+leaves normally. The setting applies to the running worker right away, to
+both channels, and to scheduled runs as well as HTTP requests.
+
+Only the **project owner** can turn the setting on or route all traffic. Any
+member can change the listed hosts or turn it off.
+
+**Routing a host doesn't allow it.** In allowlist mode the host still has to be
+on the allowlist, or requests to it are denied as usual. The dashboard and
+`canopy egress fixed-ip` flag routed hosts that aren't allowed and offer to
+allow them. The setting works in open mode too.
+
+### All traffic
+
+`canopy egress fixed-ip all` sends **every** outbound request from the fixed
+addresses. It's there for apps that can't list their partners up front, but
+it's rarely the better choice: every request takes the slower route, counts
+toward the daily quota, and leaves from addresses shared with other projects.
+List the hosts that need it instead when you can.
+
+### What to expect
+
+- **A little latency.** A routed request makes an extra hop, usually tens of
+  milliseconds. The first routed request after a quiet spell (about 15
+  minutes) can take a second or two longer while the route wakes up. Give
+  tight partner timeouts some slack.
+- **A daily transfer quota.** What a project sends and receives through the
+  fixed addresses counts toward 1 GB a day, shown on the **Usage** tab. Once
+  it's used up, routed requests are refused until 00:00 UTC; everything else
+  keeps working. Ask the platform team if you need more.
+- **`fetch` only.** Raw socket connections (`connect()`) and outbound
+  WebSockets don't leave from the fixed addresses.
+- **Uploads up to 32 MB.** A larger request body to a routed host is refused.
+
+On some sites every request of every project already leaves from these
+addresses. There the setting shows as always on and there is nothing to set.
+
+### Errors from routed requests
+
+| Status | `error`                          | What it means                                                                                    |
+| ------ | -------------------------------- | ------------------------------------------------------------------------------------------------ |
+| 429    | `egress_fixed_ip_quota_exceeded` | Today's fixed-address quota is used up. Routed requests work again at 00:00 UTC.                 |
+| 502    | `egress_fixed_ip_unavailable`    | The fixed-address route couldn't send the request. Nothing went out from another address; retry. |
+| 413    | `egress_fixed_ip_body_too_large` | The request body is over 32 MB.                                                                  |
+| 403    | `egress_denied`                  | As always: the host isn't allowed, or it resolves to a private address.                          |
 
 ## The outbound traffic log
 

package/dist/docs/porting-nextjs.md

@@ -69,7 +69,7 @@ three buckets:
 | Route handlers (`app/api/*/route.ts`)           | Worker endpoints under `/api/*`                                                                 |
 | Server actions                                  | Explicit worker endpoints, called with `fetch` from the client                                  |
 | Middleware                                      | Usually deleted (auth is platform-provided); anything else moves into the worker                |
-| NextAuth / auth middleware                      | Deleted — use `canopy.auth.user()` (client) or `env.USER` (worker)                              |
+| NextAuth / auth middleware                      | Deleted — use `canopy.auth.user()` (client) or `env.CALLER` (worker)                            |
 | Database (Prisma, Postgres, …)                  | `canopy.db` — per-project database, document API + SQL escape hatch                             |
 | File uploads (S3, …)                            | `canopy.blob` — per-project file storage with signed downloads                                  |
 | AI SDK / OpenAI client                          | `canopy.ai.chat()`, or point the Vercel AI SDK at `canopy.ai.endpoint()`                        |
@@ -117,12 +117,14 @@ Route handlers and server actions become endpoints in one fetch handler.
 
 ```ts
 // worker/index.ts
-import { createCanopy } from "@mediamonks/canopy";
+import { type CanopyCaller, createCanopy } from "@mediamonks/canopy";
 import { Hono } from "hono";
 
 type Env = {
   CANOPY: { fetch: typeof fetch };
-  /** Signed-in monk, verified by the platform; null for cron. */
+  /** Whoever the platform let in, client-password visitors included; null for cron. */
+  CALLER: CanopyCaller | null;
+  /** The signed-in monk only; null for cron and client-password visitors. */
   USER: { sub: string; email: string; name: string } | null;
   /** Project secrets from dashboard Settings appear as plain keys. */
   MY_API_KEY?: string;
@@ -132,8 +134,10 @@ const app = new Hono<{ Bindings: Env }>();
 
 // was: app/api/report/route.ts
 app.post("/api/report", async (c) => {
+  // Reports belong to a Monk's email, so this route is Monks-only. A
+  // client-password visitor is still let in, as env.CALLER with no email.
   const user = c.env.USER;
-  if (!user) return c.json({ error: "unauthenticated" }, 401);
+  if (!user) return c.json({ error: "monks_only" }, 403);
 
   // The SDK works inside the worker through the CANOPY binding —
   // same database and files the frontend sees, caller's identity attached.
@@ -184,8 +188,8 @@ egress allowlist, and even an allowed hop would arrive without your session.
 The platform recognizes this shape and short-circuits it: a fetch to the
 project's **own hostname** (or to `localhost` on any port — the common
 `BASE_URL` fallback) with a path under `/api/` re-enters your worker directly,
-in-process. No network hop, no allowlist entry, and `env.USER` is the same
-caller who made the original request. Two things to know:
+in-process. No network hop, no allowlist entry, and `env.CALLER` and
+`env.USER` are the same caller who made the original request. Two things to know:
 
 - The loopback covers `/api/*` only. A self-fetch to any other path fails
   like any other non-allowlisted host.
@@ -222,7 +226,8 @@ runs, so the ported app removes sign-in pages, session handling, and auth
 middleware entirely:
 
 - **Client:** `canopy.auth.user()` returns the signed-in monk.
-- **Worker:** `env.USER` carries the verified identity (no round-trip).
+- **Worker:** `env.CALLER` carries the verified caller (no round-trip),
+  client-password visitors included; `env.USER` is the Monk-only form.
 - Client-facing access without OneLogin is a per-project
   [password](https://docs.canopy.website/platform/client-access), configured in Settings — not code.
 
@@ -252,7 +257,7 @@ past greenhouse size (see [Use cases](https://docs.canopy.website/overview/use-c
 - [ ] Frontend: `output: 'export'` or Vite SPA; fix dynamic segments and `next/image`
 - [ ] Worker: route handlers + server actions → `/api/*` endpoints in `worker/index.ts`
 - [ ] Data: ORM → `canopy.db`; uploads → `canopy.blob`; AI clients → `canopy.ai`
-- [ ] Delete NextAuth/middleware; read identity from `canopy.auth.user()` / `env.USER`
+- [ ] Delete NextAuth/middleware; read identity from `canopy.auth.user()` / `env.CALLER`
 - [ ] Secrets via `canopy secrets set` (or dashboard Settings); `NEXT_PUBLIC_*` into your CI build
 - [ ] Crons into Settings → Schedules, handled in `scheduled()`
 - [ ] `canopy.json` with `build`, `dist`, `worker` — then `canopy deploy`

package/dist/docs/sdk-auth.md

@@ -43,6 +43,38 @@ if (user.kind === "external") {
 > **Warning:** Branching on `kind` in the browser is presentation, not security — anything your page can fetch, a
 > visitor can fetch. The platform's access rules are what actually protect data.
 
+### In a backend worker
+
+A worker route already knows who is calling, without asking: `env.CALLER`
+holds the same `id`, `email`, `name` and `kind` that `auth.user()` returns,
+plus `agent`, which is `true` when an AI agent is acting for a Monk.
+
+```ts
+import type { CanopyCaller } from "@mediamonks/canopy";
+
+app.get("/api/me", (c) => {
+  const caller: CanopyCaller | null = c.env.CALLER;
+  if (!caller) return c.json({ error: "no caller" }, 400); // a scheduled run
+  return c.json({ kind: caller.kind, name: caller.name });
+});
+```
+
+`env.CALLER` is `null` only when nobody called, such as during a scheduled
+run. `env.USER` is the Monk-only form: the signed-in Monk, or `null` for a
+client-password visitor.
+
+A client-password visitor has no email address and is named `"Client"`. Its
+`id` changes with every password unlock, so don't key data on it that has to
+last.
+
+A backend gets `env.CALLER` from its next deploy. Until it is redeployed,
+`auth.user()` through the `CANOPY` binding gives the same answer:
+
+```ts
+const canopy = createCanopy({ fetch: c.env.CANOPY.fetch.bind(c.env.CANOPY) });
+const user = await canopy.auth.user();
+```
+
 ## auth.logout()
 
 Ends the platform session for the current visitor. Their next request hits the

package/dist/docs/sdk-mcp.md

@@ -66,8 +66,8 @@ export default {
 ```
 
 **Returns** `(request, env?, executionCtx?) => Promise<Response>`. Pass the
-backend's `env` so handlers and route tools see `env.USER`, `env.CANOPY` and
-your secrets.
+backend's `env` so handlers and route tools see `env.USER`, `env.CALLER`,
+`env.CANOPY` and your secrets.
 
 **Options:** `{ app?, name?, version? }`. `app` is required when the list has
 route tools: they run its routes.
@@ -197,8 +197,9 @@ app.get("/api/notes", (c) => {
 ```
 
 **Returns** `McpCaller`: `{ user: McpUser | null, agent: boolean }`.
-`user` comes from `env.USER`. Without `env`, it falls back to the identity the
-platform attached to the request.
+`user` comes from `env.USER`, and `agent` from `env.CALLER` when the backend
+has it. Without `env`, both fall back to what the platform attached to the
+request.
 
 ## When the tool list is wrong
 

package/dist/docs/troubleshooting.md

@@ -75,6 +75,22 @@ or use dashboard Settings → Outbound hosts. Details and entry rules:
 [Outbound requests](https://docs.canopy.website/platform/egress). Calls made through the SDK /
 `env.CANOPY.fetch` don't count as egress and are unaffected.
 
+## `egress_fixed_ip_quota_exceeded` (429)
+
+The project used up today's transfer through the
+[fixed outbound addresses](https://docs.canopy.website/platform/egress#fixed-outbound-addresses). Routed
+requests are refused until 00:00 UTC; requests to other hosts keep working.
+`canopy usage` and the dashboard's Usage tab show how much was sent. If routing
+all traffic used it up, list only the hosts that need a fixed address
+(`canopy egress fixed-ip add <host>`).
+
+## `egress_fixed_ip_unavailable` (502)
+
+A request to a host routed through the fixed outbound addresses couldn't be
+sent that way. It never went out from another address, so the partner didn't
+see it. Retry; if it keeps happening, the detail says why (and the platform
+team hears about it).
+
 ## The worker returns errors and you can't see why
 
 Read its console output instead of adding diagnostic endpoints:

package/dist/{docs-Bplp4sOY.mjs → docs-B9xGnLSR.mjs}

@@ -1,8 +1,8 @@
-import { t as version } from "./package-CJJpjVh_.mjs";
+import { t as version } from "./package-SWgTmctH.mjs";
 import { n as siteConfig } from "./site-DM2J10CB.mjs";
 import { i as latestKnownVersion, r as compareSemver } from "./version-check-CcsA1QjI.mjs";
-import { n as agentHeaders } from "./api-ArfD6-t5.mjs";
-import { r as reportErrors } from "./ui-CaHgvvkJ.mjs";
+import { n as agentHeaders } from "./api-BHzCvDcY.mjs";
+import { r as reportErrors } from "./ui-SBUdC9rX.mjs";
 import { defineCommand } from "citty";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";