@dench.com/cli 0.3.6 → 0.3.8

package/dench.ts

@@ -327,6 +327,41 @@ function throwIfCliError(value: unknown) {
   }
 }
 
+function normalizeCliError(error: unknown): CliError {
+  if (error instanceof CliError) return error;
+  const message = error instanceof Error ? error.message : String(error);
+  if (message.includes("Invalid dev agent key")) {
+    return new CliError("Invalid dev agent key", {
+      code: "invalid_dev_agent_key",
+      nextActions: [
+        "Check that DENCH_DEV_AGENT_KEY in your shell matches the Convex deployment env.",
+        "Use --dev only for a local/dev Convex deployment configured with that key.",
+        "For normal terminal usage, run dench login or set DENCH_API_KEY + CONVEX_URL.",
+      ],
+    });
+  }
+  if (message.includes("Dev CRM access is disabled in production")) {
+    return new CliError("Dev CRM access is disabled in production", {
+      code: "dev_access_disabled",
+      nextActions: [
+        "Remove --dev and run dench login for terminal access.",
+        "Or use DENCH_API_KEY + CONVEX_URL for sandbox/automation access.",
+      ],
+    });
+  }
+  if (message.includes("Invalid Dench API key")) {
+    return new CliError("Invalid Dench API key", {
+      code: "invalid_api_key",
+      nextActions: [
+        "Check DENCH_API_KEY and CONVEX_URL point to the same organization/deployment.",
+        "Unset DENCH_API_KEY to use a saved dench login session instead.",
+        "Or run dench login to create a new terminal session.",
+      ],
+    });
+  }
+  return new CliError(message);
+}
+
 function parseJsonObjectOption(name: string) {
   const raw = option(name);
   if (!raw) return {};
@@ -461,8 +496,12 @@ Past chat threads (own + shared in this workspace):
 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)
+  dench chat follow <thread-id> [--json]            (tail a live thread by id)
+  dench chat tree [<root-thread-id>] [--limit N] [--json]
+                                                    (parent-child thread tree)
+  dench agent new ...     (alias for dench chat new)
+  dench agent send ...    (alias for dench chat send)
+  dench agent follow ...  (alias for dench chat follow)
 
   Help: dench chat help
 
@@ -1755,6 +1794,30 @@ async function getRuntime() {
       });
     }
 
+    // Sandbox session-mode path: workflow minting provisions a real
+    // dch_agent_* token at sandbox-create time. Prefer it over apiKey so
+    // agentWorkspace.* commands (Composio tools) work inside sandboxes.
+    const sandboxAgentToken = process.env.DENCH_AGENT_SESSION_TOKEN?.trim();
+    const sandboxConvexUrl = resolveApiKeyConvexUrl();
+    if (sandboxAgentToken && sandboxConvexUrl) {
+      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: "session" as const,
+        host: apiHost,
+        client: new ConvexHttpClient(sandboxConvexUrl),
+        sessionToken: sandboxAgentToken,
+        organization:
+          orgId && orgSlug
+            ? { id: orgId, name: orgSlug, slug: orgSlug }
+            : undefined,
+      };
+    }
+
     // 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
@@ -1781,10 +1844,12 @@ async function getRuntime() {
             : undefined,
       };
     }
