@dench.com/cli 0.3.1 → 0.3.3

package/README.md

@@ -81,6 +81,30 @@ Use `dench context` when you need to know who you are, which workspace you are
 using, assigned tasks, pending approvals you requested, connected apps, and the
 best next commands. Add `--json` for structured output.
 
+## Past chat threads
+
+Browse and search the user's past chat threads in this workspace (own +
+shared). Useful for pulling in earlier context when the user refers to
+something they discussed before. The chat agent has the equivalent
+in-process tools (`list_past_chats`, `search_past_chats`,
+`read_past_chat`); this CLI surface is the same data accessed via bash.
+
+```bash
+dench chat list [--query <substr>] [--limit N] [--include-archived] [--json]
+dench chat search "<query>" [--limit N] [--json]
+dench chat read <thread-id> [--limit N] [--json]
+```
+
+Visibility scope: only threads created by the current user, plus threads
+in the same organization marked as `shared`.
+
+`dench chat search` is a keyword full-text search across past message
+text — pick concrete tokens that the prior chat would have used (file
+paths, product names, error strings) rather than paraphrases.
+
+Inside a sandbox, `dench chat` uses `DENCH_API_KEY` + `DENCH_RUN_ID`
+automatically; locally, run `dench login` first.
+
 ## Billing
 
 Fresh workspaces verify a card for abuse prevention before starter credits are
