@dench.com/cli 0.3.1 → 0.3.3

package/dench.ts

@@ -179,6 +179,21 @@ const api = {
         "functions/agentToolsNode:agentToolStatus",
       ),
     },
+    files: {
+      listTree: makeFunctionReference<"query">("functions/files:listTree"),
+      deleteFile: makeFunctionReference<"mutation">(
+        "functions/files:deleteFile",
+      ),
+      generateUploadUrl: makeFunctionReference<"mutation">(
+        "functions/files:generateUploadUrl",
+      ),
+      commitFileUpload: makeFunctionReference<"mutation">(
+        "functions/files:commitFileUpload",
+      ),
+      getFileSignedDownloadUrl: makeFunctionReference<"action">(
+        "functions/files:getFileSignedDownloadUrl",
+      ),
+    },
   },
 };
 const CONFIG_DIR = join(homedir(), ".dench");
@@ -233,6 +248,7 @@ const BOOLEAN_FLAGS = new Set([
   "--all",
   "--compact",
   "--dev",
+  "--follow",
   "--help",
   "--mine",
   "--self",
@@ -240,6 +256,7 @@ const BOOLEAN_FLAGS = new Set([
   "--prod",
   "--no-open",
   "--version",
+  "--yolo",
   "--ask-before-publishing",
   "--ask-before-spending",
   "--ask-before-external-messages",
@@ -391,7 +408,7 @@ Usage:
   dench tool connect <toolkit> [--json]
   dench tool search "create github issue" [--toolkit github] [--limit 20] [--compact] [--json]
   dench tool run <composio_tool_slug> --args '{"key":"value"}' [--account <connected_account_id>] [--approval <approvalId>] [--json]
-  dench autonomous run "Inspect this repo and summarize the relevant feature. Do not edit files, publish, deploy, spend money, send external messages, access secrets, or change production data." [--duration 1h] [--model <model>] [--api-base http://localhost:3000] [--json]
+  dench autonomous run "Inspect this repo and summarize the relevant feature. Do not edit files, publish, deploy, spend money, send external messages, access secrets, or change production data." [--duration 1h] [--model <model>] [--api-base http://localhost:3000] [--yolo] [--json]
 
 CRM (Daytona-native rewrite):
   dench crm objects <list|get|create|update|rename|delete> ...
@@ -413,12 +430,32 @@ CRM (Daytona-native rewrite):
   dench crm batch --file ops.jsonl
   Help: dench crm help
 
+Past chat threads (own + shared in this workspace):
+  dench chat list [--query <substr>] [--limit N] [--include-archived] [--json]
+  dench chat search "<query>" [--limit N] [--include-current] [--json]
+  dench chat read <thread-id> [--limit N] [--json]
+
+Spawn a new chat-turn workflow (same 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]
+  dench agent new ...    (alias for dench chat new)
+  dench agent send ...   (alias for dench chat send)
+
+  Help: dench chat help
+
 File sync (Daytona-native rewrite):
+  dench fs status [--json] [--workspace /workspace] [--no-hash] [--drift-limit N]
   dench fs sync --initial --org-id <orgId> [--workspace /workspace]
   dench fs stream-open <path>
   dench fs stream-append <token> <chunk>
   dench fs stream-close <token>
 
+Workspace files (use these instead of mv/rm in /workspace; rename(2)
+returns ENOSYS on the FUSE-backed volume mount):
+  dench files ls <path> [--json]
+  dench files mv <src> <dst> [--json]
+  dench files rm <path> [--recursive] [--json]
+
 Subagents (Daytona-native rewrite):
   dench agent spawn '<goal>' [--parent-run-id <id>] [--sandbox own|share_parent] [--time-budget-ms N]
   dench agent await --hook <token> | --children id1,id2,id3
@@ -491,7 +528,7 @@ function autonomousHelp() {
   console.log(`Dench Long Session commands
 
 Usage:
-  dench autonomous run "Inspect this repo and summarize the relevant feature. Do not edit files, publish, deploy, spend money, send external messages, access secrets, or change production data." [--duration 1h] [--model <model>] [--api-base http://localhost:3000] [--json]
+  dench autonomous run "Inspect this repo and summarize the relevant feature. Do not edit files, publish, deploy, spend money, send external messages, access secrets, or change production data." [--duration 1h] [--model <model>] [--api-base http://localhost:3000] [--yolo] [--json]
 
 Notes:
   Starts a Long Session through /api/runs.
@@ -501,6 +538,8 @@ Notes:
   If needed, run dench login --host <api-base> once so the CLI can authenticate.
   Omit --model to use the server default.
   Approval flags: --ask-before-publishing --ask-before-spending --ask-before-external-messages --ask-before-production-changes --ask-before-secrets.
+  --yolo: skip every approval gate (overrides --ask-before-* / --approval-rules). Equivalent to the workspace's YOLO mode in /<slug>/settings -> Approvals.
+  Without any approval flags, the run inherits the workspace's Approvals policy from /<slug>/settings.
   Safe goals should explicitly say: ${SAFE_LONG_SESSION_CONSTRAINTS.join(", ")}.
 `);
 }
@@ -1417,6 +1456,9 @@ function durationPreset(rawDuration?: string) {
 }
 
 function parseApprovalRules() {
+  // --yolo wins over everything else: every approval gate is off,
+  // mirroring the org-level YOLO mode (settings -> Approvals).
+  if (hasFlag("--yolo")) return [];
   const explicit = option("--approval-rules")
     ?.split(",")
     .map((rule) => rule.trim())
@@ -1620,11 +1662,27 @@ function hasDevEnv() {
   );
 }
 
+/**
+ * Resolve the Convex URL the API-key runtime should talk to. Sandboxes
+ * bake `CONVEX_URL` (see `src/lib/secrets/sandbox-tokens.ts`); local
+ * dev typically only has `NEXT_PUBLIC_CONVEX_URL` exported. We accept
+ * either so the same code path works in both shells without callers
+ * needing to know which env var is set.
+ */
+function resolveApiKeyConvexUrl(): string | undefined {
+  return (
+    process.env.CONVEX_URL?.trim() ||
+    process.env.NEXT_PUBLIC_CONVEX_URL?.trim() ||
+    undefined
+  );
+}
+
 function loginRequiredError(command = "this command") {
   return new CliError(`${command} requires dench login`, {
     code: "login_required",
     nextActions: [
-      'Run dench onboard --kind <kind> --name "AI Agent - Project".',
+      "Set DENCH_API_KEY (and CONVEX_URL) in your env if running inside a sandbox or CI.",
+      'Or run dench onboard --kind <kind> --name "AI Agent - Project" to mint an agent session.',
       "If already approved, run dench sessions --json, then dench use <session-key-or-workspace-slug>.",
     ],
   });
@@ -1670,6 +1728,33 @@ async function getRuntime() {
         ],
       });
     }
+
+    // Sandbox / automation path: the unified Dench API key + Convex URL
+    // baked into sandbox envVars (see
+    // src/lib/secrets/sandbox-tokens.ts) is enough to drive every
+    // command that goes through `requireCrmAccess` server-side. We only
+    // fall into this branch when no stored session is present, so
+    // explicit `dench login` setups keep their existing behavior.
+    const apiKey = process.env.DENCH_API_KEY?.trim();
+    const convexUrl = resolveApiKeyConvexUrl();
+    if (apiKey && convexUrl) {
+      const orgId = process.env.DENCH_ORG_ID?.trim();
+      const orgSlug = process.env.DENCH_ORG_SLUG?.trim();
+      const apiHost =
+        process.env.DENCH_API_URL?.trim() ||
+        process.env.DENCH_INTERNAL_BASE?.trim() ||
+        host;
+      return {
+        mode: "apiKey" as const,
+        host: apiHost,
+        client: new ConvexHttpClient(convexUrl),
+        sessionToken: apiKey,
+        organization:
+          orgId && orgSlug
+            ? { id: orgId, name: orgSlug, slug: orgSlug }
+            : undefined,
+      };
+    }
   }
 
   if (!hasDevEnv()) {
@@ -1688,14 +1773,73 @@ async function getRuntime() {
 
 type Runtime = Awaited<ReturnType<typeof getRuntime>>;
 
+/**
+ * `session` mode is required for `agentWorkspace.*` calls because they
+ * gate on `validateAgentSession` server-side, which only accepts the
+ * `dch_agent_*` token format. Sandboxes that only have a unified
+ * `DENCH_API_KEY` (apiKey mode) cannot impersonate a specific agent
+ * and will fail at the server with `Invalid agent session` — surface
+ * that here as a clear error instead.
+ */
 function requireSessionRuntime(
   runtime: Runtime,
   command: string,
 ): Extract<Runtime, { mode: "session" }> {
-  if (runtime.mode !== "session") {
-    throw loginRequiredError(command);
+  if (runtime.mode === "session") return runtime;
+  if (runtime.mode === "apiKey") {
+    throw agentSessionRequiredError(command);
+  }
+  throw loginRequiredError(command);
+}
+
+/**
+ * Org-scoped commands (`dench crm`, `dench files`, etc.) accept either
+ * a `dch_agent_*` agent session token OR a unified Dench API key
+ * (`dench_*` / `gw_sk_*` / etc.) baked into sandbox envVars. The
+ * server-side `requireCrmAccess` helper dispatches on the prefix.
+ */
+type AuthenticatedRuntime = Extract<
+  Runtime,
+  { mode: "session" | "apiKey" }
+>;
+
+function requireAuthenticatedRuntime(
+  runtime: Runtime,
+  command: string,
+): AuthenticatedRuntime {
+  if (runtime.mode === "session" || runtime.mode === "apiKey") return runtime;
+  throw loginRequiredError(command);
+}
+
+function agentSessionRequiredError(command: string) {
+  return new CliError(
+    `${command} requires an agent session — DENCH_API_KEY is org-scoped and cannot impersonate a specific agent`,
+    {
+      code: "agent_session_required",
+      nextActions: [
+        'Run dench onboard --kind <kind> --name "AI Agent - Project" to mint an agent session for this command.',
+        "Or run the equivalent action via the workspace UI / dench crm if it is org-level (e.g. CRM data, files).",
+      ],
+    },
+  );
+}
+
+/**
+ * Some legacy `agentWorkspace.*` commands (task create / claim / log /
+ * approval request) have separate session vs dev branches. With apiKey
+ * mode added, the dev branch would silently receive partial args. Use
+ * this to short-circuit those branches with a clear error.
+ *
+ * Asserts away the `apiKey` mode so the caller's downstream type
+ * narrowing (e.g. `runtime.workspaceArgs`) keeps working.
+ */
+function rejectApiKeyForAgentCommand(
+  runtime: Runtime,
+  command: string,
+): asserts runtime is Exclude<Runtime, { mode: "apiKey" }> {
+  if (runtime.mode === "apiKey") {
+    throw agentSessionRequiredError(command);
   }
-  return runtime;
 }
 
 async function printToolStatus(runtime: Runtime, toolkit?: string) {
@@ -1927,23 +2071,36 @@ async function connectedAppsContext(runtime: Runtime) {
 }
 
 async function buildContext(runtime: Runtime) {
-  const mine =
-    runtime.mode === "session"
-      ? ((await runtime.client.query(
-          api.functions.agentWorkspace.whatCanIDoHere,
-          {
-            sessionToken: runtime.sessionToken,
-          },
-        )) as JsonRecord)
-      : summarizeDevMine(
-          runtime.workspaceArgs.workspaceSlug,
-          await devOverview(runtime),
-        );
-
-  const urls =
-    runtime.mode === "session"
-      ? workspaceUrls(runtime.host, workspaceSlugFromContext(mine))
+  let mine: JsonRecord;
+  let urls: JsonRecord;
+  if (runtime.mode === "session") {
+    mine = (await runtime.client.query(
+      api.functions.agentWorkspace.whatCanIDoHere,
+      { sessionToken: runtime.sessionToken },
+    )) as JsonRecord;
+    urls = workspaceUrls(runtime.host, workspaceSlugFromContext(mine));
+  } else if (runtime.mode === "dev") {
+    mine = summarizeDevMine(
+      runtime.workspaceArgs.workspaceSlug,
+      await devOverview(runtime),
+    );
+    urls = {};
+  } else {
+    // apiKey mode: no agent session is available, so we can't call
+    // `whatCanIDoHere` (it gates on `validateAgentSession`). Return a
+    // minimal context derived from sandbox envVars so dench-cli help
+    // surfaces still work without a full login.
+    mine = {
+      authMode: "apiKey",
+      organization: runtime.organization ?? null,
+      runId: process.env.DENCH_RUN_ID?.trim() ?? null,
+      parentRunId: process.env.DENCH_PARENT_RUN_ID?.trim() ?? null,
+      rootRunId: process.env.DENCH_ROOT_RUN_ID?.trim() ?? null,
+    };
+    urls = runtime.host
+      ? workspaceUrls(runtime.host, runtime.organization?.slug)
       : {};
+  }
 
   return {
     ...mine,
@@ -2341,7 +2498,7 @@ function withToolRunGuidance(runtime: Runtime, result: unknown) {
   if (!record || record.requiresApproval !== true) return result;
   const approvalId = stringField(record, "approvalId");
   const statusContext =
-    runtime.mode === "session"
+    runtime.mode === "session" || runtime.mode === "apiKey"
       ? workspaceUrls(runtime.host, runtime.organization?.slug)
       : {};
   const approvalCommand = approvalId
@@ -2501,6 +2658,12 @@ async function listArtifacts(runtime: Runtime, limit?: number) {
       );
     }
   }
+  if (runtime.mode === "apiKey") {
+    // No agent identity → no artifact list. Return empty so callers
+    // (e.g. `dench artifacts`, `dench suggested-work`) degrade gracefully
+    // instead of throwing for sandbox callers.
+    return [] as JsonRecord[];
+  }
   const data = await devOverview(runtime);
   return asRecordArray(data.recentArtifacts);
 }
@@ -2542,6 +2705,354 @@ async function runFsCommand() {
   }
 }
 
+// ── dench files <ls|mv|rm> ────────────────────────────────────────────────
+//
+// Escape hatches the model needs every time something on /workspace
+// can't be done with `mv` / `rm` — Mountpoint-S3 doesn't implement
+// rename(2) and the file daemon needs a hint to prune Convex rows.
+// All three commands take + emit POSIX paths under /workspace.
+
+function normalizeFilesPath(input: string): string {
+  if (!input || input === "/") return "/";
+  let cleaned = input.replace(/\\/g, "/").replace(/\/+/g, "/");
+  if (cleaned.startsWith("/workspace/")) cleaned = cleaned.slice("/workspace".length);
+  else if (cleaned === "/workspace") cleaned = "/";
+  if (!cleaned.startsWith("/")) cleaned = `/${cleaned}`;
+  if (cleaned.length > 1 && cleaned.endsWith("/")) cleaned = cleaned.slice(0, -1);
+  return cleaned;
+}
+
+function filesApiKey(runtime: Runtime): string | undefined {
+  if (runtime.mode === "apiKey") return runtime.sessionToken;
+  return process.env.DENCH_API_KEY?.trim() || undefined;
+}
+
+function requireFilesApiKey(runtime: Runtime, command: string): string {
+  const apiKey = filesApiKey(runtime);
+  if (!apiKey) {
+    throw new CliError(
+      `${command} needs DENCH_API_KEY (or a sandbox-baked api-key session). It bypasses the user-session auth path.`,
+      {
+        code: "files_api_key_required",
+        nextActions: [
+          "Run inside a Dench sandbox where DENCH_API_KEY is baked in.",
+          "Or export DENCH_API_KEY=<key> first (see dench login output).",
+        ],
+      },
+    );
+  }
+  return apiKey;
+}
+
+type FileTreeRow = {
+  path: string;
+  contentHash?: string;
+  isDir: boolean;
+  size?: number;
+  mtime?: number;
+};
+
+async function listConvexTreeAt(
+  runtime: Runtime,
+  apiKey: string,
+  prefix: string,
+): Promise<FileTreeRow[]> {
+  return (await runtime.client.query(api.functions.files.listTree, {
+    prefix,
+    apiKey,
+  } as never)) as FileTreeRow[];
+}
+
+async function listConvexTreeRecursive(
+  runtime: Runtime,
+  apiKey: string,
+  prefix: string,
+): Promise<FileTreeRow[]> {
+  const rows = await listConvexTreeAt(runtime, apiKey, prefix);
+  const out: FileTreeRow[] = [...rows];
+  for (const row of rows) {
+    if (row.isDir) {
+      const children = await listConvexTreeRecursive(runtime, apiKey, row.path);
+      out.push(...children);
+    }
+  }
+  return out;
+}
+
+async function downloadConvexFileBytes(
+  runtime: Runtime,
+  apiKey: string,
+  path: string,
+): Promise<Uint8Array | null> {
+  const url = (await runtime.client.action(
+    api.functions.files.getFileSignedDownloadUrl,
+    { path, apiKey } as never,
+  )) as string | null;
+  if (!url) return null;
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(
+      `signed download failed (${response.status}): ${await response
+        .text()
+        .catch(() => "")}`,
+    );
+  }
+  return new Uint8Array(await response.arrayBuffer());
+}
+
+async function uploadConvexFileBytes(
+  runtime: Runtime,
+  apiKey: string,
+  args: { path: string; bytes: Uint8Array },
+): Promise<{ path: string; storageId: string; contentHash: string }> {
+  const uploadUrl = (await runtime.client.mutation(
+    api.functions.files.generateUploadUrl,
+    { path: args.path, apiKey } as never,
+  )) as string;
+  const response = await fetch(uploadUrl, {
+    method: "POST",
+    headers: { "content-type": "application/octet-stream" },
+    body: new Blob([args.bytes as BlobPart]),
+  });
+  if (!response.ok) {
+    throw new Error(
+      `convex storage upload failed (${response.status}): ${await response
+        .text()
+        .catch(() => "")}`,
+    );
+  }
+  const { storageId } = (await response.json()) as { storageId: string };
+  const hash = sha256HexSync(args.bytes);
+  const inlineEligible = args.bytes.byteLength <= 100_000;
+  const inlineText = inlineEligible
+    ? new TextDecoder("utf-8", { fatal: false }).decode(args.bytes)
+    : undefined;
+  await runtime.client.mutation(api.functions.files.commitFileUpload, {
+    path: args.path,
+    storageId,
+    contentHash: hash,
+    size: args.bytes.byteLength,
+    text: inlineText,
+    lastModifiedBy: "cli",
+    apiKey,
+  } as never);
+  return { path: args.path, storageId, contentHash: hash };
+}
+
+async function runFilesLs() {
+  const runtime = await getRuntime();
+  const apiKey = requireFilesApiKey(runtime, "dench files ls");
+  const target = normalizeFilesPath(positional(2) ?? "/");
+  const recursive = hasFlag("--recursive") || hasFlag("-r");
+  const rows = recursive
+    ? await listConvexTreeRecursive(runtime, apiKey, target)
+    : await listConvexTreeAt(runtime, apiKey, target);
+  if (hasFlag("--json")) {
+    print({
+      ok: true,
+      prefix: target,
+      recursive,
+      count: rows.length,
+      entries: rows.map((row) => ({
+        path: row.path,
+        isDir: row.isDir,
+        size: row.size,
+        mtime: row.mtime,
+        contentHash: row.contentHash,
+      })),
+    });
+    return;
+  }
+  if (rows.length === 0) {
+    process.stdout.write(`(no entries under ${target})\n`);
+    return;
+  }
+  for (const row of rows) {
+    const kind = row.isDir ? "DIR " : "FILE";
+    const size = row.isDir
+      ? "       -"
+      : (row.size ?? 0).toString().padStart(8, " ");
+    process.stdout.write(`${kind} ${size}  ${row.path}\n`);
+  }
+}
+
+async function runFilesMv() {
+  const runtime = await getRuntime();
+  const apiKey = requireFilesApiKey(runtime, "dench files mv");
+  const fromRaw = positional(2);
+  const toRaw = positional(3);
+  if (!fromRaw || !toRaw) {
+    throw new CliError("Usage: dench files mv <src> <dst>", {
+      code: "files_mv_usage",
+      nextActions: ["Pass both source and destination paths."],
+    });
+  }
+  const from = normalizeFilesPath(fromRaw);
+  const to = normalizeFilesPath(toRaw);
+  if (from === to) {
+    throw new CliError("Source and destination are the same path", {
+      code: "files_mv_noop",
+    });
+  }
+
+  const sourceRows = await listConvexTreeRecursive(runtime, apiKey, from);
+  const sourceSelf = (await listConvexTreeAt(runtime, apiKey, parentOfPath(from))).find(
+    (row) => row.path === from,
+  );
+  if (!sourceSelf && sourceRows.length === 0) {
+    throw new CliError(`Source not found in Convex: ${from}`, {
+      code: "files_mv_not_found",
+      nextActions: [
+        "Run `dench files ls` on the parent directory to confirm.",
+        "If the file only exists on the sandbox FS, run the daemon (or `dench fs sync --initial`) first.",
+      ],
+    });
+  }
+
+  const moved: Array<{ from: string; to: string }> = [];
+  if (sourceSelf && !sourceSelf.isDir) {
+    const bytes = await downloadConvexFileBytes(runtime, apiKey, from);
+    if (!bytes) {
+      throw new CliError(`Could not download bytes for ${from}`, {
+        code: "files_mv_download",
+      });
+    }
+    await uploadConvexFileBytes(runtime, apiKey, { path: to, bytes });
+    await runtime.client.mutation(api.functions.files.deleteFile, {
+      path: from,
+      apiKey,
+    } as never);
+    moved.push({ from, to });
+  } else {
+    for (const row of sourceRows) {
+      if (row.isDir) continue;
+      const rel = row.path.slice(from.length).replace(/^\/+/, "");
+      const dest = rel ? `${to}/${rel}` : to;
+      const bytes = await downloadConvexFileBytes(runtime, apiKey, row.path);
+      if (!bytes) continue;
+      await uploadConvexFileBytes(runtime, apiKey, { path: dest, bytes });
+      await runtime.client.mutation(api.functions.files.deleteFile, {
+        path: row.path,
+        apiKey,
+      } as never);
+      moved.push({ from: row.path, to: dest });
+    }
+    if (sourceSelf?.isDir) {
+      await runtime.client.mutation(api.functions.files.deleteFile, {
+        path: from,
+        apiKey,
+      } as never);
+    }
+  }
+
+  print({ ok: true, from, to, moved });
+}
+
+async function runFilesRm() {
+  const runtime = await getRuntime();
+  const apiKey = requireFilesApiKey(runtime, "dench files rm");
+  const targetRaw = positional(2);
+  if (!targetRaw) {
+    throw new CliError("Usage: dench files rm <path> [--recursive]", {
+      code: "files_rm_usage",
+    });
+  }
+  const target = normalizeFilesPath(targetRaw);
+  const recursive = hasFlag("--recursive") || hasFlag("-r");
+
+  const parentRows = await listConvexTreeAt(runtime, apiKey, parentOfPath(target));
+  const self = parentRows.find((row) => row.path === target);
+  if (!self) {
+    if (hasFlag("--json")) {
+      print({ ok: true, path: target, removedFiles: 0, removedDirs: 0 });
+    } else {
+      process.stdout.write(
+        `dench files rm: ${target} not present in Convex (already absent)\n`,
+      );
+    }
+    return;
+  }
+  if (self.isDir && !recursive) {
+    throw new CliError(
+      `${target} is a directory; pass --recursive to delete it.`,
+      { code: "files_rm_recursive" },
+    );
+  }
+
+  const toDelete = self.isDir
+    ? await listConvexTreeRecursive(runtime, apiKey, target)
+    : [];
+  const fileRows = toDelete.filter((row) => !row.isDir);
+  const dirRows = toDelete.filter((row) => row.isDir);
+  // Children first, parents last.
+  dirRows.sort((a, b) => b.path.length - a.path.length);
+
+  for (const row of fileRows) {
+    await runtime.client.mutation(api.functions.files.deleteFile, {
+      path: row.path,
+      apiKey,
+    } as never);
+  }
+  for (const row of dirRows) {
+    await runtime.client.mutation(api.functions.files.deleteFile, {
+      path: row.path,
+      apiKey,
+    } as never);
+  }
+  await runtime.client.mutation(api.functions.files.deleteFile, {
+    path: target,
+    apiKey,
+  } as never);
+
+  print({
+    ok: true,
+    path: target,
+    removedFiles: fileRows.length + (self.isDir ? 0 : 1),
+    removedDirs: dirRows.length + (self.isDir ? 1 : 0),
+  });
+}
+
+async function runFilesCommand() {
+  const sub = positional(1);
+  if (!sub || sub === "help" || hasFlag("--help")) {
+    process.stdout.write(
+      [
+        "dench files <ls|mv|rm> — workspace file ops that update the UI tree",
+        "",
+        "  dench files ls [<path>] [--recursive] [--json]",
+        "  dench files mv <src> <dst> [--json]",
+        "  dench files rm <path> [--recursive] [--json]",
+        "",
+        "Paths are POSIX paths under /workspace; you can pass either form.",
+        "These mutate Convex directly (and the daemon syncs to the volume).",
+      ].join("\n"),
+    );
+    return;
+  }
+  if (sub === "ls") return await runFilesLs();
+  if (sub === "mv") return await runFilesMv();
+  if (sub === "rm") return await runFilesRm();
+  throw new CliError(`Unknown subcommand: dench files ${sub}`, {
+    code: "files_unknown_subcommand",
+    nextActions: ["Run dench files help for usage."],
+  });
+}
+
+function parentOfPath(input: string): string {
+  const normalized = normalizeFilesPath(input);
+  if (normalized === "/") return "/";
+  const idx = normalized.lastIndexOf("/");
+  return idx <= 0 ? "/" : normalized.slice(0, idx);
+}
+
+function sha256HexSync(bytes: Uint8Array): string {
+  // Used by the dench files commands so we can compute the hash
+  // alongside the upload synchronously. Bun + Node both ship
+  // node:crypto, so this is free.
+  const { createHash } = require("node:crypto") as typeof import("node:crypto");
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
 async function spawnInherited(binary: string, commandArgs: string[]) {
   return await new Promise<number>((resolve, reject) => {
     const child = spawn(binary, commandArgs, {
@@ -2675,14 +3186,16 @@ async function main() {
     }
     const { runCrmCommand } = await import("./crm");
     const runtime = await getRuntime();
-    const sessionRuntime = requireSessionRuntime(runtime, "dench crm");
+    // CRM is org-scoped — accept either an agent session token
+    // (`dch_agent_*` from `dench login`) or a unified Dench API key
+    // (`DENCH_API_KEY` baked into sandbox envVars). Server-side
+    // `requireCrmAccess` (convex/lib/crm/access.ts) dispatches on the
+    // bearer prefix and resolves the org for both.
+    const authedRuntime = requireAuthenticatedRuntime(runtime, "dench crm");
     await runCrmCommand({
-      convex: sessionRuntime.client,
+      convex: authedRuntime.client,
       args: subArgs,
-      // Server-side `requireCrmAccess` (convex/lib/crm/access.ts) accepts
-      // this token and resolves the agent's organization without a Convex
-      // Auth cookie. Mirrors the pattern used by every agentWorkspace fn.
-      sessionToken: sessionRuntime.sessionToken,
+      sessionToken: authedRuntime.sessionToken,
     });
     return;
   }
@@ -2692,6 +3205,60 @@ async function main() {
     return;
   }
 
+  if (command === "files") {
+    await runFilesCommand();
+    return;
+  }
+
+  if (command === "chat") {
+    const subArgs = args.slice(args.indexOf("chat") + 1);
+    const sub = subArgs[0];
+    if (!sub || sub === "help" || sub === "--help") {
+      const { runChatCommand } = await import("./chat");
+      // biome-ignore lint/suspicious/noExplicitAny: harmless help-only stub
+      await runChatCommand({ convex: {} as any, args: subArgs });
+      return;
+    }
+    // `chat new` / `chat send` spawn a chat-turn workflow via
+    // /api/chat/cli (the same workflow the web UI uses). They need
+    // an HTTP host + bearer token, not a Convex client. The
+    // remaining subcommands (list / search / read) are Convex
+    // queries and keep going through `runChatCommand`.
+    if (sub === "new" || sub === "send") {
+      const { runChatSpawnCommand } = await import("./chat-spawn");
+      const runtime = await getRuntime();
+      const authedRuntime = requireAuthenticatedRuntime(
+        runtime,
+        `dench chat ${sub}`,
+      );
+      // Drop the leading subcommand from subArgs — runChatSpawnCommand
+      // expects the remaining tokens (prompt + flags).
+      await runChatSpawnCommand({
+        runtime: {
+          host: authedRuntime.host,
+          bearerToken: authedRuntime.sessionToken,
+        },
+        args: subArgs.slice(1),
+        subcommand: sub,
+      });
+      return;
+    }
+    const { runChatCommand } = await import("./chat");
+    const runtime = await getRuntime();
+    // Past-chat queries are org+user-scoped: the server resolves the
+    // user from the session token, OR from `runId` when authenticating
+    // with a Dench API key. Pass DENCH_RUN_ID through automatically so
+    // `dench chat …` works inside a sandbox without extra flags.
+    const authedRuntime = requireAuthenticatedRuntime(runtime, "dench chat");
+    await runChatCommand({
+      convex: authedRuntime.client,
+      args: subArgs,
+      sessionToken: authedRuntime.sessionToken,
+      runId: process.env.DENCH_RUN_ID?.trim() || undefined,
+    });
+    return;
+  }
+
   if (command === "agent") {
     const subArgs = args.slice(args.indexOf("agent") + 1);
     const sub = subArgs[0];
@@ -2701,6 +3268,27 @@ async function main() {
       await runAgentCommand({ convex: {} as any, args: subArgs });
       return;
     }
+    // Aliases: `dench agent new` / `dench agent send` -> the chat-spawn
+    // implementation. Surfaced under `agent` so users who associate
+    // chat threads with the agent surface still find them; the actual
+    // workflow is identical to `dench chat new` / `dench chat send`.
+    if (sub === "new" || sub === "send") {
+      const { runChatSpawnCommand } = await import("./chat-spawn");
+      const runtime = await getRuntime();
+      const authedRuntime = requireAuthenticatedRuntime(
+        runtime,
+        `dench agent ${sub}`,
+      );
+      await runChatSpawnCommand({
+        runtime: {
+          host: authedRuntime.host,
+          bearerToken: authedRuntime.sessionToken,
+        },
+        args: subArgs.slice(1),
+        subcommand: sub,
+      });
+      return;
+    }
     const { runAgentCommand } = await import("./agent");
     const runtime = await getRuntime();
     await runAgentCommand({
@@ -2881,6 +3469,13 @@ async function main() {
       print(status);
       return;
     }
+    if (runtime.mode === "apiKey") {
+      // No agent session → no agent-status query. Fall back to a thin
+      // env-derived snapshot so sandbox callers still get something
+      // useful from `dench status`.
+      print(await buildContext(runtime));
+      return;
+    }
     const data = await devOverview(runtime);
     const output = scopedStatus
       ? summarizeDevMine(runtime.workspaceArgs.workspaceSlug, data)
@@ -2903,6 +3498,11 @@ async function main() {
       );
       return;
     }
+    if (runtime.mode === "apiKey") {
+      throw loginRequiredError(
+        "dench tasks (agent-scoped task list)",
+      );
+    }
     const data = await devOverview(runtime);
     print(data.tasks);
     return;
@@ -2919,6 +3519,9 @@ async function main() {
       print(status.agents);
       return;
     }
+    if (runtime.mode === "apiKey") {
+      throw loginRequiredError("dench agents");
+    }
     const data = await devOverview(runtime);
     print(data.agents);
     return;
@@ -2935,6 +3538,9 @@ async function main() {
       print(status.approvals);
       return;
     }
+    if (runtime.mode === "apiKey") {
+      throw loginRequiredError("dench approvals");
+    }
     const data = await devOverview(runtime);
     print(data.approvals);
     return;
@@ -3000,6 +3606,7 @@ async function main() {
       );
       return;
     }
+    rejectApiKeyForAgentCommand(runtime, "dench task create");
     const taskId = await runtime.client.mutation(
       api.functions.agentWorkspace.devCreateTask,
       {
@@ -3108,6 +3715,7 @@ async function main() {
       );
       return;
     }
+    rejectApiKeyForAgentCommand(runtime, "dench claim");
     const agentId = option("--agent") ?? (await defaultDevAgentId(runtime));
     print(
       await runtime.client.mutation(api.functions.agentWorkspace.devClaimTask, {
@@ -3135,6 +3743,7 @@ async function main() {
       );
       return;
     }
+    rejectApiKeyForAgentCommand(runtime, "dench log");
     print(
       await runtime.client.mutation(api.functions.agentWorkspace.devAppendLog, {
         ...runtime.workspaceArgs,
@@ -3164,6 +3773,7 @@ async function main() {
       );
       return;
     }
+    rejectApiKeyForAgentCommand(runtime, "dench approval request");
     const approvalId = await runtime.client.mutation(
       api.functions.agentWorkspace.devRequestApproval,
       {