@dench.com/cli 0.4.5 → 0.4.7

package/README.md

@@ -23,7 +23,27 @@ dench login --name "AI Agent - Billing Repo"
 to lowercase snake_case before send (e.g. `--kind "Claude Code"` becomes
 `claude_code`).
 
-The default host is `https://dench.dev`.
+The default backend is `https://dench.dev` (production). Use `dench backend`
+to switch:
+
+```bash
+dench backend show
+dench backend set production
+dench backend set staging
+dench backend set local                  # http://localhost:3000
+dench backend set https://example.com    # custom URL
+dench backend clear                      # revert to production
+```
+
+For one-shot overrides (no config change):
+
+```bash
+dench --prod <cmd>
+dench --staging <cmd>
+dench --backend local <cmd>
+dench --host https://example.com <cmd>
+DENCH_HOST=https://example.com dench <cmd>
+```
 
 The smooth setup flow is:
 
@@ -197,13 +217,31 @@ Auth precedence:
 
 1. Explicit `--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.
+2. A locally-stored `dench login` session for the current backend (set via
+   `dench backend`, `--host`, `--prod`, or `--staging`).
 3. `DENCH_API_KEY` + `CONVEX_URL` (sandbox / automation path).
 
 Plain terminal usage does not silently fall back to dev env vars. Without
 `--dev`, a saved session, or `DENCH_API_KEY` + `CONVEX_URL`, live commands
 return `login_required`.
 
+### `.env` auto-load is opt-in
+
+When `dench` runs from inside the `dench.com` repo it does **not**
+auto-load workspace `.env` / `.env.local` files by default — that used
+to silently flip `NEXT_PUBLIC_CONVEX_URL` to the dev Convex deployment
+and made the CLI talk to local Convex even when the user expected
+production.
+
+Auto-load now turns on only when one of:
+
+- `--dev` (also switches the runtime to dev-workspace mode)
+- `--use-dev-env` (load `.env` files but keep the rest of the runtime)
+- `DENCH_USE_DEV_ENV=1` in the shell env (e.g. via `direnv`)
+- `dench backend set local` (a stored local backend implies dev env)
+
+Explicit shell exports (`GATEWAY_URL=… ./dench …`) always win regardless.
+
 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

package/agent.ts

@@ -1,473 +1,37 @@
-/**
- * `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;
-  /**
-   * Bearer token forwarded by the dispatcher in `cli/dench.ts`. Either a
-   * `dch_agent_*` agent session minted by `dench login` or a unified
-   * Dench API key (`DENCH_API_KEY`) when the CLI is running inside a
-   * sandbox. Used by `runAwait` to authenticate against
-   * `runs:getChildRunStatusForCli`.
-   */
-  sessionToken?: string;
-  /**
-   * Convex `runs._id` of the caller's own run, when authenticated via
-   * an API key (sandbox path). Required by `getChildRunStatusForCli`
-   * to scope the API key's reach to a specific organization.
-   */
-  callerRunId?: string;
-};
-
-// 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 agentHelp(): void {
+  console.log(`Usage: dench agent <subcommand>
 
-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,
-  };
-}
+Agent sessions are normal chat-turn workflows, the same path used by the web UI:
+  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]
+  dench agent follow <thread-id> [--json]
 
-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}`,
-  };
-}
+These are aliases for:
+  dench chat new
+  dench chat send
+  dench chat follow
 
