@dench.com/cli 2.7.8 → 2.7.10-staging.100

package/tools.ts

@@ -1,5 +1,5 @@
 /**
- * `dench tool` and `dench apps` — direct Dench Cloud Gateway access for
+ * `dench tool` and `dench integrations` — 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
@@ -7,10 +7,15 @@
  * paid-workspace gateway key resolved from the active agent session by
  * the top-level dispatcher.
  *
+ * The one exception is the connection LISTING, which is not a pure gateway
+ * passthrough: Gmail, Outlook, Calendar and LinkedIn are brokered by Dench
+ * through Unipile, not Composio, so `status` also reads them from Convex and
+ * merges the two into one list. See `fetchUnipileConnections`.
+ *
  * Subcommands:
  *
- *   dench apps [--json]                                            — list connected apps
- *   dench tool status [toolkit?] [--json]                          — list connections (optionally narrowed)
+ *   dench integrations [--json]                                    — every connection, both brokers
+ *   dench tool status [toolkit?] [--json]                          — same list (optionally narrowed)
  *   dench tool search "<query>" [--toolkit <slug>] [--limit N] [--compact] [--json]
  *   dench tool run <slug> [--args <json>] [--account <id>] [--json]
  *   dench tool connect <toolkit> [--callback-url <url>] [--json]   — print OAuth redirect URL
@@ -32,6 +37,8 @@
  * working.
  */
 
