@dench.com/cli 0.3.1 → 0.3.2

package/README.md

@@ -149,3 +149,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/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;
 };

package/dench.ts

@@ -1620,11 +1620,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 +1686,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 +1731,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 +2029,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 +2456,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 +2616,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);
 }
@@ -2675,14 +2796,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;
   }
@@ -2881,6 +3004,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 +3033,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 +3054,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 +3073,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 +3141,7 @@ async function main() {
       );
       return;
     }
+    rejectApiKeyForAgentCommand(runtime, "dench task create");
     const taskId = await runtime.client.mutation(
       api.functions.agentWorkspace.devCreateTask,
       {
@@ -3108,6 +3250,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 +3278,7 @@ async function main() {
       );
       return;
     }
+    rejectApiKeyForAgentCommand(runtime, "dench log");
     print(
       await runtime.client.mutation(api.functions.agentWorkspace.devAppendLog, {
         ...runtime.workspaceArgs,
@@ -3164,6 +3308,7 @@ async function main() {
       );
       return;
     }
+    rejectApiKeyForAgentCommand(runtime, "dench approval request");
     const approvalId = await runtime.client.mutation(
       api.functions.agentWorkspace.devRequestApproval,
       {

package/fs-daemon.ts

@@ -359,15 +359,23 @@ async function pullDownRemoteFile(
   );
 }
 
+/**
+ * sysexits.h-style exit codes the supervisor (in
+ * src/lib/daytona/sandbox-bootstrap.ts) recognizes as **permanent** —
+ * keep restarting won't fix a missing env var or a missing dependency,
+ * so the supervisor gives up instead of crash-looping. Anything else
+ * (network blip, transient Convex error) exits 1 and gets retried.
+ */
+const EXIT_CONFIG_ERROR = 78;
+
 async function runDaemon(daemonArgs: Args): Promise<void> {
   const convexUrl = process.env.CONVEX_URL?.trim();
   const apiKey = process.env.DENCH_API_KEY?.trim();
   if (!convexUrl || !apiKey) {
     console.error(
-      "[dench-fs-daemon] CONVEX_URL or DENCH_API_KEY missing in env; nothing to sync",
+      "[dench-fs-daemon] CONVEX_URL or DENCH_API_KEY missing in env; refusing to start",
     );
-    setInterval(() => undefined, 60_000);
-    return;
+    process.exit(EXIT_CONFIG_ERROR);
   }
 
   const client = new DenchFileClient(convexUrl, apiKey);
@@ -386,12 +394,11 @@ async function runDaemon(daemonArgs: Args): Promise<void> {
     chokidar = (await import("chokidar")) as never;
   } catch (error) {
     console.error(
-      `[dench-fs-daemon] chokidar not available; running in idle mode (${
+      `[dench-fs-daemon] chokidar not available; refusing to start (${
         error instanceof Error ? error.message : String(error)
       })`,
     );
-    setInterval(() => undefined, 60_000);
-    return;
+    process.exit(EXIT_CONFIG_ERROR);
   }
 
   const watcher = chokidar.watch(daemonArgs.workspace, {
@@ -705,10 +712,10 @@ main().catch((error) => {
       error instanceof Error ? (error.stack ?? error.message) : String(error)
     }`,
   );
-  // Long-running daemon: don't exit on transient errors. One-shot
-  // subcommands use a non-zero exit so callers see failure.
-  if (process.argv.slice(2)[0]?.startsWith("stream-")) {
-    process.exit(1);
-  }
-  setInterval(() => undefined, 60_000);
+  // Always exit with a non-zero code so the supervisor (in
+  // src/lib/daytona/sandbox-bootstrap.ts) can decide whether to
+  // restart. Previously we parked the process on a noop interval,
+  // which made `pgrep dench-fs-daemon` report "alive" for a daemon
+  // that had silently given up syncing.
+  process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dench.com/cli",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Dench agent workspace CLI.",
   "type": "module",
   "bin": {