@dench.com/cli 2.2.7 → 2.3.1

package/browser.ts

@@ -1,9 +1,8 @@
 /**
- * `dench browser` — CLI control for the cloud Browserbase browser.
+ * `dench browser` — CLI control for Dench Browser.
  *
- * The CLI does not launch Chrome locally and never receives Browserbase
- * credentials. It sends a bearer-authenticated JSON command to
- * /api/browser/cli, where Dench Cloud drives Browserbase server-side.
+ * The CLI does not launch Chrome locally and never receives provider
+ * credentials. It sends bearer-authenticated JSON commands to Dench Cloud.
  */
 
 import { createHash } from "node:crypto";
@@ -15,6 +14,9 @@ import { hasFlag } from "./lib/cli-args";
 type RuntimeBundle = {
   host: string;
   bearerToken: string;
+  gatewayBaseUrl?: string;
+  gatewayBearerToken?: string;
+  gatewayHeaders?: Record<string, string>;
 };
 
 type BrowserCliContext = {
@@ -46,6 +48,15 @@ type BrowserResponse = Record<string, unknown> & {
   threadUrl?: string;
 };
 
+type DenchBrowserSessionResponse = {
+  provider?: string;
+  sessionId?: string;
+  connectUrl?: string;
+  liveViewUrl?: string;
+  status?: string;
+  contextId?: string;
+};
+
 class BrowserCliError extends Error {}
 
 const ACTIONS = new Set([
@@ -72,7 +83,7 @@ const ACTIONS = new Set([
 function browserHelp(): void {
   console.log(`Usage: dench browser <action> [options]
 
-Control the cloud Browserbase browser without opening dench.com locally.
+Control Dench Browser without opening dench.com locally.
 Commands authenticate with the active dench signin session or DENCH_API_KEY.
 
 Common:
@@ -95,6 +106,11 @@ Common:
   dench browser close-tab <targetId>
   dench browser stop
 
+Playwright sessions:
+  dench browser session create --json
+  dench browser session status <sessionId> --json
+  dench browser session stop <sessionId> --json
+
 State:
   The CLI remembers the latest browser thread per Dench host/session.
   Use --thread <threadId> to control a specific thread, or
@@ -213,10 +229,54 @@ function buildCliBrowserUrl(host: string): string {
   return `${host.replace(/\/+$/, "")}/api/browser/cli`;
 }
 
+function normalizeGatewayBaseUrl(value: string | undefined): string {
+  const explicit = value?.trim();
+  if (explicit) return explicit.replace(/\/+$/, "").replace(/\/v1$/, "");
+  if ("DENCH_GATEWAY_URL" in process.env || "GATEWAY_URL" in process.env) {
+    const env =
+      process.env.DENCH_GATEWAY_URL?.trim() || process.env.GATEWAY_URL?.trim();
+    if (env) return env.replace(/\/+$/, "").replace(/\/v1$/, "");
+    throw new BrowserCliError(
+      "DENCH_GATEWAY_URL is set but empty — configure a gateway URL or unset the variable",
+    );
+  }
+  if (/localhost|127\.0\.0\.1/.test(process.env.DENCH_HOST ?? "")) {
+    return "http://localhost:8787";
+  }
+  return "https://gateway.merseoriginals.com";
+}
+
+function buildGatewayBrowserUrl(
+  runtime: RuntimeBundle,
+  path = "/v1/browser/sessions",
+): string {
+  return `${normalizeGatewayBaseUrl(runtime.gatewayBaseUrl)}${path}`;
+}
+
+function buildRegisterSessionUrl(runtime: RuntimeBundle): string {
+  const convex = (
+    process.env.CONVEX_URL ||
+    process.env.NEXT_PUBLIC_CONVEX_URL ||
+    ""
+  ).trim();
+  if (convex) {
+    const siteBase = convex
+      .replace(/\/+$/, "")
+      .replace(/\.convex\.cloud$/i, ".convex.site");
+    return `${siteBase}/api/browser/register-session`;
+  }
+  const apiBase =
+    process.env.DENCH_API_URL?.trim() ||
+    process.env.DENCH_HOST?.trim() ||
+    runtime.host;
+  return `${apiBase.replace(/\/+$/, "")}/api/browser/register-session`;
+}
+
 async function postJson(
   url: string,
   bearer: string,
   body: unknown,
+  extraHeaders: Record<string, string> = {},
 ): Promise<{ ok: boolean; payload: unknown; status: number }> {
   const response = await fetch(url, {
     method: "POST",
@@ -224,6 +284,7 @@ async function postJson(
       accept: "application/json",
       authorization: `Bearer ${bearer}`,
       "content-type": "application/json",
+      ...extraHeaders,
     },
     body: JSON.stringify(body),
   });
@@ -237,14 +298,223 @@ async function postJson(
   return { ok: response.ok, payload, status: response.status };
 }
 
+async function getJson(
+  url: string,
+  bearer: string,
+  extraHeaders: Record<string, string> = {},
+): Promise<{ ok: boolean; payload: unknown; status: number }> {
+  const response = await fetch(url, {
+    method: "GET",
+    headers: {
+      accept: "application/json",
+      authorization: `Bearer ${bearer}`,
+      ...extraHeaders,
+    },
+  });
+  const text = await response.text();
+  let payload: unknown;
+  try {
+    payload = text ? JSON.parse(text) : null;
+  } catch {
+    payload = { raw: text };
+  }
+  return { ok: response.ok, payload, status: response.status };
+}
+
+async function deleteJson(
+  url: string,
+  bearer: string,
+  extraHeaders: Record<string, string> = {},
+): Promise<{ ok: boolean; payload: unknown; status: number }> {
+  const response = await fetch(url, {
+    method: "DELETE",
+    headers: {
+      accept: "application/json",
+      authorization: `Bearer ${bearer}`,
+      ...extraHeaders,
+    },
+  });
+  const text = await response.text();
+  let payload: unknown;
+  try {
+    payload = text ? JSON.parse(text) : null;
+  } catch {
+    payload = { raw: text };
+  }
+  return { ok: response.ok, payload, status: response.status };
+}
+
 function payloadError(payload: unknown): string {
   if (payload && typeof payload === "object" && !Array.isArray(payload)) {
     const error = (payload as { error?: unknown }).error;
     if (typeof error === "string" && error.trim()) return error;
+    if (error && typeof error === "object" && !Array.isArray(error)) {
+      const message = (error as { message?: unknown }).message;
+      if (typeof message === "string" && message.trim()) return message;
+    }
   }
   return "Cloud browser request failed";
 }
 
+function gatewayBearerToken(runtime: RuntimeBundle): string {
+  return runtime.gatewayBearerToken?.trim() || runtime.bearerToken;
+}
+
+function gatewayBrowserHeaders(runtime: RuntimeBundle): Record<string, string> {
+  const runId = process.env.DENCH_RUN_ID?.trim();
+  return {
+    ...(runtime.gatewayHeaders ?? {}),
+    ...(runId ? { "x-dench-run-id": runId } : {}),
+  };
+}
+
+async function registerScriptSession(args: {
+  runtime: RuntimeBundle;
+  session: DenchBrowserSessionResponse;
+  status: string;
+}): Promise<void> {
+  const runId = process.env.DENCH_RUN_ID?.trim();
+  const sessionId = args.session.sessionId?.trim();
+  if (!runId || !sessionId) return;
+  try {
+    await postJson(
+      buildRegisterSessionUrl(args.runtime),
+      args.runtime.bearerToken,
+      {
+        runId,
+        sessionId,
+        liveViewUrl: args.session.liveViewUrl,
+        status: args.status,
+      },
+    );
+  } catch {
+    // Best-effort: browser automation must not fail because UI registration
+    // could not link the session to the run.
+  }
+}
+
+function parseSessionCreateBody(args: string[]): Record<string, unknown> {
+  // The per-user browser profile is resolved server-side by the gateway
+  // from the authenticated Dench API key plus DENCH_RUN_ID when present
+  // (Convex `browserIdentities`).
+  // `--context-id` stays only as an explicit override for manual testing;
+  // there is no env-var fallback.
+  const contextId =
+    consumeFlagValue(args, "--context-id") ||
+    consumeFlagValue(args, "--contextId") ||
+    "";
+  const width = parseNumberFlag(args, "--width");
+  const height = parseNumberFlag(args, "--height");
+  return {
+    ...(contextId ? { contextId } : {}),
+    ...(width || height
+      ? {
+          viewport: {
+            ...(width ? { width } : {}),
+            ...(height ? { height } : {}),
+          },
+        }
+      : {}),
+  };
+}
+
+async function runSessionCommand(ctx: BrowserCliContext): Promise<void> {
+  ctx.args.shift(); // session
+  const subcommand = ctx.args.shift() ?? "create";
+  const bearerToken = gatewayBearerToken(ctx.runtime);
+  const gatewayHeaders = gatewayBrowserHeaders(ctx.runtime);
+
+  if (subcommand === "create") {
+    const body = parseSessionCreateBody(ctx.args);
+    const result = await postJson(
+      buildGatewayBrowserUrl(ctx.runtime),
+      bearerToken,
+      body,
+      gatewayHeaders,
+    );
+    if (!result.ok) {
+      throw new BrowserCliError(
+        `${payloadError(result.payload)} (${result.status})`,
+      );
+    }
+    const session =
+      result.payload && typeof result.payload === "object"
+        ? (result.payload as DenchBrowserSessionResponse)
+        : {};
+    await registerScriptSession({
+      runtime: ctx.runtime,
+      session,
+      status: session.status ?? "live",
+    });
+    output(
+      ctx,
+      ctx.jsonOutput ? session : `Browser session ${session.sessionId}`,
+    );
+    return;
+  }
+
+  if (subcommand === "status") {
+    const sessionId = ctx.args[0]?.trim();
+    if (!sessionId) {
+      throw new BrowserCliError(
+        "dench browser session status requires a session id",
+      );
+    }
+    const result = await getJson(
+      buildGatewayBrowserUrl(
+        ctx.runtime,
+        `/v1/browser/sessions/${encodeURIComponent(sessionId)}`,
+      ),
+      bearerToken,
+      gatewayHeaders,
+    );
+    if (!result.ok) {
+      throw new BrowserCliError(
+        `${payloadError(result.payload)} (${result.status})`,
+      );
+    }
+    output(
+      ctx,
+      ctx.jsonOutput ? result.payload : JSON.stringify(result.payload, null, 2),
+    );
+    return;
+  }
+
+  if (subcommand === "stop") {
+    const sessionId = ctx.args[0]?.trim();
+    if (!sessionId) {
+      throw new BrowserCliError(
+        "dench browser session stop requires a session id",
+      );
+    }
+    const result = await deleteJson(
+      buildGatewayBrowserUrl(
+        ctx.runtime,
+        `/v1/browser/sessions/${encodeURIComponent(sessionId)}`,
+      ),
+      bearerToken,
+      gatewayHeaders,
+    );
+    if (!result.ok) {
+      throw new BrowserCliError(
+        `${payloadError(result.payload)} (${result.status})`,
+      );
+    }
+    await registerScriptSession({
+      runtime: ctx.runtime,
+      session: { sessionId },
+      status: "ended",
+    });
+    output(
+      ctx,
+      ctx.jsonOutput ? result.payload : `Stopped browser session ${sessionId}`,
+    );
+    return;
+  }
+
+  throw new BrowserCliError(`Unknown browser session command: ${subcommand}`);
+}
+
 async function maybeWriteScreenshot(
   response: BrowserResponse,
   outputPath: string | undefined,
@@ -459,6 +729,11 @@ export async function runBrowserCommand(opts: {
     return;
   }
 
+  if (first === "session") {
+    await runSessionCommand(ctx);
+    return;
+  }
+
   const { body, outputPath } = parseActionAndBody(ctx);
   if (!body.threadId) {
     body.threadId = await readRememberedThreadId(opts.runtime);

package/cron.ts

@@ -34,10 +34,15 @@
  *   disable <jobId>                      Soft-pause without delete.
  *   run <jobId> [--wait]                 Manual fire; --wait blocks.
  *   secret <jobId>                       Mint/rotate a signing secret (any type).
+ *   events <toolkit>                     List a connected app's event types.
  *   runs <jobId> [--limit N] [--status]  Run history per trigger.
  *   history [--limit N]                  Flat history across all crons.
  *   help                                 Print this help.
  *
+ * Trigger types accepted by `create --type`:
+ *   schedule (default) | webhook | composio (app event) | crm (CRM event).
+ *   composio/crm POST to /api/cron/jobs; the others use the Convex mutation.
+ *
  * Schedule flags accepted by `create` and `update`:
  *   --every <duration>   30s | 5m | 2h | 1d | 12h…
  *   --every-ms <number>  Same, raw milliseconds.
@@ -139,6 +144,28 @@ async function postJson(
   return json;
 }
 
+async function getJson(
+  url: string,
+  headers: Record<string, string>,
+): Promise<unknown> {
+  const response = await fetch(url, { method: "GET", headers });
+  const text = await response.text();
+  let json: unknown;
+  try {
+    json = text ? JSON.parse(text) : null;
+  } catch {
+    json = { raw: text };
+  }
+  if (!response.ok) {
+    const detail =
+      json && typeof json === "object" && "error" in json
+        ? String((json as Record<string, unknown>).error)
+        : JSON.stringify(json);
+    throw new CronCliError(`${url} failed (${response.status}): ${detail}`);
+  }
+  return json;
+}
+
 async function callQuery(
   ctx: CronCliContext,
   fn: Parameters<ConvexHttpClient["query"]>[0],
@@ -367,12 +394,32 @@ async function runCreate(ctx: CronCliContext): Promise<void> {
   }
   const triggerType = (getFlag(ctx.args, "--type") ?? "schedule") as
     | "schedule"
-    | "webhook";
-  if (triggerType !== "schedule" && triggerType !== "webhook") {
+    | "webhook"
+    | "composio"
+    | "crm";
+  if (!["schedule", "webhook", "composio", "crm"].includes(triggerType)) {
     throw new CronCliError(
-      `--type must be schedule|webhook (got "${triggerType}"). app-event / CRM automations are created from the dashboard.`,
+      `--type must be schedule|webhook|composio|crm (got "${triggerType}").`,
     );
   }
+
+  // App-event (composio) and CRM-event automations are created through the
+  // REST `/api/cron/jobs` POST: composio needs the upstream subscribe +
+  // connection-ownership flow (Node runtime, project Composio key), and CRM
+  // rides the same path for one create surface. schedule + webhook keep the
+  // direct Convex mutation below.
+  if (triggerType === "composio" || triggerType === "crm") {
+    return await runCreateAppOrCrm(ctx, {
+      triggerType,
+      name,
+      prompt,
+      description,
+      overlapPolicy,
+      disabled,
+      deleteAfterRun,
+      target,
+    });
+  }
   const isWebhook = triggerType === "webhook";
 
   let schedule: CronScheduleSpec | undefined;
@@ -447,6 +494,185 @@ async function runSecret(ctx: CronCliContext): Promise<void> {
   });
 }
 
+export type AppOrCrmCreateBase = {
+  triggerType: "composio" | "crm";
+  name: string;
+  prompt: string;
+  description?: string;
+  overlapPolicy?: "skip" | "queue" | "kill_old";
+  disabled: boolean;
+  deleteAfterRun: boolean;
+  target?: "chat_turn";
+};
+
+/**
+ * Build the `/api/cron/jobs` POST body for an app-event (composio) or
+ * CRM-event automation from the create flags. Pure (no network) so the flag
+ * parsing + validation + payload shape can be unit-tested directly. Consumes
+ * the type-specific flags off `args` (composio: --connection/--event/--toolkit/
+ * --trigger-config; crm: --object/--event/--where/--where-logic) and throws a
+ * `CronCliError` with discovery hints when a required input is missing.
+ */
+export function buildAppOrCrmCreateBody(
+  args: string[],
+  base: AppOrCrmCreateBase,
+): Record<string, unknown> {
+  // Neither type takes a schedule — reject one early instead of silently
+  // dropping it server-side.
+  if (consumeScheduleFlags(args)) {
+    throw new CronCliError(
+      `${base.triggerType} automations don't take a schedule. Omit --every/--cron/--at.`,
+    );
+  }
+
+  const body: Record<string, unknown> = {
+    name: base.name,
+    prompt: base.prompt,
+    triggerType: base.triggerType,
+    description: base.description,
+    overlapPolicy: base.overlapPolicy,
+    enabled: base.disabled ? false : undefined,
+    deleteAfterRun: base.deleteAfterRun ? true : undefined,
+    target: base.target,
+  };
+
+  if (base.triggerType === "composio") {
+    const connection = getFlag(args, "--connection");
+    const event = getFlag(args, "--event");
+    if (!connection?.trim() || !event?.trim()) {
+      throw new CronCliError(
+        "app-event automations need --connection <connectedAccountId> and --event <triggerSlug>.\n" +
+          "  Discover apps:   dench apps --json              (use connectedAccountId + toolkit)\n" +
+          "  Discover events: dench cron events <toolkit>    (use the event slug)\n" +
+          "Example:\n" +
+          '  dench cron create "New GitHub star" --prompt "Thank the new stargazer" \\\n' +
+          "    --type composio --connection ca_123 --event GITHUB_STAR_ADDED_EVENT --toolkit github",
+      );
+    }
+    const toolkit = getFlag(args, "--toolkit");
+    const triggerConfigRaw = getFlag(args, "--trigger-config");
+    let triggerConfig: unknown;
+    if (triggerConfigRaw) {
+      try {
+        triggerConfig = JSON.parse(triggerConfigRaw);
+      } catch {
+        throw new CronCliError(
+          `--trigger-config must be valid JSON (got ${triggerConfigRaw})`,
+        );
+      }
+    }
+    body.composioConnectionId = connection.trim();
+    body.composioTriggerSlug = event.trim();
+    if (toolkit?.trim()) body.composioToolkitSlug = toolkit.trim();
+    if (triggerConfig !== undefined) body.triggerConfig = triggerConfig;
+  } else {
+    const object = getFlag(args, "--object");
+    const event = getFlag(args, "--event");
+    if (!object?.trim() || !event?.trim()) {
+      throw new CronCliError(
+        "CRM-event automations need --object <objectId> and --event create|update|delete.\n" +
+          "  Discover objects: dench crm objects list\n" +
+          "  Discover fields:  dench crm fields list <object>   (filter on field _id via --where)\n" +
+          "Example:\n" +
+          '  dench cron create "New company" --prompt "Research the new company" \\\n' +
+          "    --type crm --object <objectId> --event create",
+      );
+    }
+    if (!["create", "update", "delete"].includes(event)) {
+      throw new CronCliError(
+        `--event must be create|update|delete for CRM automations (got "${event}")`,
+      );
+    }
+    const whereRaw = getFlag(args, "--where");
+    const whereLogic = (getFlag(args, "--where-logic") ?? "AND") as
+      | "AND"
+      | "OR";
+    if (!["AND", "OR"].includes(whereLogic)) {
+      throw new CronCliError(
+        `--where-logic must be AND|OR (got "${whereLogic}")`,
+      );
+    }
+    const crmTriggerConfig: Record<string, unknown> = {
+      eventType: event,
+      objectId: object.trim(),
+    };
+    if (whereRaw) {
+      let whereGroups: unknown;
+      try {
+        whereGroups = JSON.parse(whereRaw);
+      } catch {
+        throw new CronCliError(
+          "--where must be valid JSON: an array of groups like " +
+            '\'[{"logic":"AND","conditions":[{"fieldId":"<id>","operator":"equals","value":"x"}]}]\'',
+        );
+      }
+      if (!Array.isArray(whereGroups)) {
+        throw new CronCliError(
+          "--where must be a JSON array of where-groups (each { logic, conditions }).",
+        );
+      }
+      crmTriggerConfig.whereGroups = whereGroups;
+      crmTriggerConfig.whereLogic = whereLogic;
+    }
+    body.crmTriggerConfig = crmTriggerConfig;
+  }
+
+  return body;
+}
+
+/**
+ * Create an app-event (composio) or CRM-event automation via the REST
+ * `/api/cron/jobs` POST. composio creation also subscribes the trigger
+ * instance upstream + verifies the org owns the connection (handled
+ * server-side in the Node route); CRM creation validates the object +
+ * filter field ids in the mutation.
+ */
+async function runCreateAppOrCrm(
+  ctx: CronCliContext,
+  base: AppOrCrmCreateBase,
+): Promise<void> {
+  const body = buildAppOrCrmCreateBody(ctx.args, base);
+  const url = `${getApiBase()}/api/cron/jobs`;
+  const created = await postJson(
+    url,
+    apiKeyHeaders(ctx.sessionToken ?? ""),
+    body,
+  );
+  out(ctx, created);
+}
+
+/**
+ * List the app-event types a connected app publishes, so the caller can pick
+ * a `--event <triggerSlug>` for `dench cron create --type composio`. Backed by
+ * `GET /api/cron/trigger-types` (project-level Composio catalogue).
+ */
+async function runEvents(ctx: CronCliContext): Promise<void> {
+  const toolkit = shift(
+    ctx.args,
+    "toolkit slug (e.g. github — run `dench apps --json` to see each app's slug)",
+  );
+  const url = `${getApiBase()}/api/cron/trigger-types?toolkit=${encodeURIComponent(toolkit)}`;
+  const result = (await getJson(
+    url,
+    apiKeyHeaders(ctx.sessionToken ?? ""),
+  )) as {
+    items?: Array<{ slug?: string; name?: string; description?: string }>;
+  };
+  if (ctx.jsonOutput) {
+    out(ctx, result);
+    return;
+  }
+  const items = result.items ?? [];
+  if (items.length === 0) {
+    console.log(`(no app events found for "${toolkit}")`);
+    return;
+  }
+  for (const item of items) {
+    console.log(`${item.slug ?? "?"}  —  ${item.name ?? ""}`);
+    if (item.description) console.log(`    ${item.description}`);
+  }
+}
+
 async function runUpdate(ctx: CronCliContext): Promise<void> {
   const jobId = shift(ctx.args, "job id");
   const name = getFlag(ctx.args, "--name");
@@ -578,11 +804,12 @@ Browse:
   dench cron get <jobId> [--json]
   dench cron history [--limit 50] [--status ok|error|skipped] [--json]
   dench cron runs <jobId> [--limit 50] [--status ok|error|skipped] [--json]
+  dench cron events <toolkit> [--json]            # app-event types for a connected app
 
 Create / update:
   dench cron create "Daily standup digest" \\
       --prompt "Pull yesterday's commits + Slack #standup msgs and post a summary…" \\
-      --type schedule                     # default; or --type webhook (no schedule)
+      --type schedule                     # default. also: webhook | composio | crm (see below)
       --every 1d                          # or --cron "0 9 * * 1-5"  or --at 2026-05-04T09:00:00Z
       [--description "..."]               # human-readable note shown in dashboard / list
       [--overlap skip|queue|kill_old]     # default: skip
@@ -595,6 +822,21 @@ Create / update:
   # signing secret unless --no-secret. The secret is shown ONCE.
   dench cron create "Inbound lead triage" --prompt "Triage the lead…" --type webhook
 
+  # App-event automation (fires when something happens in a connected app).
+  #   1. dench apps --json                    → connectedAccountId + toolkit
+  #   2. dench cron events <toolkit>          → event slug
+  dench cron create "New GitHub star" --prompt "Thank the new stargazer" \\
+      --type composio --connection <connectedAccountId> --event <triggerSlug> \\
+      [--toolkit <slug>] [--trigger-config '<json>']
+
+  # CRM-event automation (fires on a CRM object create/update/delete).
+  #   1. dench crm objects list               → objectId
+  #   2. dench crm fields list <object>       → field _id (for --where filters)
+  dench cron create "New company added" --prompt "Research the new company" \\
+      --type crm --object <objectId> --event create|update|delete \\
+      [--where '[{"logic":"AND","conditions":[{"fieldId":"<id>","operator":"equals","value":"x"}]}]'] \\
+      [--where-logic AND|OR]
+
   dench cron update <jobId> [--name N] [--prompt P] [--description D] \\
       [--every X | --cron EXPR | --at ISO] [--enabled true|false] [--overlap …]
 
@@ -676,6 +918,8 @@ export async function runCronCommand(opts: {
       return await runRunNow(ctx);
     case "secret":
       return await runSecret(ctx);
+    case "events":
+      return await runEvents(ctx);
     case "runs":
       return await runRuns(ctx);
     case "history":

package/dench.ts

@@ -501,7 +501,7 @@ Live web search (Exa via the Dench Gateway, auths with the active \`dench signin
   dench search answer "<query>" [--json]
   Help: dench search help
 
-Cloud browser (Browserbase, runs entirely in Dench Cloud):
+Cloud browser (runs entirely in Dench Cloud):
   dench browser open [url] [--json]
   dench browser inspect [--json]
   dench browser navigate <url>
@@ -4053,11 +4053,19 @@ async function main() {
     const { runBrowserCommand } = await import("./browser");
     const runtime = await getRuntime();
     const authedRuntime = requireAuthenticatedRuntime(runtime, "dench browser");
+    const filteredSubArgs = subArgs.filter((a) => a !== "--json");
+    const gatewayAuth =
+      filteredSubArgs[0] === "session"
+        ? await resolveGatewayCommandAuth(runtime, "dench browser session")
+        : undefined;
     await runBrowserCommand({
       args: subArgs,
       runtime: {
         host: authedRuntime.host,
         bearerToken: authedRuntime.sessionToken,
+        gatewayBearerToken: gatewayAuth?.bearerToken,
+        gatewayBaseUrl: gatewayAuth?.gatewayBaseUrl,
+        gatewayHeaders: gatewayAuth?.gatewayHeaders,
       },
     });
     return;

package/lib/api-schemas.ts

@@ -2532,6 +2532,13 @@ export const convexExtras: Record<string, ConvexExtras> = {
 // ---------------------------------------------------------------------------
 
 export const requestExamples: Record<string, unknown> = {
+  "browser.action": {
+    action: "open",
+    url: "https://example.com",
+  },
+  "browser.session.create": {
+    viewport: { width: 1280, height: 800 },
+  },
   "crm.objects.create": {
     name: "lead",
     description: "Sales leads",
@@ -2703,6 +2710,14 @@ const workspaceStatusExample = {
 };
 
 export const responseExamples: Record<string, unknown> = {
+  "browser.session.create": {
+    provider: "dench_browser",
+    sessionId: "bb_sess_123",
+    connectUrl:
+      "wss://gateway.merseoriginals.com/v1/browser/sessions/bb_sess_123/cdp?relay_token=...",
+    liveViewUrl: "https://www.dench.com/dench?...",
+    status: "live",
+  },
   "commands.list": {
     operations: [
       {

package/lib/command-registry.ts

@@ -34,6 +34,7 @@ export type CustomOperation = {
     | "upgrade"
     | "filesMove"
     | "filesStage"
+    | "browserAction"
     | "signinOtpStart"
     | "signinOtpVerify"
     | "signinOtpFinalize";
@@ -1963,6 +1964,57 @@ const rawApiOperations = [
     backend: gateway("DELETE", "/composio/connections/{connectionId}"),
   }),
 
+  // Browser automation (Dench Browser). The provider stays server-side; the
+  // per-(org,user) browser profile is resolved by the gateway, so callers never
+  // see or send provider credentials or context ids.
+  op({
+    id: "browser.action",
+    group: "browser",
+    summary:
+      "Drive Dench Browser with a single interactive action (open, inspect, click, fill, type, screenshot, stop). Pass the step in `action` plus its arguments.",
+    cli: "dench browser",
+    method: "POST",
+    path: "/browser/cli",
+    requestSchema: anyObject,
+    responseSchema: anyResponse,
+    backend: custom("browserAction", "bearer"),
+  }),
+  op({
+    id: "browser.session.create",
+    group: "browser",
+    summary:
+      "Create a Dench Browser session and return a CDP connect URL for Playwright (chromium.connectOverCDP) plus a live-view URL. Use for durable scripts run from the sandbox.",
+    cli: "dench browser session create",
+    method: "POST",
+    path: "/browser/sessions",
+    requestSchema: anyObject,
+    responseSchema: anyResponse,
+    backend: gateway("POST", "/browser/sessions"),
+  }),
+  op({
+    id: "browser.session.status",
+    group: "browser",
+    summary:
+      "Get the status, connect URL, and live-view URL for a Dench Browser session.",
+    cli: "dench browser session status",
+    method: "GET",
+    path: "/browser/sessions/{sessionId}",
+    requestSchema: anyObject,
+    responseSchema: anyResponse,
+    backend: gateway("GET", "/browser/sessions/{sessionId}"),
+  }),
+  op({
+    id: "browser.session.stop",
+    group: "browser",
+    summary: "Stop a Dench Browser session and release the remote browser.",
+    cli: "dench browser session stop",
+    method: "DELETE",
+    path: "/browser/sessions/{sessionId}",
+    requestSchema: anyObject,
+    responseSchema: anyResponse,
+    backend: gateway("DELETE", "/browser/sessions/{sessionId}"),
+  }),
+
   // Agent harness config.
   op({
     id: "agentConfig.identity.show",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dench.com/cli",
-  "version": "2.2.7",
+  "version": "2.3.1",
   "description": "Dench agent workspace CLI. v2 unifies auth behind `dench signin`; the legacy `dench login` / `dench onboard` / `dench setup` / `dench what-can-i-do` / `dench register` commands now error with a redirect.",
   "type": "module",
   "bin": {