@@ -149,3 +173,36 @@ For staging:
 dench login --staging
 dench login --host https://workspace-staging.dench.com
 ```
+
+## Sandbox / API key auth (no `dench login` required)
+
+Inside a Daytona sandbox the unified Dench API key is baked into envVars
+at create time (see `src/lib/secrets/sandbox-tokens.ts`). When
+`DENCH_API_KEY` and `CONVEX_URL` are both present, the CLI skips the
+`dench login` flow entirely and uses the API key as a bearer for every
+org-scoped command — `dench crm`, `dench files`, `dench fs sync`, etc.
+
+```bash
+export DENCH_API_KEY=dench_pk_live_…
+export CONVEX_URL=https://your-convex-deployment.convex.cloud
+# Optional but enables nicer URLs in CLI output:
+export DENCH_API_URL=https://app.dench.com
+export DENCH_ORG_ID=…
+export DENCH_ORG_SLUG=…
+
+dench crm entries list people
+```
+
+Auth precedence:
+
+1. `--dev` flag → use the dev workspace env (`NEXT_PUBLIC_CONVEX_URL`,
+   `DENCH_WORKSPACE`, `DENCH_DEV_AGENT_KEY`).
+2. A locally-stored `dench login` session for the current host.
+3. `DENCH_API_KEY` + `CONVEX_URL` (sandbox / automation path).
+4. `--dev`-style env vars (without the flag).
+
+Commands that need to impersonate a specific agent (`dench memory`,
+`dench task`, `dench claim`, `dench log`, `dench approval request`,
+etc.) still require an agent session (`dench login`) — the unified API
+key is org-scoped and cannot speak as a single agent. Those commands
+return a clear "agent session required" error in API-key mode.

package/agent.ts

@@ -0,0 +1,391 @@
+/**
+ * `dench agent <subcommand>` — CLI surface for the subagent + peer
+ * messaging system.
+ *
+ * Used inside sandboxes (where DENCH_API_KEY + DENCH_INTERNAL_BASE +
+ * DENCH_INTERNAL_TOKEN are already present in env) to:
+ *   - spawn parallel subagents
+ *   - await their completion
+ *   - send / wait on peer messages
+ *   - pause / resume / continue runs
+ *   - list run trees
+ *
+ * Routes hit:
+ *   POST /api/runs/spawn-child     (internal token)
+ *   POST /api/runs/notify-parent   (internal token)
+ *   POST /api/runs/send-message    (internal token)
+ *   POST /api/runs/continue        (Bearer Dench API key)
+ *   POST /api/runs                 (existing legacy route — kept for
+ *                                   compatibility; new runs prefer /start)
+ *   POST /api/runs/start           (Bearer Dench API key, the new flow)
+ */
+import type { ConvexHttpClient } from "convex/browser";
+import { makeFunctionReference } from "convex/server";
+import {
+  CliArgError,
+  getFlag,
+  hasFlag,
+  shift as shiftRaw,
+} from "./lib/cli-args";
+
+class AgentCliError extends Error {}
+
+type CliCtx = {
+  convex: ConvexHttpClient;
+  args: string[];
+  jsonOutput: boolean;
+};
+
+// Args helpers moved to cli/lib/cli-args.ts; we adapt shift to throw
+// AgentCliError so existing catch blocks don't need updating.
+function shift(args: string[], expected: string): string {
+  try {
+    return shiftRaw(args, expected);
+  } catch (error) {
+    if (error instanceof CliArgError) throw new AgentCliError(error.message);
+    throw error;
+  }
+}
+
+function out(ctx: CliCtx, value: unknown): void {
+  if (ctx.jsonOutput) {
+    console.log(JSON.stringify(value, null, 2));
+    return;
+  }
+  if (value === null || value === undefined) {
+    console.log("(empty)");
+    return;
+  }
+  console.log(JSON.stringify(value, null, 2));
+}
+
+function getInternalBase(): string {
+  const base = (
+    process.env.DENCH_INTERNAL_BASE ??
+    process.env.DENCH_API_URL ??
+    ""
+  ).replace(/\/+$/, "");
+  if (!base) {
+    throw new AgentCliError(
+      "DENCH_INTERNAL_BASE (or DENCH_API_URL) is not configured in this sandbox",
+    );
+  }
+  return base;
+}
+
+function getApiBase(): string {
+  const base = (process.env.DENCH_API_URL ?? "").replace(/\/+$/, "");
+  if (!base) {
+    throw new AgentCliError("DENCH_API_URL is not configured in this sandbox");
+  }
+  return base;
+}
+
+function internalHeaders(): Record<string, string> {
+  const token = process.env.DENCH_INTERNAL_TOKEN?.trim();
+  if (!token) {
+    throw new AgentCliError(
+      "DENCH_INTERNAL_TOKEN is not configured in this sandbox",
+    );
+  }
+  return {
+    "content-type": "application/json",
+    "x-dench-internal-token": token,
+  };
+}
+
+function apiKeyHeaders(): Record<string, string> {
+  const key = process.env.DENCH_API_KEY?.trim();
+  if (!key) {
+    throw new AgentCliError(
+      "DENCH_API_KEY is not configured in this sandbox",
+    );
+  }
+  return {
+    "content-type": "application/json",
+    authorization: `Bearer ${key}`,
+  };
+}
+
+async function postJson(
+  url: string,
+  headers: Record<string, string>,
+  body: unknown,
+): Promise<unknown> {
+  const response = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body ?? {}),
+  });
+  const text = await response.text();
+  let json: unknown;
+  try {
+    json = text ? JSON.parse(text) : null;
+  } catch {
+    json = { raw: text };
+  }
+  if (!response.ok) {
+    throw new AgentCliError(
+      `${url} failed with ${response.status}: ${
+        typeof json === "object" ? JSON.stringify(json) : String(json)
+      }`,
+    );
+  }
+  return json;
+}
+
+export async function runAgentCommand(opts: {
+  convex: ConvexHttpClient;
+  args: string[];
+}): Promise<void> {
+  const args = [...opts.args];
+  const jsonOutput = hasFlag(args, "--json");
+  const ctx: CliCtx = { convex: opts.convex, args, jsonOutput };
+  const subcommand = args.shift();
+  if (!subcommand || subcommand === "help" || subcommand === "--help") {
+    agentHelp();
+    return;
+  }
+  switch (subcommand) {
+    case "spawn":
+      return await runSpawn(ctx);
+    case "await":
+      return await runAwait(ctx);
+    case "message":
+      return await runMessage(ctx);
+    case "wait-message":
+      return await runWaitMessage(ctx);
+    case "pause":
+      return await runPause(ctx);
+    case "resume":
+      return await runResume(ctx);
+    case "continue":
+      return await runContinue(ctx);
+    case "tree":
+      return await runTree(ctx);
+    default:
+      throw new AgentCliError(
+        `Unknown agent subcommand: ${subcommand}. Run 'dench agent help'.`,
+      );
+  }
+}
+
+async function runPause(ctx: CliCtx): Promise<void> {
+  const runId = shift(ctx.args, "run id");
+  const result = await postJson(
+    `${getApiBase()}/api/runs/pause`,
+    apiKeyHeaders(),
+    { runId },
+  );
+  out(ctx, result);
+}
+
+async function runResume(ctx: CliCtx): Promise<void> {
+  const runId = shift(ctx.args, "run id");
+  const prompt = ctx.args.length > 0 ? ctx.args.join(" ").trim() : undefined;
+  const result = await postJson(
+    `${getApiBase()}/api/runs/resume`,
+    apiKeyHeaders(),
+    { runId, prompt },
+  );
+  out(ctx, result);
+}
+
+async function runSpawn(ctx: CliCtx): Promise<void> {
+  const goal = ctx.args.filter((arg) => !arg.startsWith("--")).join(" ").trim();
+  if (!goal) throw new AgentCliError("Goal required: dench agent spawn '...'");
+  const parentRunId =
+    getFlag(ctx.args, "--parent-run-id") ?? process.env.DENCH_RUN_ID;
+  if (!parentRunId) {
+    throw new AgentCliError(
+      "--parent-run-id required (or set DENCH_RUN_ID inside a sandbox)",
+    );
+  }
+  const sandboxStrategy = getFlag(ctx.args, "--sandbox") as
+    | "own"
+    | "share_parent"
+    | undefined;
+  const timeBudgetMs = parseInt(
+    getFlag(ctx.args, "--time-budget-ms") ?? "0",
+    10,
+  );
+
+  // Step 1: createChildRun via Convex (mutation requires admin auth, so we
+  // hop through the spawn-child route which has CONVEX_DEPLOY_KEY).
+  // For the v1 plan, we ship a single internal-route hop: the route owns
+  // the createChildRun + setRunLinkAwaitToken + start() sequence.
+  const result = await postJson(
+    `${getInternalBase()}/api/runs/spawn-child`,
+    internalHeaders(),
+    {
+      // The route currently expects a pre-created childRunId. To support
+      // the CLI flow we'll pass the raw goal and let the route create
+      // the child row + start the workflow. (Route extension lands in
+      // the next commit.)
+      parentRunId,
+      goal,
+      sandboxStrategy,
+      timeBudgetMs: timeBudgetMs > 0 ? timeBudgetMs : undefined,
+    },
+  );
+  out(ctx, result);
+}
+
+async function runAwait(ctx: CliCtx): Promise<void> {
+  const hookToken = getFlag(ctx.args, "--hook");
+  if (hookToken) {
+    out(ctx, { hookToken, status: "registered" });
+    return;
+  }
+  const childIdsCsv = getFlag(ctx.args, "--children");
+  if (!childIdsCsv) {
+    throw new AgentCliError(
+      "dench agent await requires --hook <token> or --children <csv>",
+    );
+  }
+  // Polling fallback: subscribe to runs via Convex realtime would be the
+  // proper implementation; for v1 we poll status fields every 2s.
+  const childIds = childIdsCsv.split(",").map((id) => id.trim()).filter(Boolean);
+  const completed: Record<string, string> = {};
+  const start = Date.now();
+  const timeoutMs = parseInt(
+    getFlag(ctx.args, "--timeout-ms") ?? "3600000",
+    10,
+  );
+  while (Object.keys(completed).length < childIds.length) {
+    if (Date.now() - start > timeoutMs) {
+      throw new AgentCliError("dench agent await timed out");
+    }
+    for (const childId of childIds) {
+      if (completed[childId]) continue;
+      // Reading status requires a query; for v1 use a tight loop on the
+      // public runs.getRun. (Wired in P5 once DenchClient lands.)
+      completed[childId] = "pending";
+    }
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+    break; // v1 polling stub — placeholder
+  }
+  out(ctx, { children: completed });
+}
+
+async function runMessage(ctx: CliCtx): Promise<void> {
+  const toRunId = shift(ctx.args, "target run id");
+  const fromRunId =
+    getFlag(ctx.args, "--from-run-id") ?? process.env.DENCH_RUN_ID;
+  if (!fromRunId) {
+    throw new AgentCliError(
+      "--from-run-id required (or set DENCH_RUN_ID inside a sandbox)",
+    );
+  }
+  const text = ctx.args.join(" ").trim();
+  if (!text) {
+    throw new AgentCliError(
+      "Message body required: dench agent message <toRunId> 'text...'",
+    );
+  }
+  const result = await postJson(
+    `${getInternalBase()}/api/runs/send-message`,
+    internalHeaders(),
+    { fromRunId, toRunId, payload: { text } },
+  );
+  out(ctx, result);
+}
+
+async function runWaitMessage(ctx: CliCtx): Promise<void> {
+  // v1 stub: print a message + exit. The real implementation lives in
+  // the agent loop's `wait_for_message` tool, which calls the workflow
+  // step that registers an await-message hook and durably sleeps.
+  out(ctx, {
+    note:
+      "wait-message is intended to be called by the agent loop, not from a one-shot CLI. Use the agent's wait_for_message tool inside a Long Session.",
+  });
+}
+
+async function runContinue(ctx: CliCtx): Promise<void> {
+  const prevRunId = shift(ctx.args, "previous run id");
+  const prompt = ctx.args.join(" ").trim();
+  if (!prompt) {
+    throw new AgentCliError(
+      "Continuation prompt required: dench agent continue <prevRunId> '...'",
+    );
+  }
+  const result = await postJson(
+    `${getApiBase()}/api/runs/continue`,
+    apiKeyHeaders(),
+    { prevRunId, prompt },
+  );
+  out(ctx, result);
+}
+
+async function runTree(ctx: CliCtx): Promise<void> {
+  const rootRunId =
+    ctx.args[0] ??
+    process.env.DENCH_ROOT_RUN_ID ??
+    process.env.DENCH_RUN_ID;
+  if (!rootRunId) {
+    throw new AgentCliError(
+      "dench agent tree <rootRunId> (or set DENCH_ROOT_RUN_ID inside a sandbox)",
+    );
+  }
+  const getRunTree = makeFunctionReference<"query">(
+    "functions/runs:getRunTree",
+  );
+  const flat = (await ctx.convex.query(getRunTree, {
+    rootRunId: rootRunId as never,
+  })) as Array<{
+    _id: string;
+    parentRunId?: string;
+    goal: string;
+    status: string;
+  }>;
+  if (ctx.jsonOutput) {
+    out(ctx, flat);
+    return;
+  }
+  // Tree-pretty-print, depth-first.
+  const byParent = new Map<string | null, typeof flat>();
+  for (const node of flat) {
+    const key = node.parentRunId ?? null;
+    const list = byParent.get(key) ?? [];
+    list.push(node);
+    byParent.set(key, list);
+  }
+  function print(node: (typeof flat)[number], depth: number): void {
+    const indent = "  ".repeat(depth);
+    const goalLine = node.goal.split("\n")[0].slice(0, 60);
+    process.stdout.write(
+      `${indent}- [${node.status}] ${node._id} ${goalLine}\n`,
+    );
+    for (const child of byParent.get(node._id) ?? []) print(child, depth + 1);
+  }
+  for (const root of byParent.get(null) ?? []) print(root, 0);
+}
+
+function agentHelp(): void {
+  console.log(`Usage: dench agent <subcommand>
+
+Spawn a chat-turn workflow (same as the web UI's chat panel):
+  dench agent new "<prompt>" [--model <m>] [--file-context <path>] [--visibility private|shared] [--title T] [--yolo] [--follow] [--json]
+  dench agent send <thread-id> "<message>" [--model <m>] [--yolo] [--follow] [--json]
+  These are aliases for \`dench chat new\` / \`dench chat send\`.
+
+Subagents (autonomous Long Sessions, NOT chat threads):
+  dench agent spawn '<goal>' [--parent-run-id <id>] [--sandbox own|share_parent] [--time-budget-ms N]
+  dench agent await --hook <token>
+  dench agent await --children id1,id2,id3 [--timeout-ms N]
+
+Peer messaging:
+  dench agent message <toRunId> '<text...>' [--from-run-id <id>]
+  dench agent wait-message            (intended for use inside the agent loop)
+
+Lifecycle:
+  dench agent pause <runId>
+  dench agent resume <runId> ['optional prompt to inject on resume']
+  dench agent continue <prevRunId> '<prompt>'   (creates a new run from a completed one)
+  dench agent tree                    (see <RunTreeView> in dench.com UI)
+
+Global flags:
+  --json    Emit raw JSON instead of pretty-printed text.
+  --follow  After spawning a chat (new/send), stream the response to stdout.
+`);
+}

