@dench.com/cli 3.6.6-staging.386 → 3.8.0-staging.389

package/dench.ts

@@ -28,10 +28,13 @@ import {
   resolveHostFromArgs,
   STAGING_HOST,
 } from "./host";
+import { CliArgError, isHelpRequest } from "./lib/cli-args";
 import { cliVersion } from "./lib/cli-version";
+import { assertDeclaredCommandFlags } from "./lib/command-args";
 import { denchConfigDirectory } from "./lib/config-path.mjs";
 import { resolveOrganizationBySelector } from "./lib/organizationSelector";
-import { backendErrorText } from "./lib/public-error";
+import { normalizeParentArgv } from "./lib/parent-argv";
+import { backendErrorText, publicErrorDetails } from "./lib/public-error";
 import { formatApprovalOpenMessage, openUrl } from "./openUrl";
 import {
   explicitSessionKeyInput,
@@ -215,10 +218,13 @@ const api = {
 };
 const CONFIG_DIR = denchConfigDirectory();
 const CONFIG_PATH = join(CONFIG_DIR, "config.json");
-const args = process.argv.slice(2);
-const json = args.includes("--json");
-const filteredArgs = args.filter((arg) => arg !== "--json");
-const scopedStatus = args.includes("--mine") || args.includes("--self");
+// A child process owns every token after `--`, including --host and --json.
+// Normalize only Dench's parent arguments; pass child argv through byte for byte.
+const { args, runtimeArgs } = normalizeParentArgv(process.argv.slice(2));
+const json = runtimeArgs.includes("--json");
+const filteredArgs = runtimeArgs.filter((arg) => arg !== "--json");
+const scopedStatus =
+  runtimeArgs.includes("--mine") || runtimeArgs.includes("--self");
 
 function readEnv(name: string) {
   const value = process.env[name]?.trim();
@@ -321,13 +327,18 @@ function throwIfCliError(value: unknown) {
   }
   const record = value as JsonRecord;
   if (record.ok === false && typeof record.error === "string") {
-    throw new Error(record.error);
+    throw new CliError(record.error, publicErrorDetails(record));
   }
 }
 
 function normalizeCliError(error: unknown): CliError {
-  if (error instanceof CliError) return error;
+  if (error instanceof CliError) {
+    error.payload = { ...error.payload, ...publicErrorDetails(error.payload) };
+    return error;
+  }
   const message = backendErrorText(error);
+  if (error instanceof CliArgError)
+    return new CliError(message, { code: error.code, retryable: false });
   if (message.includes("Invalid dev agent key")) {
     return new CliError("Invalid dev agent key", {
       code: "invalid_dev_agent_key",
@@ -369,7 +380,10 @@ function normalizeCliError(error: unknown): CliError {
       ],
     });
   }
-  return new CliError(message);
+  return new CliError(message, {
+    code: "cli_error",
+    ...publicErrorDetails(error),
+  });
 }
 
 function _parseJsonObjectOption(name: string) {
@@ -632,14 +646,11 @@ Past chat threads (own + shared in this workspace):
   dench chat delete --ids id1,id2 [--yes] [--json]   (PERMANENTLY deletes threads)
 
 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 new "<prompt>" [--environment NAME] [--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 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
 
@@ -661,30 +672,23 @@ returns ENOSYS on the FUSE-backed volume mount):
 Persist scratch -> workspace (cp from /tmp into /workspace + cloud sync):
   dench stage <local-path> [<workspace-dest>] [--clean] [--json]
 
-Subagents:
-  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
-  dench agent message <toRunId> '<text>' [--from-run-id <id>]
-  dench agent wait-message
-  dench agent pause <runId>
-  dench agent resume <runId> ['optional prompt']
-  dench agent continue <prevRunId> '<prompt>'
-  dench agent tree [<rootRunId>]
-  Help: dench agent help
+Reusable workspace setup:
+  dench env list | show <name> | save <name> --path <directory> | run <name> -- <command> | delete <name>
+  dench secrets set <NAME> --stdin [--kind env|file]
+  dench secrets list | delete <NAME>                metadata only; values are never printed
+  Help: dench env --help, dench secrets --help
 
   dench --version
+  dench reference <name> [--json]      Offline CLI-version-matched skill/reference
+  dench reference --list [--json]     Bundled reference index and revision
 
-Self-updating agent harness:
-  dench identity show | edit                    IDENTITY.md (org-wide)
-  dench organisation show | edit                ORGANISATION.md
-  dench user show | edit                        USER.md (per-member)
-  dench tools show | edit                       TOOLS.md notes section
-  dench mem show | append "<text>" | set        MEMORY.md aggregate
-  dench bootstrap status | complete | reopen | template
-  dench model default <id|clear>
-  dench model thread <threadId> <id|clear>
-  dench daily today | show <YYYY-MM-DD>
-  Help: dench identity help
+Standing context and memory:
+  dench context --sections identity,organisation,user,memory,rules,tools [--json]
+  dench context set <identity|organisation|user|tools|rules> --stdin
+  dench memory search "<query>" | save <key> "<fact>"
+  dench model default <id|clear> | thread <threadId> <id|clear>
+  Context describes preferences and instructions. Environments store setup;
+  secrets store credentials. A memory note does not install or save either.
 
 External tools:
   dench integrations is an alias for dench tool status -- it lists connected apps.
@@ -746,13 +750,14 @@ function contextHelp() {
 Usage:
   dench context [--instructions] [--json]
   dench context --sections organisation,user,memory [--json]
-  dench instructions [--json]
+  dench context set <identity|organisation|user|tools|rules> --stdin | --content "text" [--json]
 
 Shows the current workspace, current agent, assigned tasks, pending approvals
 requested by this agent, connected apps when available, and useful next commands.
 
 Use --instructions (or dench instructions) to print the standing workspace
-instructions external agents should treat as system-level guidance.
+instructions for the current workspace. Context and memory do not persist
+credentials or installed software: use dench secrets and dench env.
 `);
 }
 
@@ -2694,19 +2699,33 @@ type Runtime = Awaited<ReturnType<typeof getRuntime>>;
  * `dench members list --json` print the human table and `dench crm … --json`
  * fall back to text on empty results (`(no rows)`), breaking `| jq` pipelines.
  */
-function stripRuntimeFlags(args: string[]) {
+function stripRuntimeFlags(args: string[], validateValues = true) {
   const booleanFlags = new Set([
     "--dev",
     "--prod",
     "--staging",
     "--use-dev-env",
   ]);
-  const valueFlags = new Set(["--convex-url", "--host", "--backend"]);
+  const valueFlags = new Set([
+    "--convex-url",
+    "--host",
+    "--backend",
+    "--session-key",
+    "--session",
+  ]);
   const stripped: string[] = [];
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
+    if (arg === "--") {
+      stripped.push(...args.slice(i));
+      break;
+    }
     if (booleanFlags.has(arg)) continue;
     if (valueFlags.has(arg)) {
+      if (!args[i + 1] || args[i + 1].startsWith("-")) {
+        if (validateValues) throw new CliArgError(`Missing value for ${arg}`);
+        continue;
+      }
       i++;
       continue;
     }
@@ -3392,7 +3411,7 @@ async function resolveFsDaemonEnv(): Promise<NodeJS.ProcessEnv> {
 }
 
 async function runFsCommand() {
-  const subArgs = args.slice(args.indexOf("fs") + 1);
+  const subArgs = stripRuntimeFlags(args.slice(args.indexOf("fs") + 1));
   const configuredBinary = process.env.DENCH_FS_DAEMON_BIN?.trim();
   const binary = configuredBinary || "dench-fs-daemon";
   const daemonEnv = await resolveFsDaemonEnv();
@@ -4303,10 +4322,234 @@ function isCommandNotFound(error: unknown) {
 }
 
 async function main() {
+  if (isHelpRequest(runtimeArgs)) {
+    const helpArgs = stripRuntimeFlags(runtimeArgs, false).filter(
+      (arg) => !["--json", "--help", "-h"].includes(arg),
+    );
+    if (helpArgs[0] === "help") helpArgs.shift();
+    if (!helpArgs.length) {
+      help();
+      return;
+    }
+    const path = helpArgs.filter(
+      (arg) => !["help", "--help", "-h"].includes(arg),
+    );
+    if (path[0] === "daily") {
+      console.log(
+        `dench ${path.join(" ")} was retired. Search history with dench chat search or read existing daily files with dench files download. Harness A does not automatically write daily logs.`,
+      );
+      return;
+    }
+    // Root help retains domain-specific setup, account and pagination guidance.
+    // These are explicit help-only paths; never pass mutation arguments to a handler.
+    if (path.length === 1) {
+      const roots: Record<string, () => void | Promise<void>> = {
+        reference: async () =>
+          console.log((await import("./reference")).REFERENCE_HELP),
+        env: async () =>
+          console.log((await import("./environments")).environmentHelpText()),
+        secrets: async () =>
+          console.log(
+            (await import("./workspace-secrets")).workspaceSecretsHelpText(),
+          ),
+        tool: toolHelp,
+        integrations: integrationsHelp,
+        backend: backendHelp,
+        signin: signinHelp,
+        login: signinHelp,
+        onboard: signinHelp,
+        setup: signinHelp,
+        "what-can-i-do": signinHelp,
+        register: signinHelp,
+        memory: memoryHelp,
+        billing: billingHelp,
+        logout: logoutHelp,
+        context: contextHelp,
+        artifacts: artifactsHelp,
+        "suggested-work": artifactsHelp,
+        lists: listsCliHelp,
+        leads: leadsHelp,
+        companies: companiesHelp,
+        jobs: jobsHelp,
+        status: statusHelp,
+        web: async () => (await import("./web")).webHelp(),
+        crm: async () =>
+          (await import("./crm")).runCrmCommand({
+            convex: {} as ConvexHttpClient,
+            args: ["help"],
+          }),
+        apps: async () =>
+          (await import("./apps")).runAppsCommand({
+            convex: {} as ConvexHttpClient,
+            args: ["help"],
+          }),
+      };
+      if (roots[path[0]]) {
+        await roots[path[0]]();
+        return;
+      }
+    }
+    if (helpArgs[0] === "reference") {
+      console.log((await import("./reference")).REFERENCE_HELP);
+      return;
+    }
+    // Preserve the small, established CRM read help including its cursor contract.
+    if (helpArgs[0] === "crm" && ["query", "aggregate"].includes(helpArgs[1])) {
+      const { runCrmCommand } = await import("./crm");
+      await runCrmCommand({
+        convex: {} as ConvexHttpClient,
+        args: [...helpArgs.slice(1), "--help"],
+      });
+      return;
+    }
+    const { commandHelp } = await import("./lib/command-help");
+    const usage =
+      helpArgs[0] === "email"
+        ? (await import("./email")).emailHelpText()
+        : helpArgs[0] === "crm"
+          ? (await import("./crm")).crmHelpText()
+          : helpArgs[0] === "env"
+            ? (await import("./environments")).environmentHelpText()
+            : helpArgs[0] === "secrets"
+              ? (await import("./workspace-secrets")).workspaceSecretsHelpText()
+              : "";
+    console.log(commandHelp(helpArgs, usage));
+    return;
+  }
   const command = positional(0);
   const subcommand = positional(1);
 
-  if (command === "version" || hasFlag("--version")) {
+  assertDeclaredCommandFlags(stripRuntimeFlags(runtimeArgs));
+
+  // New setup commands validate before authentication and never consume child flags.
+  if (command === "env" || command === "secrets") {
+    const rawSubArgs = args.slice(args.indexOf(command) + 1);
+    const helpRequested =
+      runtimeArgs.includes("--help") ||
+      runtimeArgs.includes("-h") ||
+      subcommand === "help";
+    const subArgs = helpRequested ? rawSubArgs : stripRuntimeFlags(rawSubArgs);
+    const mod =
+      command === "env"
+        ? await import("./environments")
+        : await import("./workspace-secrets");
+    if ("validateEnvironmentArgs" in mod) {
+      const parsed = mod.validateEnvironmentArgs(subArgs);
+      if (parsed.verb === "help") {
+        console.log(mod.environmentHelpText());
+        return;
+      }
+      const runtime = requireAuthenticatedRuntime(
+        await getRuntime(),
+        "dench env",
+      );
+      await mod.runEnvironmentCommand({
+        convex: runtime.client,
+        args: subArgs,
+        sessionToken: runtime.sessionToken,
+        apiUrl: runtime.host,
+      });
+    } else {
+      const parsed = mod.validateWorkspaceSecretsArgs(subArgs);
+      if (parsed.verb === "help") {
+        console.log(mod.workspaceSecretsHelpText());
+        return;
+      }
+      const runtime = requireAuthenticatedRuntime(
+        await getRuntime(),
+        "dench secrets",
+      );
+      await mod.runWorkspaceSecretsCommand({
+        convex: runtime.client,
+        args: subArgs,
+        sessionToken: runtime.sessionToken,
+      });
+    }
+    return;
+  }
+  if (
+    command === "context" &&
+    (runtimeArgs.includes("--help") ||
+      runtimeArgs.includes("-h") ||
+      subcommand === "help")
+  ) {
+    contextHelp();
+    return;
+  }
+  if (command === "daily") {
+    const guidance =
+      "Daily-log commands were retired. Search actual history with dench chat search or read existing daily files with dench files download. Nothing writes daily logs automatically in Harness A.";
+    if (
+      runtimeArgs.includes("--help") ||
+      runtimeArgs.includes("-h") ||
+      subcommand === "help"
+    ) {
+      console.log(guidance);
+      return;
+    }
+    throw new CliError(guidance, {
+      code: "deprecated_command",
+      retryable: false,
+    });
+  }
+  if (command === "context" && subcommand === "set") {
+    const { validateContextSet, runContextSet } = await import(
+      "./context-settings"
+    );
+    const subArgs = stripRuntimeFlags(args.slice(args.indexOf(command) + 1));
+    validateContextSet(subArgs);
+    const runtime = requireAuthenticatedRuntime(
+      await getRuntime(),
+      "dench context set",
+    );
+    await runContextSet({
+      convex: runtime.client,
+      args: subArgs,
+      sessionToken: runtime.sessionToken,
+    });
+    return;
+  }
+  if (
+    command === "memory" &&
+    (runtimeArgs.includes("--help") || runtimeArgs.includes("-h"))
+  ) {
+    memoryHelp();
+    return;
+  }
+  if (command === "memory" && subcommand === "save") {
+    const kind = option("--kind") ?? "fact";
+    if (
+      ![
+        "fact",
+        "decision",
+        "preference",
+        "goal",
+        "tool_note",
+        "other",
+        "convention",
+        "project_context",
+        "agent_lesson",
+        "docs_knowledge",
+        "open_goal",
+      ].includes(kind)
+    )
+      throw new CliError(
+        "Unsupported memory kind. Use memory for facts/preferences; use dench secrets set NAME --stdin for credentials and dench env save for reusable setup.",
+        { code: "validation_failed", retryable: false },
+      );
+  }
+
+  if (command === "reference") {
+    await (await import("./reference")).runReferenceCommand(
+      stripRuntimeFlags(args.slice(args.indexOf("reference") + 1)),
+    );
+    return;
+  }
+
+  if (
+    command === "version" ||
+    stripRuntimeFlags(runtimeArgs)[0] === "--version"
+  ) {
     console.log(await cliVersion());
     return;
   }
@@ -4741,7 +4984,7 @@ async function main() {
   }
 
   if (command === "web") {
-    const subArgs = args.slice(args.indexOf("web") + 1);
+    const subArgs = stripRuntimeFlags(args.slice(args.indexOf("web") + 1));
     const filteredSubArgs = subArgs.filter((a) => a !== "--json");
     const { runWebCommand, webHelp } = await import("./web");
     const sub = filteredSubArgs[0];
@@ -4761,7 +5004,7 @@ async function main() {
   }
 
   if (command === "search") {
-    const subArgs = args.slice(args.indexOf("search") + 1);
+    const subArgs = stripRuntimeFlags(args.slice(args.indexOf("search") + 1));
     const filteredSubArgs = subArgs.filter((a) => a !== "--json");
     const { runSearchCommand } = await import("./search");
     const sub = filteredSubArgs[0];
@@ -4784,7 +5027,7 @@ async function main() {
   }
 
   if (command === "image") {
-    const subArgs = args.slice(args.indexOf("image") + 1);
+    const subArgs = stripRuntimeFlags(args.slice(args.indexOf("image") + 1));
     const filteredSubArgs = subArgs.filter((a) => a !== "--json");
     const { runImageCommand } = await import("./image");
     const sub = filteredSubArgs[0];
@@ -4804,7 +5047,7 @@ async function main() {
   }
 
   if (command === "email") {
-    const subArgs = args.slice(args.indexOf("email") + 1);
+    const subArgs = stripRuntimeFlags(args.slice(args.indexOf("email") + 1));
     const { runEmailCommand } = await import("./email");
     const runtime = await getRuntime();
     const authedRuntime = requireAuthenticatedRuntime(runtime, "dench email");
@@ -4813,7 +5056,7 @@ async function main() {
       | undefined;
     try {
       if (
-        subArgs[0] !== "draft" &&
+        !["draft", "inbox", "send"].includes(subArgs[0]) &&
         !subArgs.some(
           (arg) => arg === "--mailbox" || arg.startsWith("--mailbox="),
         )
@@ -4922,7 +5165,7 @@ async function main() {
   }
 
   if (command === "browser") {
-    const subArgs = args.slice(args.indexOf("browser") + 1);
+    const subArgs = stripRuntimeFlags(args.slice(args.indexOf("browser") + 1));
     const { runBrowserCommand } = await import("./browser");
     const runtime = await getRuntime();
     const authedRuntime = requireAuthenticatedRuntime(runtime, "dench browser");
@@ -4947,7 +5190,7 @@ async function main() {
   // `dench ads` is canonical; `dench ad` and `dench adline` are aliases for
   // the same command (one code path in ./ads).
   if (command === "ads" || command === "ad" || command === "adline") {
-    const subArgs = args.slice(args.indexOf(command) + 1);
+    const subArgs = stripRuntimeFlags(args.slice(args.indexOf(command) + 1));
     const { runAdsCommand } = await import("./ads");
     // Earning is opt-in: resolve the agent session token best-effort so a
     // signed-in developer gets credited on flush, but never require login —
@@ -4983,7 +5226,7 @@ async function main() {
   }
 
   if (command === "chat") {
-    const subArgs = args.slice(args.indexOf("chat") + 1);
+    const subArgs = stripRuntimeFlags(args.slice(args.indexOf("chat") + 1));
     const sub = subArgs[0];
     if (!sub || sub === "help" || sub === "--help") {
       const { runChatCommand } = await import("./chat");
@@ -5033,43 +5276,33 @@ async function main() {
   }
 
   if (command === "agent") {
-    const subArgs = args.slice(args.indexOf("agent") + 1);
+    const subArgs = stripRuntimeFlags(args.slice(args.indexOf("agent") + 1));
     const sub = subArgs[0];
-    if (!sub || sub === "help" || sub === "--help") {
-      const { runAgentCommand } = await import("./agent");
-      // biome-ignore lint/suspicious/noExplicitAny: harmless help-only stub
-      await runAgentCommand({ convex: {} as any, args: subArgs });
-      return;
-    }
-    // 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(
-        runtime,
-        `dench agent ${sub}`,
+    if (
+      !sub ||
+      sub === "help" ||
+      subArgs.includes("--help") ||
+      subArgs.includes("-h")
+    ) {
+      console.log(
+        "Use dench chat new, send, follow, or tree. agent new/send/follow remain compatibility aliases. In Harness A, use spawn_task/read_task for child tasks.",
       );
-      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({
-      convex: runtime.client,
-      args: subArgs,
-      sessionToken: runtime.sessionToken,
-      callerRunId: process.env.DENCH_RUN_ID?.trim() || undefined,
+    if (sub !== "new" && sub !== "send" && sub !== "follow")
+      throw new CliError(
+        "Unsupported agent command. Use dench chat new/send/follow/tree or the harness subagent tools.",
+        { code: "unsupported_capability", retryable: false },
+      );
+    const { runChatSpawnCommand } = await import("./chat-spawn");
+    const runtime = requireAuthenticatedRuntime(
+      await getRuntime(),
+      `dench chat ${sub}`,
+    );
+    await runChatSpawnCommand({
+      runtime: { host: runtime.host, bearerToken: runtime.sessionToken },
+      args: subArgs.slice(1),
+      subcommand: sub,
     });
     return;
   }
@@ -5110,7 +5343,7 @@ async function main() {
   // `dench cron`. Same dispatch, same auth, same handler — only the
   // top-level command name differs to match the workspace UI rename.
   if (command === "cron" || command === "routine" || command === "routines") {
-    const subArgs = args.slice(args.indexOf(command) + 1);
+    const subArgs = stripRuntimeFlags(args.slice(args.indexOf(command) + 1));
     const sub = subArgs[0];
     // Help is a no-auth path so users can read the surface without a
     // session — mirrors `dench crm help`.
@@ -5144,7 +5377,7 @@ async function main() {
   // ── OpenClaw-parity self-update CLI surface ──────────────────────────
   //
   // Dispatch all `dench identity / organisation / user / tools / mem /
-  // bootstrap / model / daily` traffic through the shared
+  // bootstrap / model` traffic through the shared
   // agent-config CLI module. Each command requires the same auth shape
   // as `dench cron` (Bearer DENCH_API_KEY or `dench signin` session
   // token) so server-side `requireCronAccess` accepts both.
@@ -5156,10 +5389,9 @@ async function main() {
     "mem",
     "bootstrap",
     "model",
-    "daily",
   ]);
   if (AGENT_CONFIG_COMMANDS.has(command)) {
-    const subArgs = args.slice(args.indexOf(command) + 1);
+    const subArgs = stripRuntimeFlags(args.slice(args.indexOf(command) + 1));
     if (
       subArgs[0] === "help" ||
       subArgs.includes("--help") ||
@@ -5209,10 +5441,6 @@ async function main() {
       await mod.runModelCommand(ctxBase);
       return;
     }
-    if (command === "daily") {
-      await mod.runDailyCommand(ctxBase);
-      return;
-    }
   }
 
   if (command === "signin") {
@@ -5260,7 +5488,7 @@ async function main() {
     return;
   }
 
-  if (command === "context" && args.includes("--sections")) {
+  if (command === "context" && runtimeArgs.includes("--sections")) {
     const raw = args[args.indexOf("--sections") + 1];
     const sections = raw
       ?.split(",")
@@ -5298,7 +5526,7 @@ async function main() {
     return;
   }
 
-  if (command === "context" && args.includes("--instructions")) {
+  if (command === "context" && runtimeArgs.includes("--instructions")) {
     const instructions = await buildWorkspaceInstructionsContext(runtime);
     print(
       json ? instructions : (stringField(instructions, "instructions") ?? ""),