@mediamonks/canopy-cli 0.7.38 → 0.7.40

package/README.md

@@ -11,12 +11,15 @@ canopy deploy [--no-build]        # authorize → signed upload → complete
 canopy rollback / deploys / download
 canopy db pull | snapshot | snapshots | restore
 canopy token create | list | revoke
-canopy usage / docs / whoami / logout
+canopy feedback list | show | comment | note | status | report | watch
+canopy usage / docs / whoami [--json] / logout
 ```
 
 Control-plane calls go through `src/api.ts` (`/control/v1` on the active
 site's `api.` host, bearer token — `CANOPY_DEPLOY_TOKEN` in CI wins over the
-login token); database safety runs on the data plane (`apiDataRequest` with
+login token; every request says which AI agent drives the CLI, if any, as
+`x-canopy-agent`: `CANOPY_AGENT=<name>`, `none` to opt out, else `claude-code`
+under `CLAUDECODE=1`); database safety runs on the data plane (`apiDataRequest` with
 `X-Canopy-Project`). `canopy deploy` streams bundle bytes straight to
 `/data/v1/uploads/:grant` under a short-lived signed grant — they never
 transit the control plane (docs/09-plane-split.md D-d). Multi-site profiles:

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

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

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

@@ -213,6 +213,41 @@ function randomHex(bytes) {
 function traceHeaders() {
 	return { traceparent: `00-${TRACE_ID}-${randomHex(8)}-01` };
 }
+/**
+* Which AI agent drives this process, if any (report-agent). The platform
+* records it next to what the caller writes — "Arjan's agent (claude-code)" —
+* without changing who the author is or what they may do. `CANOPY_AGENT`
+* names it (`none` opts out, e.g. a person running the CLI from a shell that
+* inherited the variable); otherwise Claude Code is recognised by the
+* `CLAUDECODE=1` it sets in every shell it spawns.
+*/
+const AGENT_RE = /^[a-z0-9-]{1,40}$/;
+const warnedAgents = /* @__PURE__ */ new Set();
+function agentName(env = process.env) {
+	const named = env["CANOPY_AGENT"];
+	if (named !== void 0 && named !== "") {
+		if (named === "none") return void 0;
+		if (AGENT_RE.test(named)) return named;
+		if (!warnedAgents.has(named)) {
+			warnedAgents.add(named);
+			console.error(`warning: ignoring CANOPY_AGENT=${JSON.stringify(named)} — use 1–40 characters from a-z, 0-9 and -, or \`none\` to send no agent name.`);
+		}
+		return;
+	}
+	return env["CLAUDECODE"] === "1" ? "claude-code" : void 0;
+}
+/** The `x-canopy-agent` header for every platform request (empty when no agent drives us). */
+function agentHeaders(env = process.env) {
+	const agent = agentName(env);
+	return agent ? { "x-canopy-agent": agent } : {};
+}
+/** Headers every control/data-plane request carries besides auth: trace + agent. */
+function commonHeaders() {
+	return {
+		...traceHeaders(),
+		...agentHeaders()
+	};
+}
 var ApiError = class extends Error {
 	status;
 	code;
@@ -297,7 +332,7 @@ async function apiRequest(method, path, body, rawContentType, headers) {
 	const response = await fetch(`${apiUrl}/control/v1${path}`, {
 		method,
 		headers: {
-			...traceHeaders(),
+			...commonHeaders(),
 			authorization: `Bearer ${token}`,
 			...body === void 0 || isForm ? {} : { "content-type": rawContentType ?? "application/json" },
 			...headers
@@ -317,7 +352,7 @@ async function apiUpload(path, bytes, contentType) {
 	const response = await fetch(`${apiUrl}/control/v1${path}`, {
 		method: "POST",
 		headers: {
-			...traceHeaders(),
+			...commonHeaders(),
 			authorization: `Bearer ${token}`,
 			"content-type": contentType
 		},
@@ -330,7 +365,7 @@ async function apiUpload(path, bytes, contentType) {
 async function apiDownload(path) {
 	const { apiUrl, token, isDeployToken } = credentials();
 	const response = await fetch(`${apiUrl}/control/v1${path}`, { headers: {
-		...traceHeaders(),
+		...commonHeaders(),
 		authorization: `Bearer ${token}`
 	} });
 	if (!response.ok) return fail(response, isDeployToken, "GET", path);
@@ -346,7 +381,7 @@ async function apiDataRequest(method, path, projectSlug, body, rawContentType, c
 	const response = await fetch(`${apiUrl}/data/v1${path}`, {
 		method,
 		headers: {
-			...traceHeaders(),
+			...commonHeaders(),
 			authorization: `Bearer ${token}`,
 			"x-canopy-project": projectSlug,
 			...channel === "staging" ? { "x-canopy-channel": "staging" } : {},
@@ -359,4 +394,4 @@ async function apiDataRequest(method, path, projectSlug, body, rawContentType, c
 	return await response.json();
 }
 //#endregion
-export { apiUpload as a, apiRequest as i, apiDataRequest as n, withContext as o, apiDownload as r, ApiError as t };
+export { apiRequest as a, credentials as c, apiDownload as i, withContext as l, agentHeaders as n, apiUpload as o, apiDataRequest as r, commonHeaders as s, ApiError as t };

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

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

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

@@ -1,7 +1,7 @@
 import { c as resolveProject, o as projectFlagArgs } from "./site-DM2J10CB.mjs";
-import { i as apiRequest, n as apiDataRequest, o as withContext } from "./api-BPEYm9ts.mjs";
-import { a as unwrap, i as requireTty, r as reportErrors } from "./ui-CHfKV6lG.mjs";
-import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-CF1iNZ7F.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 { defineCommand } from "citty";
 import { readFileSync, writeFileSync } from "node:fs";
 import * as p from "@clack/prompts";

package/dist/{deploy-CqCyry4o.mjs → deploy-B7KItUnh.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 { i as apiRequest, n as apiDataRequest, o as withContext, r as apiDownload } from "./api-BPEYm9ts.mjs";
-import { a as unwrap, r as reportErrors, t as formatDateTime } from "./ui-CHfKV6lG.mjs";
-import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-CF1iNZ7F.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 { builtinModules } from "node:module";
 import { defineCommand } from "citty";
 import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";

package/dist/{dev-BtnEuAnS.mjs → dev-03LA_Etx.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 { i as apiRequest, o as withContext, t as ApiError } from "./api-BPEYm9ts.mjs";
-import { r as reportErrors, t as formatDateTime } from "./ui-CHfKV6lG.mjs";
-import { r as readMigrationFiles } from "./migrations-CF1iNZ7F.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-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-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-BfqTheMP.mjs");
+		const { fetchProjectDump } = await import("./local-CkS1XhRu.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-BfqTheMP.mjs");
+	const { createSandbox } = await import("./local-CkS1XhRu.mjs");
 	const sandbox = await createSandbox({
 		slug,
 		persistDir: join(flags.dir, ".canopy", "local"),

package/dist/dev-dJ88L73Y.mjs

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

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

@@ -13,10 +13,13 @@ ones.
 canopy feedback list --status investigate
 canopy feedback show <id>
 canopy feedback comment <id> "root cause: the upload grant expires too early"
+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"
 canopy feedback report "the header overlaps the logo" --attach ./shot.png
 canopy feedback attach <id> ./after-fix.png --comment "fixed — see the shot"
@@ -46,6 +49,9 @@ machine-readable output.
   updates). `--internal` (members only) keeps the note off the reporter's
   view — for stack traces, table names, and other working detail that would
   only confuse them.
+- `note <id> <text>` — post an internal note: the same as
+  `comment <id> <text> --internal`, with no way to make it public. Handy
+  when you let an agent post notes but not replies the reporter sees.
 - `attach <id> <file> [--attach <more>] [--caption <text>] [--comment <text>] [--internal]` —
   add screenshots to an existing report. With `--comment`, the comment is
   posted first and the screenshots hang off that trail entry — how you show
@@ -56,6 +62,12 @@ machine-readable output.
   findings: pass `--comment`, or comment first.
 - `mine [--project <slug>] [--json]` — your own reports across all projects,
   with current statuses.
+- `watch [--project <slug>]... [--since <time>] [--after <cursor>] [--json]` —
+  follow new reports, comments and status changes on projects you're a member
+  of, live, until you stop it. Repeat `--project` to follow several. With
+  `--json` each event is one line of JSON carrying an `id`; pass the last one
+  back as `--after` to pick up where you left off. Events say what happened
+  and who did it, not the text — use `show` for that.
 - `report <text> [--kind bug|feedback] [--project <slug>] [--command <cmd>] [--error <output>] [--attach <file>] [--caption <text>]` —
   file a new report. **Without `--project` it goes to the platform inbox**
   (Canopy itself) — the right target when a `canopy` command misbehaves. The
@@ -65,6 +77,21 @@ machine-readable output.
   itself is the write-up of what you found, `accepted` when the person you are
   working with asked for it.
 
+## Agents and people
+
+Every report and comment remembers how it was made: from the dashboard or
+widget, by a person at the CLI, or by an AI agent driving the CLI. Agent
+entries read as "Ana's agent (claude-code)" in the dashboard, in Slack and
+in `show`, so you can tell what you wrote from what your agent wrote.
+
+The CLI notices on its own when Claude Code runs it. For another agent, set
+`CANOPY_AGENT=<name>` (letters, digits and dashes) in its environment. To
+mark a command as yours even inside an agent's shell, set
+`CANOPY_AGENT=none`.
+
+You get a Slack message when your own agent does something on a report you
+follow, even though you never get one for your own actions.
+
 ## For agents
 
 Two loops.
@@ -77,13 +104,14 @@ Stop there — say what it would take to fix and let the person decide.
 Split your findings by audience: the status comment is what the **reporter**
 reads, so keep it plain ("the upload fails for files over 5 MB — looking into
 it"). The tech-loaded version — stack traces, table names, reproduction
-queries — goes in `comment <id> "<detail>" --internal`, which only project
+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-schedules.md

@@ -91,6 +91,27 @@ of truth for _when_ a job runs, so you can change `daily-digest` from 6:00 to
 7:30 — or pause it — without touching code or redeploying. The name is the
 stable contract between the dashboard and your handler.
 
+## How long a run may take
+
+Plan for **at most 5 minutes** per run. A run that takes longer can be cut
+off before it finishes, and is then recorded as failed. If a job grows past
+that, split it: handle a batch per run and remember where you stopped (in
+the database), or run the schedule more often.
+
+What happens around a run:
+
+- **No retries.** A failed run is recorded on the schedule row, members are
+  notified the first time it fails, and the next attempt is simply the next
+  tick.
+- **No overlap protection.** Every tick starts a fresh run, and **Run now**
+  can run alongside a scheduled one. Make the handler safe to run twice: write
+  idempotently, or take a lock row in the database and skip when it's held.
+- **Deploys don't stop a run.** A run in progress finishes on the version it
+  started with, and keeps its data access while it does. New code takes over
+  from the next run. Database migrations in a deploy apply right away, so a
+  run on the old version may meet the new schema. Additive migrations keep
+  that safe.
+
 ## Things to know
 
 - **Cron runs as the project, not as a person.** Data access works (see

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-T1nuu00A.mjs → docs-B0-IEPjd.mjs}

@@ -1,7 +1,8 @@
-import { t as version } from "./package-CdDH35SE.mjs";
+import { t as version } from "./package-C1xCnyOB.mjs";
 import { n as siteConfig } from "./site-DM2J10CB.mjs";
 import { i as latestKnownVersion, r as compareSemver } from "./version-check-CcsA1QjI.mjs";
-import { r as reportErrors } from "./ui-CHfKV6lG.mjs";
+import { n as agentHeaders } from "./api-ArfD6-t5.mjs";
+import { r as reportErrors } from "./ui-CaHgvvkJ.mjs";
 import { defineCommand } from "citty";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -62,7 +63,10 @@ function parseFrontmatter(raw) {
 /** Bearer header from the deploy token (CI) or the CLI login, if either exists. */
 function authHeaders() {
 	const token = process.env["CANOPY_DEPLOY_TOKEN"] || siteConfig().token;
-	return token ? { authorization: `Bearer ${token}` } : {};
+	return token ? {
+		authorization: `Bearer ${token}`,
+		...agentHeaders()
+	} : {};
 }
 async function fetchRes(url) {
 	try {

package/dist/{egress-ButFsQ2N.mjs → egress-CzxRD6Tp.mjs}

@@ -1,6 +1,6 @@
 import { a as projectDirArgs, c as resolveProject } from "./site-DM2J10CB.mjs";
-import { i as apiRequest, o as withContext } from "./api-BPEYm9ts.mjs";
-import { a as unwrap, i as requireTty, r as reportErrors, t as formatDateTime } from "./ui-CHfKV6lG.mjs";
+import { a as apiRequest, l as withContext } from "./api-ArfD6-t5.mjs";
+import { a as unwrap, i as requireTty, r as reportErrors, t as formatDateTime } from "./ui-CaHgvvkJ.mjs";
 import { defineCommand } from "citty";
 import * as p from "@clack/prompts";
 //#region src/egress.ts