-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;
+Use spawn_agent from inside a running chat to create child agents. Child agents
+are also normal chat threads and can be followed with dench agent follow.
+`);
 }
 
-export async function runAgentCommand(opts: {
+export async function runAgentCommand(_opts: {
   convex: ConvexHttpClient;
   args: string[];
   sessionToken?: string;
   callerRunId?: string;
 }): Promise<void> {
-  const args = [...opts.args];
-  const jsonOutput = hasFlag(args, "--json");
-  const ctx: CliCtx = {
-    convex: opts.convex,
-    args,
-    jsonOutput,
-    sessionToken: opts.sessionToken,
-    callerRunId: opts.callerRunId,
-  };
-  const subcommand = args.shift();
+  const subcommand = _opts.args[0];
   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,
-    },
+  throw new AgentCliError(
+    `Unknown agent subcommand: ${subcommand}. Use dench agent new, send, or follow.`,
   );
-  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>",
-    );
-  }
-  if (!ctx.sessionToken) {
-    throw new AgentCliError(
-      "dench agent await --children needs an authenticated session " +
-        "(run `dench login`, or set DENCH_API_KEY in a sandbox)",
-    );
-  }
-
-  const childIds = childIdsCsv
-    .split(",")
-    .map((id) => id.trim())
-    .filter(Boolean);
-  if (childIds.length === 0) {
-    throw new AgentCliError("--children requires at least one run id");
-  }
-  const start = Date.now();
-  const timeoutMs = parseInt(
-    getFlag(ctx.args, "--timeout-ms") ?? "3600000",
-    10,
-  );
-  const intervalMs = parseInt(
-    getFlag(ctx.args, "--interval-ms") ?? "2000",
-    10,
-  );
-
-  type ChildSnapshot = {
-    runId: string;
-    status: string;
-    summary: string | null;
-    threadId: string | null;
-    terminal: boolean;
-  };
-  const getStatus = makeFunctionReference<"query">(
-    "functions/runs:getChildRunStatusForCli",
-  );
-
-  // Poll each child's status until it reaches a terminal state. The
-  // server uses sessionToken auth (mirrors `dench chat list`) so this
-  // works both for `dch_agent_*` sessions (local dev) and for unified
-  // `DENCH_API_KEY`s (sandbox, must include `--caller-run-id`).
-  const completed: Record<string, ChildSnapshot> = {};
-  while (Object.keys(completed).length < childIds.length) {
-    if (Date.now() - start > timeoutMs) {
-      throw new AgentCliError(
-        `dench agent await timed out after ${timeoutMs}ms with ${
-          Object.keys(completed).length
-        }/${childIds.length} children completed`,
-      );
-    }
-    for (const childId of childIds) {
-      if (completed[childId]) continue;
-      try {
-        const snap = (await ctx.convex.query(getStatus, {
-          sessionToken: ctx.sessionToken,
-          runId: ctx.callerRunId ?? undefined,
-          childRunId: childId as never,
-        })) as ChildSnapshot | null;
-        if (snap?.terminal) {
-          completed[childId] = snap;
-        }
-      } catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        // Treat "not found" / access errors as terminal-with-error so
-        // we don't poll forever on a typo'd id.
-        completed[childId] = {
-          runId: childId,
-          status: "error",
-          summary: msg,
-          threadId: null,
-          terminal: true,
-        };
-      }
-    }
-    if (Object.keys(completed).length < childIds.length) {
-      await new Promise((resolve) => setTimeout(resolve, intervalMs));
-    }
-  }
-  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]
-  dench agent follow <thread-id> [--json]
-  These are aliases for \`dench chat new\` / \`dench chat send\` / \`dench chat follow\`.
-  Use \`follow\` to tail the live stream of an existing thread (e.g.
-  a subagent spawned by \`spawn_agent\`) without sending a new message.
-
-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] [--interval-ms N]
-                                            (polls runs:getChildRunStatusForCli
-                                             with the active session token until
-                                             every child is terminal)
-
-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/crm.ts

@@ -1082,56 +1082,9 @@ async function runActionsCommand(ctx: CrmCliContext): Promise<void> {
       return;
     }
     case "run": {
-      // Two-step happy path: insert crmActionRuns row → POST run-action
-      // route which creates the workflow run + starts agentRunWorkflow.
-      const actionId = shift(ctx.args, "action id");
-      const fieldId = getFlag(ctx.args, "--field-id");
-      const entryId = getFlag(ctx.args, "--entry-id");
-      const goal = getFlag(ctx.args, "--goal") ?? "";
-      const wait = hasFlag(ctx.args, "--wait");
-      assertNoUnknownFlags(ctx.args, "crm actions run");
-      if (!fieldId || !entryId) {
-        throw new CrmCliError(
-          "dench crm actions run requires --field-id and --entry-id",
-        );
-      }
-      const created = (await callMutation(ctx, api.actions.startActionRun, {
-        actionId,
-        fieldId: fieldId as any,
-        entryId: entryId as any,
-      })) as { id: string };
-      // Hop through /api/crm/run-action so the workflow actually starts.
-      const apiBase = (
-        process.env.DENCH_API_URL ?? "http://localhost:3000"
-      ).replace(/\/+$/, "");
-      const apiKey =
-        process.env.DENCH_API_KEY?.trim() ??
-        process.env.DENCH_FALLBACK_API_KEY?.trim() ??
-        "";
-      if (!apiKey) {
-        throw new CrmCliError(
-          "DENCH_API_KEY required to fire the action workflow",
-        );
-      }
-      const response = await fetch(`${apiBase}/api/crm/run-action`, {
-        method: "POST",
-        headers: {
-          "content-type": "application/json",
-          authorization: `Bearer ${apiKey}`,
-        },
-        body: JSON.stringify({ actionRunId: created.id, goal }),
-      });
-      const json = (await response.json().catch(() => ({}))) as {
-        runId?: string;
-        error?: string;
-      };
-      if (!response.ok) {
-        throw new CrmCliError(
-          `run-action failed (${response.status}): ${json.error ?? ""}`,
-        );
-      }
-      out(ctx, { actionRunId: created.id, runId: json.runId, wait });
-      return;
+      throw new CrmCliError(
+        "dench crm actions run has been removed. Start a normal agent with `dench agent new --follow` and ask it to perform the CRM action.",
+      );
     }
     default:
       throw new CrmCliError(`Unknown crm actions verb: ${verb ?? "<none>"}`);
@@ -1700,7 +1653,7 @@ async function callEnrichmentGatewayForEntry(args: {
 
 async function enrichOneEntry(
   ctx: CrmCliContext,
-  args: CellEnrichmentArgs & {
+  args: Omit<CellEnrichmentArgs, "entryId"> & {
     target: EnrichmentTarget;
     entry: CrmEntryForEnrichment;
   },

package/cron.ts

@@ -356,14 +356,9 @@ async function runCreate(ctx: CronCliContext): Promise<void> {
   }
   const disabled = hasFlag(ctx.args, "--disabled");
   const deleteAfterRun = hasFlag(ctx.args, "--delete-after-run");
-  const target = getFlag(ctx.args, "--target") as
-    | "chat_turn"
-    | "agent_run"
-    | undefined;
-  if (target && !["chat_turn", "agent_run"].includes(target)) {
-    throw new CronCliError(
-      `--target must be chat_turn|agent_run (got "${target}")`,
-    );
+  const target = getFlag(ctx.args, "--target") as "chat_turn" | undefined;
+  if (target && target !== "chat_turn") {
+    throw new CronCliError(`--target must be chat_turn (got "${target}")`);
   }
   const schedule = consumeScheduleFlags(ctx.args);
   if (!schedule) {
@@ -523,7 +518,7 @@ Create / update (one of --every / --cron / --at is required for create):
       [--overlap skip|queue|kill_old]     # default: skip
       [--disabled]                        # default: enabled
       [--delete-after-run]                # one-shot at-schedule; default false
-      [--target chat_turn|agent_run]      # default: chat_turn (fires a fresh chat thread)
+      [--target chat_turn]                # default: chat_turn (fires a fresh chat thread)
       [--json]
 
   dench cron update <jobId> [--name N] [--prompt P] [--description D] \\