@dench.com/cli 2.3.0 → 2.3.2

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/dench.ts

@@ -163,6 +163,14 @@ const api = {
         "functions/agentWorkspace:whatCanIDoHere",
       ),
     },
+    agentConfig: {
+      workspaceInstructions: makeFunctionReference<"query">(
+        "functions/agentConfig:workspaceInstructions",
+      ),
+      devWorkspaceInstructions: makeFunctionReference<"query">(
+        "functions/agentConfig:devWorkspaceInstructions",
+      ),
+    },
     files: {
       listTree: makeFunctionReference<"query">("functions/files:listTree"),
       deleteFile: makeFunctionReference<"mutation">(
@@ -450,7 +458,8 @@ Usage:
   dench use <session-key-or-workspace-slug> [--host <host>] [--json]
   dench logout [session-key-or-workspace-slug] [--session <key-or-scope>] [--host <host>] [--all] [--json]
   dench backend [show|set|clear] [<production|staging|local|<url>>] [--json]
-  dench context [--json]
+  dench context [--instructions] [--json]
+  dench instructions [--json]
   dench status [--mine|--self] [--json]
   dench memory search "query" [--limit 8] [--json]
   dench memory save <key> "text" [--kind fact|decision|preference|goal|tool_note|other] [--tags a,b] [--sensitivity normal|broad|sensitive] [--scope user|org] [--json]
@@ -501,7 +510,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>
@@ -682,10 +691,14 @@ function contextHelp() {
   console.log(`Dench context
 
 Usage:
-  dench context [--json]
+  dench context [--instructions] [--json]
+  dench instructions [--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.
 `);
 }
 
@@ -2900,6 +2913,24 @@ function formatContext(context: JsonRecord) {
   return lines.join("\n");
 }
 
+async function buildWorkspaceInstructionsContext(
+  runtime: Awaited<ReturnType<typeof getRuntime>>,
+) {
+  if (runtime.mode === "dev") {
+    return (await runtime.client.query(
+      api.functions.agentConfig.devWorkspaceInstructions,
+      runtime.workspaceArgs,
+    )) as JsonRecord;
+  }
+  if (runtime.mode !== "session" && runtime.mode !== "apiKey") {
+    throw loginRequiredError("dench context --instructions");
+  }
+  return (await runtime.client.query(
+    api.functions.agentConfig.workspaceInstructions,
+    { sessionToken: runtime.sessionToken },
+  )) as JsonRecord;
+}
+
 async function devOverview(runtime: Awaited<ReturnType<typeof getRuntime>>) {
   if (runtime.mode !== "dev") {
     throw new Error("Not in dev mode");
@@ -4053,11 +4084,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;
@@ -4347,6 +4386,22 @@ async function main() {
     return;
   }
 
+  if (command === "context" && args.includes("--instructions")) {
+    const instructions = await buildWorkspaceInstructionsContext(runtime);
+    print(
+      json ? instructions : (stringField(instructions, "instructions") ?? ""),
+    );
+    return;
+  }
+
+  if (command === "instructions") {
+    const instructions = await buildWorkspaceInstructionsContext(runtime);
+    print(
+      json ? instructions : (stringField(instructions, "instructions") ?? ""),
+    );
+    return;
+  }
+
   if (command === "context") {
     const context = await buildContext(runtime);
     print(json ? context : formatContext(context));

package/lib/api-schemas.ts

@@ -340,6 +340,18 @@ const workspaceStatusPayload = z
     "Workspace orientation payload shared by /context, /status, /agents, and /approvals.",
   );
 
+const workspaceInstructionsResponse = z.object({
+  instructions: z
+    .string()
+    .describe(
+      "Markdown standing instructions for external agents connected to this workspace.",
+    ),
+  workspace: z.object({
+    name: z.string(),
+    slug: z.string().optional(),
+  }),
+});
+
 const memoryDoc = z
   .object({
     _id: z.string(),
@@ -1183,6 +1195,7 @@ export const requestSchemas: Record<string, ZodTypeAny> = {
 
   // Workspace
   "workspace.context": noInput,
+  "workspace.instructions": noInput,
   "workspace.status": noInput,
   "workspace.agents": noInput,
   "workspace.approvals.list": noInput,
@@ -1909,6 +1922,7 @@ export const responseSchemas: Record<string, ZodTypeAny> = {
 
   // Workspace orientation
   "workspace.context": workspaceStatusPayload,
+  "workspace.instructions": workspaceInstructionsResponse,
   "workspace.status": workspaceStatusPayload,
   "workspace.agents": workspaceStatusPayload,
   "workspace.approvals.list": workspaceStatusPayload,
@@ -2532,6 +2546,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 +2724,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: [
       {
@@ -2742,6 +2771,11 @@ export const responseExamples: Record<string, unknown> = {
     },
   },
   "workspace.context": workspaceStatusExample,
+  "workspace.instructions": {
+    workspace: { name: "Acme", slug: "acme" },
+    instructions:
+      "# Dench Workspace Instructions\n\nWorkspace: Acme (acme)\n\n## Identity\nYou are Dench...",
+  },
   "workspace.status": workspaceStatusExample,
   "workspace.agents": workspaceStatusExample,
   "workspace.approvals.list": workspaceStatusExample,

package/lib/command-registry.ts

@@ -34,6 +34,7 @@ export type CustomOperation = {
     | "upgrade"
     | "filesMove"
     | "filesStage"
+    | "browserAction"
     | "signinOtpStart"
     | "signinOtpVerify"
     | "signinOtpFinalize";
@@ -244,6 +245,18 @@ const rawApiOperations = [
     responseSchema: anyResponse,
     backend: convex("query", "functions/agentWorkspace:whatCanIDoHere"),
   }),
+  op({
+    id: "workspace.instructions",
+    group: "workspace",
+    summary:
+      "Return the current workspace's standing instructions for external agents.",
+    cli: "dench context --instructions",
+    method: "GET",
+    path: "/context/instructions",
+    requestSchema: noBody,
+    responseSchema: anyResponse,
+    backend: convex("query", "functions/agentConfig:workspaceInstructions"),
+  }),
   op({
     id: "workspace.status",
     group: "workspace",
@@ -1963,6 +1976,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.3.0",
+  "version": "2.3.2",
   "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": {