package/chat.ts

@@ -0,0 +1,216 @@
+/**
+ * `dench chat <subcommand>` — CLI surface for browsing past chat threads
+ * in the user's workspace.
+ *
+ * Mirrors the `dench crm` pattern: a thin command dispatcher on top of
+ * Convex public queries (`functions/chat:listPastChats`,
+ * `searchPastChats`, `readPastChat`) which themselves enforce the
+ * "own + shared in this org" visibility rule.
+ *
+ * Auth: every call forwards a single bearer token via `sessionToken`
+ * (either a `dch_agent_*` agent session minted by `dench login` or a
+ * unified Dench API key like `DENCH_API_KEY` in a sandbox). When the
+ * caller is using an API key, the server needs a `runId` to resolve
+ * the acting user — the dispatcher in `cli/dench.ts` lifts that from
+ * `DENCH_RUN_ID` and forwards it here so `dench chat` works seamlessly
+ * inside a sandbox without extra flags.
+ *
+ * Subcommands:
+ *   chat list   [--query <substr>] [--limit N] [--include-archived]
+ *   chat search <query>            [--limit N] [--include-current]
+ *   chat read   <thread-id>        [--limit N]
+ */
+import type { ConvexHttpClient } from "convex/browser";
+import { makeFunctionReference } from "convex/server";
+import {
+  CliArgError,
+  getFlag,
+  hasFlag,
+  shift as shiftRaw,
+} from "./lib/cli-args";
+
+type ChatCliContext = {
+  convex: ConvexHttpClient;
+  args: string[];
+  jsonOutput: boolean;
+  sessionToken?: string;
+  runId?: string;
+};
+
+class ChatCliError extends Error {}
+
+function shift(args: string[], expected: string): string {
+  try {
+    return shiftRaw(args, expected);
+  } catch (error) {
+    if (error instanceof CliArgError) throw new ChatCliError(error.message);
+    throw error;
+  }
+}
+
+function parseLimit(raw: string | undefined): number | undefined {
+  if (raw === undefined) return undefined;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new ChatCliError(`Invalid --limit value: ${raw}`);
+  }
+  return Math.floor(parsed);
+}
+
+const api = {
+  listPastChats: makeFunctionReference<"query">(
+    "functions/chat:listPastChats",
+  ),
+  searchPastChats: makeFunctionReference<"query">(
+    "functions/chat:searchPastChats",
+  ),
+  readPastChat: makeFunctionReference<"query">(
+    "functions/chat:readPastChat",
+  ),
+};
+
+function commonArgs(ctx: ChatCliContext) {
+  return {
+    ...(ctx.sessionToken ? { sessionToken: ctx.sessionToken } : {}),
+    ...(ctx.runId ? { runId: ctx.runId } : {}),
+  };
+}
+
+async function callQuery(
+  ctx: ChatCliContext,
+  fn: Parameters<ConvexHttpClient["query"]>[0],
+  args: Record<string, unknown> = {},
+): Promise<unknown> {
+  return ctx.convex.query(fn, { ...args, ...commonArgs(ctx) } as never);
+}
+
+function out(ctx: ChatCliContext, value: unknown): void {
+  if (ctx.jsonOutput) {
+    console.log(JSON.stringify(value, null, 2));
+    return;
+  }
+  if (value === null || value === undefined) {
+    console.log("(empty)");
+    return;
+  }
+  console.log(JSON.stringify(value, null, 2));
+}
+
+function chatHelp(): void {
+  console.log(`Usage: dench chat <subcommand>
+
+List past chat threads (own + shared in this workspace):
+  dench chat list [--query <substr>] [--limit N] [--include-archived] [--json]
+
+Full-text search across past chat messages (own + shared):
+  dench chat search "<query>" [--limit N] [--include-current] [--json]
+
+Read messages from a specific past chat thread:
+  dench chat read <thread-id> [--limit N] [--json]
+
+Spawn a new chat-turn workflow (same agent loop as the web UI):
+  dench chat new "<prompt>" [--model <m>] [--file-context <path>] [--visibility private|shared] [--title T] [--yolo] [--follow] [--json]
+  dench chat send <thread-id> "<message>" [--model <m>] [--yolo] [--follow] [--json]
+  Aliased as: dench agent new / dench agent send.
+
+Approval policy:
+  Without --yolo the workflow uses the workspace policy from
+  /<slug>/settings -> Approvals (master YOLO + per-rule toggles).
+  --yolo overrides for this single chat turn — every approval gate is
+  off, equivalent to flipping the org to YOLO mode for this run.
+
+Auth:
+  Inside a sandbox, this just works — DENCH_API_KEY + DENCH_RUN_ID are
+  used automatically. Locally, run \`dench login\` first.
+
+Global flags:
+  --json    Output raw JSON instead of pretty-printed text.
+  --follow  After spawning, stream the chat response to stdout.
+`);
+}
+
+export async function runChatCommand(opts: {
+  convex: ConvexHttpClient;
+  args: string[];
+  sessionToken?: string;
+  runId?: string;
+}): Promise<void> {
+  const args = [...opts.args];
+  const jsonOutput = hasFlag(args, "--json");
+  const ctx: ChatCliContext = {
+    convex: opts.convex,
+    args,
+    jsonOutput,
+    sessionToken: opts.sessionToken,
+    runId: opts.runId,
+  };
+  const subcommand = args.shift();
+  if (!subcommand || subcommand === "help" || subcommand === "--help") {
+    chatHelp();
+    return;
+  }
+  switch (subcommand) {
+    case "list":
+      return await runChatListCommand(ctx);
+    case "search":
+      return await runChatSearchCommand(ctx);
+    case "read":
+      return await runChatReadCommand(ctx);
+    default:
+      throw new ChatCliError(`Unknown chat subcommand: ${subcommand}`);
+  }
+}
+
+async function runChatListCommand(ctx: ChatCliContext): Promise<void> {
+  const titleQuery = getFlag(ctx.args, "--query");
+  const limit = parseLimit(getFlag(ctx.args, "--limit"));
+  const includeArchived = hasFlag(ctx.args, "--include-archived");
+  out(
+    ctx,
+    await callQuery(ctx, api.listPastChats, {
+      titleQuery,
+      limit,
+      includeArchived,
+    }),
+  );
+}
+
+async function runChatSearchCommand(ctx: ChatCliContext): Promise<void> {
+  const includeCurrent = hasFlag(ctx.args, "--include-current");
+  const limit = parseLimit(getFlag(ctx.args, "--limit"));
+  const queryParts: string[] = [];
+  while (ctx.args.length > 0) {
+    const next = ctx.args.shift();
+    if (next === undefined) break;
+    queryParts.push(next);
+  }
+  const query = queryParts.join(" ").trim();
+  if (!query) {
+    throw new ChatCliError(
+      'Usage: dench chat search "<query>" [--limit N] [--include-current]',
+    );
+  }
+  out(
+    ctx,
+    await callQuery(ctx, api.searchPastChats, {
+      query,
+      limit,
+      // The server defaults excludeThreadId to undefined; the agent path
+      // sets it explicitly. CLI users are not "in" a thread, so we pass
+      // undefined unless --include-current is intentionally set (no-op).
+      ...(includeCurrent ? {} : {}),
+    }),
+  );
+}
+
+async function runChatReadCommand(ctx: ChatCliContext): Promise<void> {
+  const threadId = shift(ctx.args, "thread id");
+  const limit = parseLimit(getFlag(ctx.args, "--limit"));
+  out(
+    ctx,
+    await callQuery(ctx, api.readPastChat, {
+      threadId,
+      limit,
+    }),
+  );
+}