+
+    throw loginRequiredError();
   }
 
   if (!hasDevEnv()) {
-    throw hasFlag("--dev") ? missingDevEnvError() : loginRequiredError();
+    throw missingDevEnvError();
   }
 
   return {
@@ -1799,6 +1864,22 @@ async function getRuntime() {
 
 type Runtime = Awaited<ReturnType<typeof getRuntime>>;
 
+function stripRuntimeFlags(args: string[]) {
+  const booleanFlags = new Set(["--dev", "--prod", "--staging"]);
+  const valueFlags = new Set(["--convex-url", "--host"]);
+  const stripped: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (booleanFlags.has(arg)) continue;
+    if (valueFlags.has(arg)) {
+      i++;
+      continue;
+    }
+    stripped.push(arg);
+  }
+  return stripped;
+}
+
 /**
  * `session` mode is required for `agentWorkspace.*` calls because they
  * gate on `validateAgentSession` server-side, which only accepts the
@@ -1837,6 +1918,13 @@ function requireAuthenticatedRuntime(
   throw loginRequiredError(command);
 }
 
+function encodeDevCrmSessionToken(args: {
+  workspaceSlug: string;
+  devKey: string;
+}) {
+  return `dch_dev_${encodeURIComponent(args.workspaceSlug)}:${encodeURIComponent(args.devKey)}`;
+}
+
 function agentSessionRequiredError(command: string) {
   return new CliError(
     `${command} requires an agent session — DENCH_API_KEY is org-scoped and cannot impersonate a specific agent`,
@@ -3458,7 +3546,7 @@ async function main() {
   }
 
   if (command === "crm") {
-    const subArgs = args.slice(args.indexOf("crm") + 1);
+    const subArgs = stripRuntimeFlags(args.slice(args.indexOf("crm") + 1));
     const sub = subArgs[0];
     // Short-circuit help so users don't need a session to read the
     // surface. The crm dispatcher's own help resolves --json + the
@@ -3478,6 +3566,14 @@ async function main() {
     // (`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.
+    if (runtime.mode === "dev") {
+      await runCrmCommand({
+        convex: runtime.client,
+        args: subArgs,
+        sessionToken: encodeDevCrmSessionToken(runtime.workspaceArgs),
+      });
+      return;
+    }
     const authedRuntime = requireAuthenticatedRuntime(runtime, "dench crm");
     await runCrmCommand({
       convex: authedRuntime.client,
@@ -3534,12 +3630,13 @@ async function main() {
       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") {
+    // `chat new` / `chat send` / `chat follow` use HTTP routes
+    // (/api/chat/cli for spawn, /api/chat/[runId]/stream and
+    // /api/chat/stream for follow) so they need an authenticated host
+    // + bearer token, not a Convex client. The remaining subcommands
+    // (list / search / read / tree) are Convex queries and keep going
+    // through `runChatCommand`.
+    if (sub === "new" || sub === "send" || sub === "follow") {
       const { runChatSpawnCommand } = await import("./chat-spawn");
       const runtime = await getRuntime();
       const authedRuntime = requireAuthenticatedRuntime(
@@ -3583,11 +3680,12 @@ 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") {
+    // Aliases: `dench agent new` / `dench agent send` / `dench agent
+    // follow` -> 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` / `dench chat follow`.
+    if (sub === "new" || sub === "send" || sub === "follow") {
       const { runChatSpawnCommand } = await import("./chat-spawn");
       const runtime = await getRuntime();
       const authedRuntime = requireAuthenticatedRuntime(
@@ -3609,6 +3707,8 @@ async function main() {
     await runAgentCommand({
       convex: runtime.client,
       args: subArgs,
+      sessionToken: runtime.sessionToken,
+      callerRunId: process.env.DENCH_RUN_ID?.trim() || undefined,
     });
     return;
   }
@@ -4237,11 +4337,12 @@ async function main() {
 }
 
 main().catch((error) => {
-  const extra = error instanceof CliError ? error.payload : {};
+  const normalized = normalizeCliError(error);
+  const extra = normalized.payload;
   const payload: JsonRecord = {
     ok: false,
     ...extra,
-    error: error instanceof Error ? error.message : String(error),
+    error: normalized.message,
   };
   if (json) {
     console.error(JSON.stringify(payload, null, 2));

package/lib/cli-args.ts

@@ -7,9 +7,20 @@
  *   - shift(args, expected): pop the next positional arg or throw.
  *   - getFlag(args, name): pull the value following `--name` and remove
  *     both tokens from args. Returns undefined if the flag is missing.
+ *   - getFlagWithAliases(args, primary, aliases): like getFlag but
+ *     accepts multiple flag names; the first one found wins. Used to
+ *     accept e.g. `--data` and `--fields` interchangeably so a confused
+ *     caller doesn't silently produce blank rows.
  *   - hasFlag(args, name): true iff `--name` appears (and removes it).
  *   - parseJson(value): JSON.parse with a CliError-style throw on
  *     failure.
+ *   - assertNoUnknownFlags(args, command): after all known flags have
+ *     been drained via getFlag/hasFlag, throw if any token starting
+ *     with `--` is left in args. Catches typos like `--fields` when
+ *     the subcommand only knows `--data` — the previous behaviour
+ *     silently dropped the typo and produced empty writes (see
+ *     incident in chat y5710jn4313ht2p6fwmw0m0mjn8636ya where 15 blank
+ *     CRM rows were created before the agent realized).
  *
  * NOTE: each module wraps its own *CliError class so we don't import
  * across cli/ entry points; this module's errors throw plain Error and
@@ -24,10 +35,7 @@ export function shift(args: string[], expected: string): string {
   return value;
 }
 
-export function getFlag(
-  args: string[],
-  name: string,
-): string | undefined {
+export function getFlag(args: string[], name: string): string | undefined {
   const idx = args.indexOf(name);
   if (idx === -1) return undefined;
   const value = args[idx + 1];
@@ -35,6 +43,36 @@ export function getFlag(
   return value;
 }
 
+export function getFlagWithAliases(
+  args: string[],
+  primary: string,
+  aliases: readonly string[],
+): string | undefined {
+  // Try each name in order; the first one found is consumed and returned.
+  // Aliases (and duplicate occurrences of the picked name) are still
+  // removed from args so unknown-flag detection downstream doesn't flag
+  // them as typos and so the caller can't get bitten by silent
+  // first-wins drift across multiple invocations.
+  const all = [primary, ...aliases];
+  let chosen: string | undefined;
+  for (const name of all) {
+    const value = getFlag(args, name);
+    if (value !== undefined) {
+      chosen = value;
+      break;
+    }
+  }
+  // Drain any remaining occurrences of every alias (including the
+  // primary). With a single getFlag pass per name we'd leave a
+  // duplicate `--fields` behind to look like an unknown flag.
+  for (const name of all) {
+    while (getFlag(args, name) !== undefined) {
+      // Intentional empty body: drain duplicates.
+    }
+  }
+  return chosen;
+}
+
 export function hasFlag(args: string[], name: string): boolean {
   const idx = args.indexOf(name);
   if (idx === -1) return false;
@@ -50,3 +88,22 @@ export function parseJson(value: string | undefined): unknown {
     throw new CliArgError(`Invalid JSON: ${value}`);
   }
 }
+
+export function assertNoUnknownFlags(
+  args: readonly string[],
+  command: string,
+): void {
+  // After every getFlag/hasFlag/getFlagWithAliases call has had a chance
+  // to drain known flags, any remaining token that starts with `--` is
+  // unknown. We surface the first one with a hint so the caller can fix
+  // the typo. Don't include positional `--` literals; raw `--` (used by
+  // some shells to terminate option parsing) is allowed.
+  for (const token of args) {
+    if (token === "--") continue;
+    if (token.startsWith("--")) {
+      throw new CliArgError(
+        `Unknown flag for ${command}: ${token}. Run \`dench ${command.split(" ")[0]} help\` for the full flag list.`,
+      );
+    }
+  }
+}

package/package.json

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