@dench.com/cli 0.3.8 → 0.4.1

package/tools.ts

@@ -0,0 +1,808 @@
+/**
+ * `dench tool` and `dench apps` — direct Dench Cloud Gateway access for
+ * Composio's get-apps / get-tools / execute-tool surface.
+ *
+ * Mirrors `denchclaw`'s pattern: this CLI is a thin wrapper over five
+ * gateway endpoints, authenticated with the unified `DENCH_API_KEY`
+ * baked into every Dench sandbox at create time. There is no Convex
+ * session involved; that means these subcommands work in any
+ * environment that has the API key (sandboxes, CI, local dev with the
+ * key exported manually). The previous implementation forced
+ * `requireSessionRuntime` and routed through a Convex action, which
+ * broke `apiKey` runtime mode entirely.
+ *
+ * Subcommands:
+ *
+ *   dench apps [--json]                                            — list connected apps
+ *   dench tool status [toolkit?] [--json]                          — list connections (optionally narrowed)
+ *   dench tool search "<query>" [--toolkit <slug>] [--limit N] [--json]
+ *   dench tool run <slug> [--args <json>] [--account <id>] [--json]
+ *   dench tool connect <toolkit> [--callback-url <url>] [--json]   — print OAuth redirect URL
+ *   dench tool disconnect <connectionId> [--json]
+ *
+ * Endpoints used (all `Authorization: Bearer DENCH_API_KEY`):
+ *
+ *   GET    /v1/composio/connections
+ *   GET    /v1/composio/toolkits?search=<slug>
+ *   POST   /v1/composio/tools/search          { query, toolkit_slug?, limit? }
+ *   POST   /v1/composio/tools/execute         { tool_slug, arguments, connected_account_id? }
+ *   POST   /v1/composio/connect               { toolkit, callback_url }
+ *   DELETE /v1/composio/connections/<id>
+ *
+ * Output parity: this module preserves the JSON shape and human
+ * formatting that the previous Convex-routed implementation produced
+ * (compact ranked search, "Connect <toolkit> here: <url>", redacted
+ * run output) so any agent that already parses `dench tool ...` keeps
+ * working.
+ */
+
+import {
+  CliArgError,
+  getFlag,
+  hasFlag,
+  parseJson,
+  shift as shiftRaw,
+} from "./lib/cli-args";
+
+// ---------------------------------------------------------------------------
+// Public dispatcher
+// ---------------------------------------------------------------------------
+
+export type ToolCliContext = {
+  args: string[];
+  jsonOutput: boolean;
+};
+
+export async function runToolCommand(ctx: ToolCliContext): Promise<void> {
+  const sub = ctx.args[0];
+  if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
+    toolHelp();
+    return;
+  }
+  ctx.args.shift();
+
+  if (sub === "status") {
+    await runStatusSubcommand(ctx);
+    return;
+  }
+  if (sub === "search") {
+    await runSearchSubcommand(ctx);
+    return;
+  }
+  if (sub === "run") {
+    await runRunSubcommand(ctx);
+    return;
+  }
+  if (sub === "connect") {
+    await runConnectSubcommand(ctx);
+    return;
+  }
+  if (sub === "disconnect") {
+    await runDisconnectSubcommand(ctx);
+    return;
+  }
+
+  throw new ToolCliError(`Unknown dench tool subcommand: ${sub}`);
+}
+
+/**
+ * Summarise the user's connected apps for `dench context` and friends.
+ * Bypasses any Convex session and speaks straight to the gateway.
+ * Returns the same legacy shape the previous Convex-routed path did so
+ * existing parsers don't need to change.
+ */
+export async function fetchConnectedAppsSummary(): Promise<{
+  available: boolean;
+  count: number;
+  connections: Array<{
+    toolkit: string;
+    status: string;
+    connectedAccountId: string | null;
+    accountLabel: string | null;
+  }>;
+  error?: string;
+  reason?: string;
+}> {
+  let payload: unknown;
+  try {
+    payload = await callGateway("GET", "/v1/composio/connections");
+  } catch (error) {
+    if (error instanceof MissingApiKeyError) {
+      return {
+        available: false,
+        reason: error.message,
+        count: 0,
+        connections: [],
+      };
+    }
+    return {
+      available: false,
+      error: errorMessage(error),
+      count: 0,
+      connections: [],
+    };
+  }
+  const connections = extractConnections(payload).map(compactConnection);
+  return { available: true, count: connections.length, connections };
+}
+
+// ---------------------------------------------------------------------------
+// Subcommands
+// ---------------------------------------------------------------------------
+
+async function runStatusSubcommand(ctx: ToolCliContext): Promise<void> {
+  const filterToolkit = ctx.args[0]?.startsWith("--") ? undefined : ctx.args[0];
+  if (filterToolkit) ctx.args.shift();
+
+  const connectionsPayload = await callGateway(
+    "GET",
+    "/v1/composio/connections",
+  );
+  let toolkitsPayload: unknown = null;
+  if (filterToolkit) {
+    const search = encodeURIComponent(filterToolkit);
+    toolkitsPayload = await callGateway(
+      "GET",
+      `/v1/composio/toolkits?search=${search}`,
+    );
+  }
+
+  const allConnections = extractConnections(connectionsPayload);
+  const filteredConnections = filterToolkit
+    ? allConnections.filter((conn) => {
+        const slug = stringField(conn, "toolkit_slug", "toolkit") ?? "";
+        return slug.toLowerCase() === filterToolkit.toLowerCase();
+      })
+    : allConnections;
+
+  const summary = {
+    ok: true,
+    available: true,
+    toolkit: filterToolkit ?? null,
+    count: filteredConnections.length,
+    connections: filteredConnections.map(compactConnection),
+    ...(toolkitsPayload
+      ? { toolkit_info: extractToolkits(toolkitsPayload) }
+      : {}),
+  };
+
+  if (ctx.jsonOutput) {
+    console.log(JSON.stringify(summary, null, 2));
+    return;
+  }
+  console.log(formatStatusSummary(summary));
+}
+
+async function runSearchSubcommand(ctx: ToolCliContext): Promise<void> {
+  const toolkit = getFlag(ctx.args, "--toolkit");
+  const limitRaw = getFlag(ctx.args, "--limit");
+  const limit = limitRaw ? parsePositiveInt("--limit", limitRaw) : undefined;
+  const queryParts = ctx.args.slice();
+  ctx.args.length = 0;
+  const query = queryParts.join(" ").trim();
+  if (!query) {
+    throw new ToolCliError(
+      'Usage: dench tool search "<query>" [--toolkit <slug>] [--limit N] [--json]',
+    );
+  }
+
+  const body: Record<string, unknown> = { query };
+  if (toolkit) body.toolkit_slug = toolkit;
+  if (limit) body.limit = limit;
+
+  const payload = await callGateway("POST", "/v1/composio/tools/search", body);
+  if (ctx.jsonOutput) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  console.log(formatSearchResult(payload));
+}
+
+async function runRunSubcommand(ctx: ToolCliContext): Promise<void> {
+  const toolSlug = ctx.args[0];
+  if (!toolSlug || toolSlug.startsWith("--")) {
+    throw new ToolCliError(
+      'Usage: dench tool run <composio_tool_slug> [--args \'{"key":"value"}\'] [--account <connectedAccountId>] [--json]',
+    );
+  }
+  ctx.args.shift();
+  const argsJson = getFlag(ctx.args, "--args");
+  const account = getFlag(ctx.args, "--account");
+  const parsedArgs = (parseJson(argsJson) ?? {}) as Record<string, unknown>;
+  if (
+    parsedArgs &&
+    typeof parsedArgs === "object" &&
+    !Array.isArray(parsedArgs)
+  ) {
+    // ok
+  } else {
+    throw new ToolCliError("--args must be a JSON object");
+  }
+
+  const body: Record<string, unknown> = {
+    tool_slug: toolSlug,
+    arguments: parsedArgs,
+  };
+  if (account) body.connected_account_id = account;
+
+  let payload: unknown;
+  try {
+    payload = await callGateway("POST", "/v1/composio/tools/execute", body);
+  } catch (error) {
+    if (error instanceof GatewayHttpError && isLikelyNoConnection(error)) {
+      const noConnPayload = noConnectionPayload(toolSlug, error);
+      if (ctx.jsonOutput) {
+        console.log(JSON.stringify(noConnPayload, null, 2));
+      } else {
+        console.log(formatNoConnection(noConnPayload));
+      }
+      process.exitCode = 1;
+      return;
+    }
+    throw error;
+  }
+
+  if (ctx.jsonOutput) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  console.log(redactForDisplay(payload));
+}
+
+async function runConnectSubcommand(ctx: ToolCliContext): Promise<void> {
+  const toolkit = ctx.args[0];
+  if (!toolkit || toolkit.startsWith("--")) {
+    throw new ToolCliError(
+      "Usage: dench tool connect <toolkit> [--callback-url <url>] [--json]",
+    );
+  }
+  ctx.args.shift();
+  const callbackUrl =
+    getFlag(ctx.args, "--callback-url") ??
+    process.env.DENCH_OAUTH_CALLBACK_URL?.trim() ??
+    `${resolveAppPublicOrigin()}/api/composio/callback`;
+
+  const payload = await callGateway("POST", "/v1/composio/connect", {
+    toolkit,
+    callback_url: callbackUrl,
+  });
+
+  const record = asRecord(payload);
+  const redirectUrl =
+    stringField(record, "redirect_url", "redirectUrl", "url") ??
+    stringField(asRecord(record?.data), "redirect_url", "redirectUrl", "url");
+  const summary = {
+    ok: true,
+    toolkit,
+    callbackUrl,
+    redirectUrl: redirectUrl ?? null,
+    connectionId:
+      stringField(record, "connection_id", "connectionId") ??
+      stringField(asRecord(record?.data), "connection_id", "connectionId") ??
+      null,
+    ...(redirectUrl
+      ? { message: `Connect ${toolkit} here: ${redirectUrl}` }
+      : {}),
+    raw: payload,
+  };
+
+  if (ctx.jsonOutput) {
+    console.log(JSON.stringify(summary, null, 2));
+    return;
+  }
+  if (redirectUrl) {
+    console.log(`Connect ${toolkit} here: ${redirectUrl}`);
+    return;
+  }
+  console.log(JSON.stringify(payload, null, 2));
+}
+
+async function runDisconnectSubcommand(ctx: ToolCliContext): Promise<void> {
+  const connectionId = ctx.args[0];
+  if (!connectionId || connectionId.startsWith("--")) {
+    throw new ToolCliError(
+      "Usage: dench tool disconnect <connectionId> [--json]",
+    );
+  }
+  ctx.args.shift();
+
+  const path = `/v1/composio/connections/${encodeURIComponent(connectionId)}`;
+  let payload: unknown = { ok: true, deleted: true };
+  try {
+    payload = await callGateway("DELETE", path);
+  } catch (error) {
+    // Composio returns 404 for connections that are already gone — surface
+    // that as a soft success so callers can keep their local state in sync.
+    if (error instanceof GatewayHttpError && error.status === 404) {
+      payload = { ok: true, deleted: true, alreadyGone: true };
+    } else {
+      throw error;
+    }
+  }
+
+  if (ctx.jsonOutput) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  const record = asRecord(payload);
+  if (record?.alreadyGone) {
+    console.log(`Connection ${connectionId} was already disconnected.`);
+    return;
+  }
+  console.log(`Disconnected ${connectionId}.`);
+}
+
+// ---------------------------------------------------------------------------
+// HTTP plumbing
+// ---------------------------------------------------------------------------
+
+class ToolCliError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ToolCliError";
+  }
+}
+
+class MissingApiKeyError extends ToolCliError {
+  constructor() {
+    super(
+      "DENCH_API_KEY is not set. Inside a Dench sandbox it is baked into " +
+        "the env automatically; outside, export it manually or run " +
+        "`dench login` and copy the api-key from the output.",
+    );
+    this.name = "MissingApiKeyError";
+  }
+}
+
+class GatewayHttpError extends ToolCliError {
+  status: number;
+  body: string;
+  path: string;
+
+  constructor(args: { status: number; body: string; path: string }) {
+    const truncated =
+      args.body.length > 500 ? `${args.body.slice(0, 500)}…` : args.body;
+    super(
+      `Gateway ${args.path} returned ${args.status}: ${truncated || "(empty)"}`,
+    );
+    this.name = "GatewayHttpError";
+    this.status = args.status;
+    this.body = args.body;
+    this.path = args.path;
+  }
+}
+
+function resolveGatewayBaseUrl(): string {
+  const explicit =
+    process.env.DENCH_GATEWAY_URL?.trim() || process.env.GATEWAY_URL?.trim();
+  if (explicit) return explicit.replace(/\/+$/, "");
+  const host = process.env.DENCH_HOST?.trim();
+  if (host && /localhost|127\.0\.0\.1/.test(host)) {
+    return "http://localhost:8787";
+  }
+  return "https://gateway.merseoriginals.com";
+}
+
+/**
+ * Best-effort guess at the Next.js host that should receive the
+ * Composio OAuth callback when an agent runs `dench tool connect`
+ * outside the browser. Sandboxes set `DENCH_API_URL` /
+ * `DENCH_INTERNAL_BASE` / `DENCH_HOST` already; pick whichever one is
+ * available so the redirect lands on the right deployment. Falls back
+ * to production.
+ */
+function resolveAppPublicOrigin(): string {
+  const candidates = [
+    process.env.DENCH_API_URL,
+    process.env.DENCH_INTERNAL_BASE,
+    process.env.DENCH_HOST,
+    process.env.NEXT_PUBLIC_APP_URL,
+    process.env.NEXT_PUBLIC_SITE_URL,
+  ];
+  for (const candidate of candidates) {
+    const trimmed = candidate?.trim();
+    if (trimmed) return trimmed.replace(/\/+$/, "");
+  }
+  return "https://dench.com";
+}
+
+function requireApiKey(): string {
+  const apiKey = process.env.DENCH_API_KEY?.trim();
+  if (!apiKey) throw new MissingApiKeyError();
+  return apiKey;
+}
+
+async function callGateway(
+  method: "GET" | "POST" | "DELETE",
+  path: string,
+  body?: Record<string, unknown>,
+): Promise<unknown> {
+  const apiKey = requireApiKey();
+  const baseUrl = resolveGatewayBaseUrl();
+  const init: RequestInit = {
+    method,
+    headers: {
+      "content-type": "application/json",
+      authorization: `Bearer ${apiKey}`,
+    },
+  };
+  if (body !== undefined) init.body = JSON.stringify(body);
+  const response = await fetch(`${baseUrl}${path}`, init);
+  if (!response.ok) {
+    const detail = await response.text().catch(() => "");
+    throw new GatewayHttpError({ status: response.status, body: detail, path });
+  }
+  if (response.status === 204) return null;
+  const contentType = response.headers.get("content-type") ?? "";
+  if (!contentType.includes("application/json")) {
+    return response.text();
+  }
+  return response.json();
+}
+
+// ---------------------------------------------------------------------------
+// Result extraction & formatting
+// ---------------------------------------------------------------------------
+
+const NO_CONNECTION_HINTS = [
+  "composio_account_selection_required",
+  "no active connection",
+  "no connection found",
+  "connected_account_id is required",
+  "is not active or does not exist",
+  "account is not active",
+  "account does not exist",
+  "connection has been disabled",
+  "connection is disabled",
+];
+
+function isLikelyNoConnection(error: GatewayHttpError): boolean {
+  if (![400, 404, 422].includes(error.status)) return false;
+  const lower = error.body.toLowerCase();
+  return NO_CONNECTION_HINTS.some((hint) => lower.includes(hint));
+}
+
+function noConnectionPayload(toolSlug: string, error: GatewayHttpError) {
+  const toolkit = toolkitFromSlug(toolSlug);
+  return {
+    ok: false,
+    no_connection: true,
+    tool_slug: toolSlug,
+    toolkit,
+    error: error.message,
+    next_actions: toolkit
+      ? [
+          `Run \`dench tool connect ${toolkit}\` to start the OAuth flow, then re-run this command.`,
+        ]
+      : [
+          "Run `dench tool connect <toolkit>` to start the OAuth flow, then re-run this command.",
+        ],
+  };
+}
+
+function formatNoConnection(payload: ReturnType<typeof noConnectionPayload>) {
+  const lines = [
+    "No active connection for this tool.",
+    `Tool: ${payload.tool_slug}`,
+    payload.toolkit ? `Toolkit: ${payload.toolkit}` : null,
+    "",
+    "Next actions:",
+    ...payload.next_actions.map((line) => `  - ${line}`),
+  ];
+  return lines.filter((line) => line !== null).join("\n");
+}
+
+function toolkitFromSlug(toolSlug: string): string | undefined {
+  const head = toolSlug.split("_")[0];
+  return head ? head.toLowerCase() : undefined;
+}
+
+function extractConnections(payload: unknown): JsonRecord[] {
+  const root = asRecord(payload);
+  const candidates = [
+    asRecordArray(root?.connections),
+    asRecordArray(root?.items),
+    asRecordArray(asRecord(root?.data)?.items),
+    asRecordArray(asRecord(root?.data)?.connections),
+    asRecordArray(root?.data),
+  ];
+  for (const candidate of candidates) {
+    if (candidate.length > 0) return candidate;
+  }
+  if (Array.isArray(payload))
+    return payload.filter((entry) => asRecord(entry)) as JsonRecord[];
+  return [];
+}
+
+function extractToolkits(payload: unknown): JsonRecord[] {
+  const root = asRecord(payload);
+  return (
+    asRecordArray(root?.items) ||
+    asRecordArray(root?.toolkits) ||
+    asRecordArray(root?.data) ||
+    []
+  );
+}
+
+function compactConnection(connection: JsonRecord) {
+  return {
+    toolkit:
+      stringField(connection, "toolkit_slug", "toolkit") ??
+      stringField(asRecord(connection.toolkit), "slug", "name") ??
+      "unknown",
+    status: stringField(connection, "status", "connection_status") ?? "unknown",
+    connectedAccountId:
+      stringField(
+        connection,
+        "connected_account_id",
+        "connectedAccountId",
+        "id",
+      ) ?? null,
+    accountLabel:
+      stringField(connection, "account_label", "accountLabel", "label") ?? null,
+  };
+}
+
+function formatStatusSummary(summary: {
+  toolkit: string | null;
+  count: number;
+  connections: ReturnType<typeof compactConnection>[];
+}): string {
+  const lines: string[] = [];
+  if (summary.toolkit) {
+    lines.push(`Connections for ${summary.toolkit}:`);
+  } else {
+    lines.push("Connected apps:");
+  }
+  if (summary.connections.length === 0) {
+    lines.push("  none");
+  } else {
+    for (const connection of summary.connections.slice(0, 24)) {
+      const label = connection.accountLabel
+        ? ` (${connection.accountLabel})`
+        : "";
+      lines.push(
+        `  - ${connection.toolkit} [${connection.status}]${label}${
+          connection.connectedAccountId
+            ? ` id=${connection.connectedAccountId}`
+            : ""
+        }`,
+      );
+    }
+  }
+  return lines.join("\n");
+}
+
+const READ_ONLY_TOOL_ACTIONS = new Set([
+  "FETCH",
+  "GET",
+  "LIST",
+  "SEARCH",
+  "READ",
+  "FIND",
+]);
+
+function toolApprovalHint(toolSlug: string | undefined): string {
+  if (!toolSlug) return "approval unknown";
+  const tokens = toolSlug
+    .toUpperCase()
+    .split(/[^A-Z0-9]+/)
+    .filter(Boolean);
+  const readOnly = tokens.find((token) => READ_ONLY_TOOL_ACTIONS.has(token));
+  return readOnly ? `read-only (${readOnly})` : "approval likely";
+}
+
+function formatSearchResult(searchResult: unknown): string {
+  const root = asRecord(searchResult);
+  const data = asRecord(root?.data) ?? root;
+  const items = extractSearchItems(data);
+  const connectedSet = connectedToolkitSet(data);
+
+  if (items.length === 0) {
+    return [
+      "No matching tools found.",
+      "",
+      "`dench tool search` is a KEYWORD search over Composio's tool",
+      "names and descriptions, not a semantic / natural-language search.",
+      "Retry with one or two concrete tokens that likely appear in the",
+      'tool slug or its docs ("fetch emails", "send message", "create',
+      'issue", "list channels"). Drop filter words like "today" /',
+      '"unread" — those go in the EXECUTED tool\'s --args, not in the',
+      "catalog query. Pass --toolkit <slug> to narrow further.",
+      "",
+      "Use --json if you need the raw provider response.",
+    ].join("\n");
+  }
+
+  const lines = [
+    `Top tools${stringField(data, "query") ? ` for "${stringField(data, "query")}"` : ""}:`,
+  ];
+  for (const [index, tool] of items.entries()) {
+    const slug = stringField(tool, "slug", "tool_slug") ?? "unknown_tool";
+    const name = stringField(tool, "display_name", "name") ?? slug;
+    const toolkit =
+      stringField(tool, "toolkit_slug") ??
+      stringField(asRecord(tool.toolkit), "slug", "name") ??
+      "unknown";
+    const isConnected =
+      booleanField(asRecord(tool.connection_status), "is_connected") ??
+      connectedSet.has(toolkit.toLowerCase());
+    const description = compactLine(tool.description) ?? null;
+    lines.push(
+      `${index + 1}. ${slug} - ${name}`,
+      `   toolkit: ${toolkit} | ${toolApprovalHint(slug)} | ${
+        isConnected ? "connected" : "not connected"
+      }`,
+    );
+    if (description) lines.push(`   ${description}`);
+  }
+  lines.push(
+    "",
+    "Use dench tool run <slug> --args '{...}' when ready.",
+    "Use --json only when you need full schemas or raw arguments.",
+  );
+  return lines.join("\n");
+}
+
+function extractSearchItems(data: JsonRecord | undefined): JsonRecord[] {
+  const direct = asRecordArray(data?.items);
+  if (direct.length > 0) return direct;
+  const schemas = asRecord(data?.tool_schemas);
+  if (!schemas) return [];
+  return Object.entries(schemas).flatMap<JsonRecord>(([slug, value]) => {
+    const tool = asRecord(value);
+    return tool
+      ? [{ ...tool, tool_slug: stringField(tool, "tool_slug") ?? slug }]
+      : [];
+  });
+}
+
+function connectedToolkitSet(data: JsonRecord | undefined): Set<string> {
+  const set = new Set<string>();
+  for (const value of asRecordArray(data?.toolkit_connection_statuses)) {
+    if (booleanField(value, "has_active_connection")) {
+      const slug = stringField(value, "toolkit");
+      if (slug) set.add(slug.toLowerCase());
+    }
+  }
+  if (Array.isArray(data?.connected_toolkits)) {
+    for (const value of data?.connected_toolkits ?? []) {
+      if (typeof value === "string") set.add(value.toLowerCase());
+    }
+  }
+  return set;
+}
+
+// ---------------------------------------------------------------------------
+// Redaction (display-only)
+// ---------------------------------------------------------------------------
+
+const SENSITIVE_KEY_RE =
+  /(?:otp|oneTime|verification|security|passcode|password|secret|api[_-]?key|access[_-]?token|refresh[_-]?token|authorization)/i;
+
+function redactForDisplay(value: unknown, key?: string): unknown {
+  if (typeof value === "string") {
+    return key && SENSITIVE_KEY_RE.test(key)
+      ? "[redacted]"
+      : value
+          .replace(
+            /\b((?:one[-\s]?time|verification|security|login|sign[-\s]?in|auth(?:entication)?|2fa|mfa|otp|passcode|code)[^.\n\r]{0,80}?)(\d[\d\s-]{2,10}\d)\b/gi,
+            "$1[redacted-code]",
+          )
+          .replace(
+            /\b((?:api[_\s-]?key|secret|token|password)[^.\n\r]{0,60}?)([A-Za-z0-9_=-]{12,})\b/gi,
+            "$1[redacted-secret]",
+          );
+  }
+  if (typeof value === "number" && key && SENSITIVE_KEY_RE.test(key)) {
+    return "[redacted]";
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => redactForDisplay(item));
+  }
+  const record = asRecord(value);
+  if (!record) return value;
+  return Object.fromEntries(
+    Object.entries(record).map(([entryKey, entryValue]) => [
+      entryKey,
+      redactForDisplay(entryValue, entryKey),
+    ]),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Help text
+// ---------------------------------------------------------------------------
+
+function toolHelp() {
+  console.log(`Dench tool commands
+
+Usage:
+  dench apps [--json]
+  dench tool status [toolkit] [--json]
+  dench tool connect <toolkit> [--callback-url <url>] [--json]
+  dench tool search "create github issue" [--toolkit github] [--limit 20] [--json]
+  dench tool run <composio_tool_slug> --args '{"key":"value"}' [--account <connectedAccountId>] [--json]
+  dench tool disconnect <connectionId> [--json]
+
+Notes:
+  All commands authenticate with DENCH_API_KEY (Bearer) directly to the
+  Dench Cloud Gateway. No \`dench login\` agent session required.
+  dench tool connect prints the OAuth redirect URL for the human to open.
+  dench tool run output is redacted for display; pass --json for raw output.
+  Override the gateway base with DENCH_GATEWAY_URL or GATEWAY_URL.
+`);
+}
+
+// ---------------------------------------------------------------------------
+// Tiny utility helpers (local copies — keeps this file self-contained)
+// ---------------------------------------------------------------------------
+
+type JsonRecord = Record<string, unknown>;
+
+function asRecord(value: unknown): JsonRecord | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  return value as JsonRecord;
+}
+
+function asRecordArray(value: unknown): JsonRecord[] {
+  return Array.isArray(value)
+    ? value.flatMap<JsonRecord>((item) => asRecord(item) ?? [])
+    : [];
+}
+
+function stringField(
+  record: JsonRecord | undefined,
+  ...names: string[]
+): string | undefined {
+  if (!record) return undefined;
+  for (const name of names) {
+    const value = record[name];
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return undefined;
+}
+
+function booleanField(
+  record: JsonRecord | undefined,
+  ...names: string[]
+): boolean | undefined {
+  if (!record) return undefined;
+  for (const name of names) {
+    const value = record[name];
+    if (typeof value === "boolean") return value;
+  }
+  return undefined;
+}
+
+function compactLine(value: unknown, maxLength = 140): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const text = value.replace(/\s+/g, " ").trim();
+  if (!text) return undefined;
+  return text.length > maxLength ? `${text.slice(0, maxLength - 1)}...` : text;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function parsePositiveInt(name: string, raw: string): number {
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new ToolCliError(`Invalid ${name} value: ${raw}`);
+  }
+  return Math.floor(parsed);
+}
+
+// Re-export shared helpers used implicitly above so eslint doesn't flag
+// them as unused when callers tree-shake.
+export { ToolCliError, GatewayHttpError, MissingApiKeyError };
+// Kept reachable so a future caller can build their own dispatcher.
+export { resolveGatewayBaseUrl, requireApiKey, callGateway };
+// shiftRaw / hasFlag from cli-args are not used in this module yet but
+// keep the import group consistent with cli/search.ts conventions.
+void shiftRaw;
+void hasFlag;
+void CliArgError;