package/crm.ts

@@ -2,8 +2,14 @@
  * `dench crm <subcommand>` — CLI surface for the Convex CRM.
  *
  * All operations resolve via the unified Dench API key baked into the
- * sandbox (DENCH_API_KEY) or the locally-stored session token. Talks to
- * the Convex deployment URL stored in the active session.
+ * sandbox (DENCH_API_KEY) or a locally-stored agent session token from
+ * `dench login`. The dispatcher does not care which one — the parent
+ * (`cli/dench.ts → getRuntime`) picks whichever auth is available and
+ * forwards a single bearer through `sessionToken`. The server-side
+ * `requireCrmAccess` (convex/lib/crm/access.ts) accepts either format.
+ *
+ * Talks to the Convex deployment URL provided by the active runtime
+ * (the session's `convexUrl` or the sandbox's `CONVEX_URL` envvar).
  *
  * This is a thin command dispatcher; the heavy lifting lives in
  * convex/functions/crm/* and convex/lib/crm/*.
@@ -37,9 +43,14 @@ type CrmCliContext = {
   args: string[];
   jsonOutput: boolean;
   /**
-   * Agent session token (`dch_agent_*`) minted by `dench login`. Sent
-   * with every Convex call so the server-side `requireCrmAccess` helper
-   * can resolve the caller's organization without a Convex Auth cookie.
+   * Bearer token sent with every Convex call so the server-side
+   * `requireCrmAccess` helper can resolve the caller's organization
+   * without a Convex Auth cookie. Two formats are accepted:
+   *   • `dch_agent_*` agent session minted by `dench login`.
+   *   • Unified Dench API key (`dench_pk_*`, `dench_live_*`,
+   *     `gw_sk_*`, etc.) baked into sandbox envVars as `DENCH_API_KEY`.
+   * The server dispatches on prefix; both resolve to the same
+   * organization context.
    */
   sessionToken?: string;
 };