+import type { ConvexHttpClient } from "convex/browser";
+import { makeFunctionReference } from "convex/server";
 import { PRODUCTION_API_URL, PRODUCTION_GATEWAY_URL } from "./host";
 import {
   CliArgError,
@@ -51,6 +58,13 @@ export type ToolCliContext = {
   bearerToken?: string;
   gatewayBaseUrl?: string;
   gatewayHeaders?: Record<string, string>;
+  /**
+   * Convex client + bearer for the Unipile half of the list. Absent on the
+   * help path and whenever the caller could not be authenticated, in which
+   * case the command still runs and reports Composio only.
+   */
+  convex?: ConvexHttpClient;
+  sessionToken?: string;
 };
 
 type GatewayAuthContext = Pick<
@@ -58,6 +72,8 @@ type GatewayAuthContext = Pick<
   "bearerToken" | "gatewayBaseUrl" | "gatewayHeaders"
 >;
 
+type UnipileAuthContext = Pick<ToolCliContext, "convex" | "sessionToken">;
+
 export async function runToolCommand(ctx: ToolCliContext): Promise<void> {
   const sub = ctx.args[0];
   if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
@@ -90,48 +106,147 @@ export async function runToolCommand(ctx: ToolCliContext): Promise<void> {
   throw new ToolCliError(`Unknown dench tool subcommand: ${sub}`);
 }
 
+const listUnipileConnectionsRef = makeFunctionReference<"query">(
+  "functions/unipileConnections:listConnections",
+);
+const listUnipileToolsRef = makeFunctionReference<"query">(
+  "functions/unipileTools:listTools",
+);
+const getUnipileToolRef = makeFunctionReference<"query">(
+  "functions/unipileTools:getTool",
+);
+const runUnipileToolRef = makeFunctionReference<"action">(
+  "functions/unipileToolsNode:runTool",
+);
+
+/**
+ * Gmail, Outlook, Calendar and LinkedIn are brokered by Dench, and Composio
+ * refuses to connect them — so its catalogue entries for those toolkits can
+ * never execute, and showing them next to the ones that work just teaches an
+ * agent to pick a tool that always answers `composio_not_connected`.
+ *
+ * The set comes from the server with the tools themselves rather than being
+ * hardcoded here, so a fifth platform needs no CLI change.
+ */
+
+/**
+ * Composio spells some toolkits without a separator (`googlecalendar`), while
+ * our registry uses the hyphenated form. Normalize through this map before the
+ * membership test, or the dead Composio calendar entries survive the filter
+ * and sit next to the working ones under two names for one product.
+ */
+const COMPOSIO_TOOLKIT_ALIASES: Record<string, string> = {
+  googlecalendar: "google-calendar",
+  outlookcalendar: "outlook-calendar",
+};
+
+function withoutShadowedComposioTools(
+  items: JsonRecord[],
+  ownedToolkits: Set<string>,
+): JsonRecord[] {
+  if (ownedToolkits.size === 0) return items;
+  return items.filter((item) => {
+    const slug = (
+      stringField(item, "toolkit_slug") ??
+      stringField(asRecord(item.toolkit), "slug", "name") ??
+      ""
+    )
+      .toLowerCase()
+      .replaceAll("_", "-");
+    const canonical = COMPOSIO_TOOLKIT_ALIASES[slug] ?? slug;
+    return !canonical || !ownedToolkits.has(canonical);
+  });
+}
+
+/**
+ * Gmail, Outlook, Calendar and LinkedIn — the connections Dench brokers itself
+ * through Unipile rather than Composio.
+ *
+ * They come from Convex, not the gateway, so this is a second fetch rather than
+ * a richer parse of the first. It NEVER throws: a CLI ships independently of
+ * the deployment it talks to (npm publish + a re-baked Daytona snapshot), so a
+ * new CLI will meet backends that do not export this query yet. Failing the
+ * whole command over that would take `dench integrations` from "missing the
+ * calendar" to "broken", which is strictly worse.
+ */
+async function fetchUnipileConnections(ctx: UnipileAuthContext): Promise<{
+  available: boolean;
+  connections: CompactConnection[];
+  error?: string;
+}> {
+  if (!ctx.convex) {
+    return {
+      available: false,
+      connections: [],
+      error: "no Dench session — sign in with `dench signin`",
+    };
+  }
+  try {
+    const rows = await ctx.convex.query(listUnipileConnectionsRef, {
+      ...(ctx.sessionToken ? { sessionToken: ctx.sessionToken } : {}),
+    } as never);
+    if (!Array.isArray(rows)) return { available: true, connections: [] };
+    return {
+      available: true,
+      connections: rows.map((row) =>
+        compactUnipileConnection(asRecord(row) ?? {}),
+      ),
+    };
+  } catch (error) {
+    return { available: false, connections: [], error: errorMessage(error) };
+  }
+}
+
 /**
  * Summarise the user's connected apps for `dench context` and friends.
  * Speaks straight to the gateway with either DENCH_API_KEY or a gateway
- * key resolved from the active agent session.
+ * key resolved from the active agent session, and merges in the Unipile
+ * connections Composio never reports.
  * Returns the same legacy shape the previous Convex-routed path did so
  * existing parsers don't need to change.
  */
 export async function fetchConnectedAppsSummary(
-  ctx: GatewayAuthContext = {},
+  ctx: GatewayAuthContext & UnipileAuthContext = {},
 ): Promise<{
   available: boolean;
   count: number;
-  connections: Array<{
-    toolkit: string;
-    status: string;
-    connectedAccountId: string | null;
-    accountLabel: string | null;
-  }>;
+  connections: CompactConnection[];
+  unipileAvailable: boolean;
+  unipileError?: string;
   error?: string;
   reason?: string;
 }> {
+  const unipile = await fetchUnipileConnections(ctx);
+  const unipileFields = {
+    unipileAvailable: unipile.available,
+    ...(unipile.error ? { unipileError: unipile.error } : {}),
+  };
   let payload: unknown;
   try {
     payload = await callGateway(ctx, "GET", "/v1/composio/connections");
   } catch (error) {
-    if (error instanceof MissingApiKeyError) {
-      return {
-        available: false,
-        reason: error.message,
-        count: 0,
-        connections: [],
-      };
-    }
-    return {
+    // Composio being unreachable must not hide a connected calendar, so the
+    // Unipile rows are still reported alongside the failure.
+    const failure = {
       available: false,
-      error: errorMessage(error),
-      count: 0,
-      connections: [],
+      count: unipile.connections.length,
+      connections: unipile.connections,
+      ...unipileFields,
     };
+    return error instanceof MissingApiKeyError
+      ? { ...failure, reason: error.message }
+      : { ...failure, error: errorMessage(error) };
   }
-  const connections = extractConnections(payload).map(compactConnection);
-  return { available: true, count: connections.length, connections };
+  const connections = [
+    ...extractConnections(payload).map(compactConnection),
+    ...unipile.connections,
+  ];
+  return {
+    available: true,
+    count: connections.length,
+    connections,
+    ...unipileFields,
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -142,11 +257,10 @@ 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(
-    ctx,
-    "GET",
-    "/v1/composio/connections",
-  );
+  const [connectionsPayload, unipile] = await Promise.all([
+    callGateway(ctx, "GET", "/v1/composio/connections"),
+    fetchUnipileConnections(ctx),
+  ]);
   let toolkitsPayload: unknown = null;
   if (filterToolkit) {
     const search = encodeURIComponent(filterToolkit);
@@ -157,12 +271,16 @@ async function runStatusSubcommand(ctx: ToolCliContext): Promise<void> {
     );
   }
 
-  const allConnections = extractConnections(connectionsPayload);
+  const allConnections = [
+    ...extractConnections(connectionsPayload).map(compactConnection),
+    ...unipile.connections,
+  ];
+  // Filtering after the merge is what makes `dench tool status gmail` answer
+  // with the Unipile mailbox instead of nothing.
   const filteredConnections = filterToolkit
-    ? allConnections.filter((conn) => {
-        const slug = stringField(conn, "toolkit_slug", "toolkit") ?? "";
-        return slug.toLowerCase() === filterToolkit.toLowerCase();
-      })
+    ? allConnections.filter(
+        (conn) => conn.toolkit.toLowerCase() === filterToolkit.toLowerCase(),
+      )
     : allConnections;
 
   const summary = {
@@ -170,7 +288,9 @@ async function runStatusSubcommand(ctx: ToolCliContext): Promise<void> {
     available: true,
     toolkit: filterToolkit ?? null,
     count: filteredConnections.length,
-    connections: filteredConnections.map(compactConnection),
+    connections: filteredConnections,
+    unipileAvailable: unipile.available,
+    ...(unipile.error ? { unipileError: unipile.error } : {}),
     ...(toolkitsPayload
       ? { toolkit_info: extractToolkits(toolkitsPayload) }
       : {}),
@@ -210,17 +330,141 @@ async function runSearchSubcommand(ctx: ToolCliContext): Promise<void> {
   if (toolkit) body.toolkit_slug = toolkit;
   if (limit) body.limit = limit;
 
-  const payload = await callGateway(
-    ctx,
-    "POST",
-    "/v1/composio/tools/search",
-    body,
+  const [payload, unipile] = await Promise.all([
+    callGateway(ctx, "POST", "/v1/composio/tools/search", body),
+    fetchUnipileTools(ctx, { query, ...(toolkit ? { toolkit } : {}) }),
+  ]);
+
+  const record = asRecord(payload) ?? {};
+  const ownedToolkits = new Set(
+    unipile.tools
+      .map((tool) => stringField(asRecord(tool.toolkit), "slug") ?? "")
+      .filter(Boolean),
   );
+  const merged = {
+    ...record,
+    items: [
+      ...withoutShadowedComposioTools(
+        extractSearchItems(record),
+        ownedToolkits,
+      ),
+      ...unipile.tools,
+    ],
+    unipileAvailable: unipile.available,
+    ...(unipile.error ? { unipileError: unipile.error } : {}),
+  };
+
   if (ctx.jsonOutput) {
-    console.log(JSON.stringify(payload, null, 2));
+    console.log(JSON.stringify(merged, null, 2));
     return;
   }
-  console.log(formatSearchResult(payload, compact));
+  console.log(formatSearchResult(merged, compact));
+}
+
+/**
+ * Whether this slug is ours. A lookup failure answers "not ours", so an old
+ * deployment routes everything to Composio exactly as it did before.
+ */
+async function resolveUnipileTool(
+  ctx: UnipileAuthContext,
+  slug: string,
+): Promise<JsonRecord | null> {
+  if (!ctx.convex) return null;
+  try {
+    return (
+      asRecord(await ctx.convex.query(getUnipileToolRef, { slug } as never)) ??
+      null
+    );
+  } catch {
+    return null;
+  }
+}
+
+async function runUnipileTool(
+  ctx: ToolCliContext,
+  slug: string,
+  toolArgs: Record<string, unknown>,
+  approvalId: string | undefined,
+): Promise<void> {
+  if (!ctx.convex) throw new MissingApiKeyError();
+  const result = await ctx.convex.action(runUnipileToolRef, {
+    ...(ctx.sessionToken ? { sessionToken: ctx.sessionToken } : {}),
+    slug,
+    arguments: toolArgs,
+    ...(approvalId ? { approvalId } : {}),
+  } as never);
+
+  const record = asRecord(result) ?? {};
+  if (ctx.jsonOutput) {
+    console.log(JSON.stringify(record, null, 2));
+  } else {
+    console.log(formatUnipileToolResult(record));
+  }
+  // Same convention as the Composio failures below: a refusal the agent is
+  // expected to act on exits non-zero without throwing, so the payload above
+  // is still the thing it reads.
+  if (record.ok === false) process.exitCode = 1;
+}
+
+function formatUnipileToolResult(record: JsonRecord): string {
+  if (record.ok === false) {
+    const lines = [
+      `Failed: ${stringField(record, "error") ?? "unknown error"}`,
+    ];
+    const approvalId = stringField(record, "approvalId");
+    if (approvalId) {
+      lines.push(
+        `Approval required. Once a human says yes:`,
+        `  dench approval approve ${approvalId} --evidence "…"`,
+        `  dench tool run ${stringField(record, "toolSlug") ?? "<slug>"} --args '…' --approval ${approvalId}`,
+      );
+    }
+    return lines.join("\n");
+  }
+  if (record.queued === true) {
+    const data = asRecord(record.data) ?? {};
+    return [
+      `Queued: ${stringField(data, "action_id") ?? "unknown"}`,
+      "LinkedIn actions are paced to protect the account.",
+      `  dench tool run LINKEDIN_GET_ACTION_STATUS --args '{"action_id":"${stringField(data, "action_id") ?? ""}"}'`,
+    ].join("\n");
+  }
+  return JSON.stringify(redactForDisplay(record), null, 2);
+}
+
+/**
+ * The Unipile half of tool discovery. Never throws, for the same reason the
+ * connection listing does not: the CLI ships on its own cadence, so a new CLI
+ * will meet deployments that do not export these functions yet. That must cost
+ * the Unipile tools, not the whole search.
+ */
+async function fetchUnipileTools(
+  ctx: UnipileAuthContext,
+  options: { query?: string; toolkit?: string } = {},
+): Promise<{ available: boolean; tools: JsonRecord[]; error?: string }> {
+  if (!ctx.convex) {
+    return {
+      available: false,
+      tools: [],
+      error: "no Dench session — sign in with `dench signin`",
+    };
+  }
+  try {
+    const rows = await ctx.convex.query(listUnipileToolsRef, {
+      ...(ctx.sessionToken ? { sessionToken: ctx.sessionToken } : {}),
+      ...(options.query ? { query: options.query } : {}),
+      ...(options.toolkit ? { toolkit: options.toolkit } : {}),
+    } as never);
+    if (!Array.isArray(rows)) return { available: true, tools: [] };
+    return {
+      available: true,
+      tools: rows
+        .map((row) => asRecord(row))
+        .filter((row): row is JsonRecord => row !== undefined),
+    };
+  } catch (error) {
+    return { available: false, tools: [], error: errorMessage(error) };
+  }
 }
 
 async function runRunSubcommand(ctx: ToolCliContext): Promise<void> {
@@ -233,6 +477,7 @@ async function runRunSubcommand(ctx: ToolCliContext): Promise<void> {
   ctx.args.shift();
   const argsJson = getFlag(ctx.args, "--args");
   const account = getFlag(ctx.args, "--account");
+  const approval = getFlag(ctx.args, "--approval");
   const parsedArgs = (parseJson(argsJson) ?? {}) as Record<string, unknown>;
   if (
     parsedArgs &&
@@ -244,6 +489,16 @@ async function runRunSubcommand(ctx: ToolCliContext): Promise<void> {
     throw new ToolCliError("--args must be a JSON object");
   }
 
+  // Ask the server which broker owns this slug rather than keeping a copy of
+  // the vocabulary here. Two hand-maintained lists is the drift CLAUDE.md
+  // records for gateway usage providers, and here it would mean a real tool
+  // routed to Composio, which 404s.
+  const unipileTool = await resolveUnipileTool(ctx, toolSlug);
+  if (unipileTool) {
+    await runUnipileTool(ctx, toolSlug, parsedArgs, approval);
+    return;
+  }
+
   const body: Record<string, unknown> = {
     tool_slug: toolSlug,
     arguments: parsedArgs,
@@ -653,8 +908,30 @@ function extractToolkits(payload: unknown): JsonRecord[] {
   );
 }
 
-function compactConnection(connection: JsonRecord) {
+/**
+ * The merged row shape. `source` is the discriminator: `composio` rows carry a
+ * routable `connectedAccountId` (usable as `dench tool run --account`), while
+ * `unipile` rows never do — their account id is an internal credential.
+ */
+export type CompactConnection = {
+  source: "composio" | "unipile";
+  toolkit: string;
+  status: string;
+  connectedAccountId: string | null;
+  accountLabel: string | null;
+  /** Unipile only: whether the connection belongs to this agent's member. */
+  isOwner?: boolean;
+  ownerName?: string;
+  /**
+   * Unipile only. A teammate's `private` connection is never listed at all, so
+   * `private` here always means the caller's own.
+   */
+  visibility?: "private" | "shared";
+};
+
+function compactConnection(connection: JsonRecord): CompactConnection {
   return {
+    source: "composio",
     toolkit:
       stringField(connection, "toolkit_slug", "toolkit") ??
       stringField(asRecord(connection.toolkit), "slug", "name") ??
@@ -672,10 +949,47 @@ function compactConnection(connection: JsonRecord) {
   };
 }
 
+function compactUnipileConnection(connection: JsonRecord): CompactConnection {
+  return {
+    source: "unipile",
+    toolkit: stringField(connection, "toolkit") ?? "unknown",
+    status: stringField(connection, "status") ?? "unknown",
+    connectedAccountId: null,
+    accountLabel: stringField(connection, "accountLabel") ?? null,
+    isOwner: connection.isOwner === true,
+    ownerName: stringField(connection, "ownerName") ?? undefined,
+    visibility: connection.visibility === "private" ? "private" : "shared",
+  };
+}
+
+function formatConnectionLine(connection: CompactConnection): string {
+  const label = connection.accountLabel ? ` (${connection.accountLabel})` : "";
+  const id = connection.connectedAccountId
+    ? ` id=${connection.connectedAccountId}`
+    : "";
+  // "via Dench" both names the broker and explains why the row has no
+  // connected-account id to pass to `dench tool run`.
+  const via = connection.source === "unipile" ? " via Dench" : "";
+  // Whose mailbox/LinkedIn it is only matters when it is not this agent's —
+  // `dench email --mailbox` picks between them.
+  const owner =
+    connection.source === "unipile" &&
+    connection.isOwner === false &&
+    connection.ownerName
+      ? ` · ${connection.ownerName}`
+      : "";
+  // Only ever the caller's own — a teammate's private connection is filtered
+  // out server-side rather than shown as unusable.
+  const privacy = connection.visibility === "private" ? " · private" : "";
+  return `  - ${connection.toolkit} [${connection.status}]${label}${id}${via}${owner}${privacy}`;
+}
+
 function formatStatusSummary(summary: {
   toolkit: string | null;
   count: number;
-  connections: ReturnType<typeof compactConnection>[];
+  connections: CompactConnection[];
+  unipileAvailable?: boolean;
+  unipileError?: string;
 }): string {
   const lines: string[] = [];
   if (summary.toolkit) {
@@ -686,18 +1000,16 @@ function formatStatusSummary(summary: {
   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}`
-            : ""
-        }`,
-      );
-    }
+    lines.push(...summary.connections.slice(0, 24).map(formatConnectionLine));
+  }
+  // Say so rather than silently listing Composio only — otherwise a connected
+  // calendar reads as absent, which is the failure this merge exists to fix.
+  if (summary.unipileAvailable === false) {
+    lines.push(
+      `  (could not check Gmail/Outlook/Calendar/LinkedIn: ${
+        summary.unipileError ?? "unknown error"
+      })`,
+    );
   }
   return lines.join("\n");
 }
@@ -849,16 +1161,27 @@ function toolHelp() {
   console.log(`Dench tool commands
 
 Usage:
-  dench apps [--json]
+  dench integrations [--json]
   dench tool status [toolkit] [--json]
   dench tool connect <toolkit> [--callback-url <url>] [--json]
   dench tool search "create github issue" [--toolkit github] [--limit 20] [--compact] [--json]
-  dench tool run <composio_tool_slug> --args '{"key":"value"}' [--account <connectedAccountId>] [--json]
+  dench tool run <tool_slug> --args '{"key":"value"}' [--account <connectedAccountId>] [--approval <approvalId>] [--json]
   dench tool disconnect <connectionId> [--json]
 
 Notes:
   All commands authenticate with DENCH_API_KEY or the active \`dench signin\`
   agent session. Agent sessions require a paid workspace.
+  Results carry a "source". "composio" rows are brokered by Composio; "unipile"
+  rows (gmail, outlook, calendar, linkedin) are connected by Dench itself. Both
+  run through \`dench tool run\` with the same slug + --args contract; only
+  \`dench tool connect\` is Composio-only — the human connects the other four
+  from the workspace Marketplace.
+  A write tool returns approval_required with an approvalId. Once a human
+  approves it, re-run with --approval <approvalId>; an approval is bound to that
+  exact tool and argument set.
+  LinkedIn tools are QUEUED, not run inline, so account-safety pacing (daily
+  caps, working hours, spacing) applies. They return an action_id — poll it with
+  LINKEDIN_GET_ACTION_STATUS.
   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.