@dench.com/cli 2.8.3-staging.117 → 2.8.4-staging.154

package/dench.ts

@@ -715,6 +715,10 @@ Auth:
 Notes:
   dench integrations is an alias for dench tool status.
   dench tool connect prints the OAuth redirect URL for the human to open.
+  Slack is Dench's IN-HOUSE integration (never Composio): \`dench tool connect
+  slack\` prints the first-party install URL, and SLACK_* tools (send with
+  Block Kit blocks/buttons, read history, list channels/users) run through
+  the org's own Slack app and can post to / read any channel.
   dench tool run output is redacted for display; pass --json for raw JSON.
   Override the gateway base with DENCH_GATEWAY_URL or GATEWAY_URL.
 `);
@@ -890,17 +894,20 @@ Usage:
 
 Lists every app connected to this organization, from both brokers:
 
-  - Composio apps (Slack, GitHub, Notion, …), each with a
+  - Composio apps (GitHub, Notion, HubSpot, …), each with a
     \`connectedAccountId\` you can pass to \`dench tool run --account\`.
-  - Gmail, Outlook, Calendar and LinkedIn, which Dench connects itself.
-    These show \`source: "unipile"\` and no connected-account id, but they
-    run through the SAME \`dench tool search\` / \`dench tool run\` — find
-    the slug and run it. Only \`dench tool connect\` is Composio-only; a
-    human connects these four from the workspace Marketplace.
+  - Gmail, Outlook, Calendar, LinkedIn (\`source: "unipile"\`) and Slack
+    (\`source: "dench"\`), which Dench connects itself. These have no
+    connected-account id, but they run through the SAME \`dench tool
+    search\` / \`dench tool run\` — find the slug and run it. \`dench tool
+    connect slack\` prints the in-house Slack install URL (org admin);
+    a human connects the other four from the workspace Marketplace.
+    Slack is ALWAYS in-house (never Composio): SLACK_* tools can post
+    to / read any channel, with Block Kit blocks and buttons.
     For reading, the CRM is usually better: calendar events sync into
     \`calendar_event\` and recordings into \`meeting\`.
 
-Composio does not broker those four, so they appear ONLY here — a
+Composio does not broker those five, so they appear ONLY here — a
 missing calendar in this list means it is genuinely not connected.
 
 Authenticates with the active \`dench signin\` agent session or
@@ -1135,15 +1142,18 @@ function backendSnapshot(config: ConfigFile) {
   };
 }
 
+function backendSourceHint(source: "flag" | "env" | "config" | "default") {
+  return source === "flag"
+    ? "(set via CLI flag for this invocation)"
+    : source === "env"
+      ? "(set via DENCH_HOST env var)"
+      : source === "config"
+        ? "(set via `dench backend set`)"
+        : "(default — no explicit choice in env or config)";
+}
+
 function formatBackendShow(snapshot: ReturnType<typeof backendSnapshot>) {
-  const sourceHint =
-    snapshot.source === "flag"
-      ? "(set via CLI flag for this invocation)"
-      : snapshot.source === "env"
-        ? "(set via DENCH_HOST env var)"
-        : snapshot.source === "config"
-          ? "(set via `dench backend set`)"
-          : "(default — no explicit choice in env or config)";
+  const sourceHint = backendSourceHint(snapshot.source);
   const lines = [
     `Active backend: ${snapshot.host} [${snapshot.label}] ${sourceHint}`,
   ];
@@ -1462,6 +1472,43 @@ async function selectSession() {
   }
 
   const [entry] = matches;
+
+  // `dench use` only records WHICH session is selected — it never moves the
+  // backend. If the machine's command target (flags > DENCH_HOST >
+  // `dench backend set` > production default) points at a DIFFERENT host
+  // than the selected session, every later command resolves that target
+  // host, finds no session there, and fails `login_required` — while this
+  // command would have reported success. That silent trap is exactly the
+  // "use dench-com ok, context login_required, sessions all current:false"
+  // incident (defaultBackend was still http://localhost:3000), so refuse
+  // the no-op selection loudly instead.
+  const snapshot = backendSnapshot(config);
+  if (normalizeHost(snapshot.host) !== entry.host) {
+    const alias =
+      backendLabelForHost(entry.host) === "custom"
+        ? entry.host
+        : backendLabelForHost(entry.host);
+    throw new CliError(
+      `Session ${entry.key} is saved for ${entry.host}, but dench commands currently target ${snapshot.host} ${backendSourceHint(snapshot.source)}. Selecting it would have no effect: commands on this backend would still fail with login_required.`,
+      {
+        code: "session_host_mismatch",
+        sessionHost: entry.host,
+        targetHost: snapshot.host,
+        targetSource: snapshot.source,
+        nextActions: [
+          `Run dench backend set ${alias} to point commands at ${entry.host}, then re-run dench use ${selector}.`,
+          ...(snapshot.source === "env"
+            ? ["Or unset DENCH_HOST so the saved backend applies."]
+            : []),
+          ...(snapshot.source === "flag"
+            ? ["Or drop the --host/--backend/--prod/--staging flag."]
+            : []),
+          `Or sign in on the current backend: dench signin --host ${snapshot.host}.`,
+        ],
+      },
+    );
+  }
+
   await saveConfig({
     ...withCurrentSessionSelection(config, {
       host: entry.host,
@@ -2460,10 +2507,42 @@ function resolveApiHost(fallbackHost: string): string {
   );
 }
 
-function loginRequiredError(command = "this command") {
+function loginRequiredError(
+  command = "this command",
+  context?: {
+    targetHost: string;
+    targetSource: "flag" | "env" | "config" | "default";
+    otherHostSessions: Array<StoredSessionEntry<StoredSession>>;
+  },
+) {
+  // Saved sessions for a DIFFERENT host are the most common reason this
+  // error is a lie ("requires dench signin" while three valid sessions sit
+  // in the config): the backend target moved (usually a stale
+  // `dench backend set local` or DENCH_HOST) after the sessions were saved.
+  // Name that directly so agents stop burning turns re-authing.
+  const mismatchActions =
+    context && context.otherHostSessions.length > 0
+      ? [
+          `You have ${plural(context.otherHostSessions.length, "saved Dench session")} for ${[
+            ...new Set(context.otherHostSessions.map((entry) => entry.host)),
+          ].join(
+            ", ",
+          )}, but commands are targeting ${context.targetHost} ${backendSourceHint(context.targetSource)}.`,
+          "Run dench backend show to inspect the target, then dench backend set <production|staging|local|url> to match the saved sessions.",
+        ]
+      : [];
   return new CliError(`${command} requires dench signin`, {
     code: "login_required",
+    ...(context && context.otherHostSessions.length > 0
+      ? {
+          targetHost: context.targetHost,
+          savedSessionHosts: [
+            ...new Set(context.otherHostSessions.map((entry) => entry.host)),
+          ],
+        }
+      : {}),
     nextActions: [
+      ...mismatchActions,
       "Set DENCH_API_KEY (and CONVEX_URL) in your env if running inside a sandbox or CI.",
       'Or run dench signin --kind <kind> --name "AI Agent - Project" to mint an agent session.',
       "If already approved, run dench sessions --json, then dench use <session-key-or-workspace-slug>.",
@@ -2573,7 +2652,14 @@ async function getRuntime() {
       };
     }
 
-    throw loginRequiredError();
+    const snapshot = backendSnapshot(config);
+    throw loginRequiredError("this command", {
+      targetHost: snapshot.host,
+      targetSource: snapshot.source,
+      otherHostSessions: listStoredSessionEntries(config).filter(
+        (entry) => entry.host !== normalizeHost(host),
+      ),
+    });
   }
 
   if (!hasDevEnv()) {
@@ -4643,14 +4729,33 @@ async function main() {
       return;
     }
     const runtime = await getRuntime();
-    const gatewayAuth = await resolveGatewayCommandAuth(runtime, "dench tool");
+    // `connect slack` never touches the gateway — it prints the in-house
+    // install URL — so don't fail the whole command on gateway auth there.
+    const isSlackConnect =
+      sub === "connect" &&
+      ["slack", "slackbot"].includes(
+        (filteredSubArgs[1] ?? "").trim().toLowerCase(),
+      );
+    const gatewayAuth = isSlackConnect
+      ? null
+      : await resolveGatewayCommandAuth(runtime, "dench tool");
     await runToolCommand({
       args: filteredSubArgs,
       jsonOutput: json,
-      bearerToken: gatewayAuth.bearerToken,
-      gatewayBaseUrl: gatewayAuth.gatewayBaseUrl,
-      gatewayHeaders: gatewayAuth.gatewayHeaders,
+      ...(gatewayAuth
+        ? {
+            bearerToken: gatewayAuth.bearerToken,
+            gatewayBaseUrl: gatewayAuth.gatewayBaseUrl,
+            gatewayHeaders: gatewayAuth.gatewayHeaders,
+          }
+        : {}),
       ...unipileQueryAuth(runtime),
+      ...(runtime.mode !== "dev"
+        ? {
+            appOrigin: runtime.host,
+            workspaceSlug: runtime.organization?.slug,
+          }
+        : {}),
     });
     return;
   }

package/email.ts

@@ -118,6 +118,134 @@ function requiredFlag(args: string[], name: string): string {
   return value;
 }
 
+/** Default page cap for internally paginated list commands. */
+export const DEFAULT_MAX_PAGES = 1;
+const HARD_MAX_PAGES = 100;
+
+export type PaginatedEnvelope = {
+  page: unknown[];
+  isDone: boolean;
+  continueCursor: string | null;
+};
+
+/**
+ * Drain a Convex `{page, isDone, continueCursor}` pagination envelope for up
+ * to `maxPages` pages. Aborts loudly (instead of looping forever) when the
+ * server returns the same `continueCursor` twice or omits it while
+ * `isDone` is false.
+ */
+export async function collectPaginated(
+  fetchPage: (cursor: string | null) => Promise<PaginatedEnvelope>,
+  options: { maxPages: number },
+): Promise<{
+  rows: unknown[];
+  pagesFetched: number;
+  isDone: boolean;
+  continueCursor: string | null;
+}> {
+  const maxPages = Math.max(
+    1,
+    Math.min(Math.floor(options.maxPages), HARD_MAX_PAGES),
+  );
+  const seenCursors = new Set<string>();
+  const rows: unknown[] = [];
+  let cursor: string | null = null;
+  let pagesFetched = 0;
+  let isDone = false;
+  while (pagesFetched < maxPages) {
+    const result = await fetchPage(cursor);
+    pagesFetched += 1;
+    if (Array.isArray(result?.page)) rows.push(...result.page);
+    isDone = result?.isDone === true;
+    const next =
+      typeof result?.continueCursor === "string" && result.continueCursor
+        ? result.continueCursor
+        : null;
+    cursor = next;
+    if (isDone) break;
+    if (!next) {
+      throw new EmailCliError(
+        "Pagination error: server reported isDone=false but returned no continueCursor. Aborting instead of looping.",
+      );
+    }
+    if (seenCursors.has(next)) {
+      throw new EmailCliError(
+        `Pagination aborted: server returned the same continueCursor twice (${next.slice(0, 24)}…). Refusing to loop; re-run with a smaller --limit or report this.`,
+      );
+    }
+    seenCursors.add(next);
+  }
+  return { rows, pagesFetched, isDone, continueCursor: cursor };
+}
+
+function maxPagesFlag(args: string[]): number {
+  const raw = getFlag(args, "--max-pages");
+  if (raw === undefined) return DEFAULT_MAX_PAGES;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < 1) {
+    throw new EmailCliError("--max-pages must be a positive integer");
+  }
+  return Math.floor(parsed);
+}
+
+type ResolvedCampaignMatch = {
+  campaignId: string;
+  name: string;
+  status: string;
+  recipientCount: number;
+};
+
+async function resolveCampaignByNameQuery(
+  ctx: EmailCliContext,
+  name: string,
+): Promise<{ matchType: string; matches: ResolvedCampaignMatch[] }> {
+  const payload = (await callQuery(
+    ctx,
+    "functions/emailCampaigns:resolveCampaignByName",
+    { name },
+  )) as JsonRecord;
+  return {
+    matchType:
+      typeof payload.matchType === "string" ? payload.matchType : "none",
+    matches: Array.isArray(payload.matches)
+      ? (payload.matches as ResolvedCampaignMatch[])
+      : [],
+  };
+}
+
+function formatCampaignCandidates(matches: ResolvedCampaignMatch[]): string {
+  return matches
+    .map(
+      (match) =>
+        `  ${match.campaignId}  ${JSON.stringify(match.name)}  status=${match.status}  recipients=${match.recipientCount}`,
+    )
+    .join("\n");
+}
+
+/**
+ * Resolve the target campaign for a subcommand: `--campaign <id>` wins;
+ * otherwise `--name "<campaign name>"` is resolved via
+ * resolveCampaignByName and must match exactly one campaign.
+ */
+async function resolveCampaignRef(ctx: EmailCliContext): Promise<string> {
+  const explicit = getFlag(ctx.args, "--campaign")?.trim();
+  if (explicit) return explicit;
+  const name = getFlag(ctx.args, "--name")?.trim();
+  if (!name) {
+    throw new EmailCliError('Pass --campaign <id> or --name "<campaign name>"');
+  }
+  const { matches } = await resolveCampaignByNameQuery(ctx, name);
+  if (matches.length === 1) return matches[0].campaignId;
+  if (matches.length === 0) {
+    throw new EmailCliError(
+      `No campaign matches name ${JSON.stringify(name)}. List campaigns with \`dench email campaign list\` or resolve with \`dench email campaign resolve --name "${name}"\`.`,
+    );
+  }
+  throw new EmailCliError(
+    `Campaign name ${JSON.stringify(name)} is ambiguous (${matches.length} matches). Pass --campaign <id> instead. Candidates:\n${formatCampaignCandidates(matches)}`,
+  );
+}
+
 async function resolveMailboxAccountIds(
   ctx: EmailCliContext,
   mailbox: string,
@@ -249,14 +377,29 @@ Usage:
   dench email template create --name "Intro" --subject "Hi {{firstName}}" --html-file body.html [--text-file body.txt] [--json]
   dench email template preview --template <id> --data '{"firstName":"Ada"}' [--json]
   dench email campaign create --name "Q2 outreach" (--mailbox you@gmail.com | --identity <identityId|fromEmail>) --template <id> [--json]
-  dench email campaign list [--status sending] [--limit 25] [--json]
-  dench email campaign recipients add --campaign <id> --file recipients.jsonl [--json]
-  dench email campaign recipients list --campaign <id> [--status queued] [--limit 50] [--json]
-  dench email campaign recipients add-from-object --campaign <id> --object prospect --email-field "Email" --entries id1,id2 [--json]
-  dench email campaign preview --campaign <id> [--sample 5] [--json]
-  dench email campaign submit --campaign <id> [--json]
-  dench email campaign status --campaign <id> [--json]
-  dench email campaign pause|resume|cancel --campaign <id> [--json]
+  dench email campaign resolve --name "Q2 outreach" [--json]                              # find campaign ids by (fuzzy) name; never creates
+  dench email campaign list [--status sending] [--limit 25] [--max-pages 1] [--json]
+  dench email campaign recipients add (--campaign <id> | --name "<name>") --file recipients.jsonl [--allow-duplicates] [--allow-unlinked] [--json]
+  dench email campaign recipients list (--campaign <id> | --name "<name>") [--status queued] [--limit 50] [--max-pages 1] [--summary] [--json]
+  dench email campaign recipients add-from-object (--campaign <id> | --name "<name>") --object prospect --email-field "Email" --entries id1,id2 [--allow-duplicates] [--json]
+  dench email campaign preview (--campaign <id> | --name "<name>") [--sample 5] [--json]
+  dench email campaign submit (--campaign <id> | --name "<name>") [--json]
+  dench email campaign status (--campaign <id> | --name "<name>") [--json]
+  dench email campaign pause|resume|cancel (--campaign <id> | --name "<name>") [--json]
+
+Campaign recipient safety (on by default):
+  • recipients add / add-from-object SKIP addresses another workspace campaign or
+    sequence already targets (duplicatesElsewhere) or already emailed — including
+    campaigns that have COMPLETED (skippedAlreadySent). --allow-duplicates opts out.
+  • recipients add rejects rows it cannot link to a CRM person/lead (rejected /
+    unlinkedRecipients) — unlinked engagement never syncs to the CRM. Prefer
+    recipients add-from-object, or pass --allow-unlinked to add them anyway.
+
+Pagination: list commands return a {page, isDone, continueCursor} envelope.
+  --limit sets the page size; --max-pages (default 1, this command paginates
+  internally up to that many pages) drains further pages and aborts with an
+  error if the server ever repeats a continueCursor. When isDone=false, pass
+  a larger --max-pages to fetch more.
 
 Sequences (automatic multi-step follow-ups):
   dench email sequence create --name "New-customer follow-up" (--mailbox you@gmail.com | --identity <identityId|fromEmail>) [--stop-on-click] [--no-stop-on-reply] [--json]
@@ -816,20 +959,35 @@ async function runCampaign(ctx: EmailCliContext) {
     );
     return;
   }
+  if (sub === "resolve") {
+    const name = requiredFlag(ctx.args, "--name");
+    const payload = await resolveCampaignByNameQuery(ctx, name);
+    const text =
+      payload.matches.length === 0
+        ? `No campaign matches ${JSON.stringify(name)}.`
+        : `${payload.matches.length} match(es) [${payload.matchType}]:\n${formatCampaignCandidates(payload.matches)}`;
+    out(ctx, { ok: true, ...payload }, text);
+    return;
+  }
   if (sub === "list") {
     const limitRaw = getFlag(ctx.args, "--limit");
     const status = getFlag(ctx.args, "--status");
-    const payload = await callQuery(
-      ctx,
-      "functions/emailCampaigns:listCampaigns",
-      {
-        paginationOpts: {
-          numItems: limitRaw ? Number(limitRaw) : 25,
-          cursor: null,
-        },
-        status,
-      },
+    const maxPages = maxPagesFlag(ctx.args);
+    const numItems = limitRaw ? Number(limitRaw) : 25;
+    const result = await collectPaginated(
+      async (cursor) =>
+        (await callQuery(ctx, "functions/emailCampaigns:listCampaigns", {
+          paginationOpts: { numItems, cursor },
+          status,
+        })) as PaginatedEnvelope,
+      { maxPages },
     );
+    const payload = {
+      page: result.rows,
+      isDone: result.isDone,
+      continueCursor: result.continueCursor,
+      pagesFetched: result.pagesFetched,
+    };
     out(ctx, payload, JSON.stringify(payload, null, 2));
     return;
   }
@@ -838,18 +996,27 @@ async function runCampaign(ctx: EmailCliContext) {
     if (nested === "list") {
       const limitRaw = getFlag(ctx.args, "--limit");
       const status = getFlag(ctx.args, "--status");
-      const payload = await callQuery(
-        ctx,
-        "functions/emailCampaigns:listRecipients",
-        {
-          campaignId: requiredFlag(ctx.args, "--campaign"),
-          paginationOpts: {
-            numItems: limitRaw ? Number(limitRaw) : 50,
-            cursor: null,
-          },
-          status,
-        },
+      const summary = hasFlag(ctx.args, "--summary");
+      const maxPages = maxPagesFlag(ctx.args);
+      const campaignId = await resolveCampaignRef(ctx);
+      const numItems = limitRaw ? Number(limitRaw) : 50;
+      const result = await collectPaginated(
+        async (cursor) =>
+          (await callQuery(ctx, "functions/emailCampaigns:listRecipients", {
+            campaignId,
+            paginationOpts: { numItems, cursor },
+            status,
+            // --summary skips the per-row CRM person attachment server-side.
+            includePeople: summary ? false : undefined,
+          })) as PaginatedEnvelope,
+        { maxPages },
       );
+      const payload = {
+        page: result.rows,
+        isDone: result.isDone,
+        continueCursor: result.continueCursor,
+        pagesFetched: result.pagesFetched,
+      };
       out(ctx, payload, JSON.stringify(payload, null, 2));
       return;
     }
@@ -858,10 +1025,18 @@ async function runCampaign(ctx: EmailCliContext) {
         ctx,
         "functions/emailCampaigns:addRecipientsFromCrm",
         {
-          campaignId: requiredFlag(ctx.args, "--campaign"),
+          campaignId: await resolveCampaignRef(ctx),
           objectName: requiredFlag(ctx.args, "--object"),
           emailFieldName: getFlag(ctx.args, "--email-field"),
           entryIds: parseEntryIds(requiredFlag(ctx.args, "--entries")),
+          // Cross-campaign duplicate + already-sent check is ON by default;
+          // --allow-duplicates opts out.
+          checkDuplicatesAcrossWorkspace: hasFlag(
+            ctx.args,
+            "--allow-duplicates",
+          )
+            ? false
+            : undefined,
         },
       );
       out(ctx, payload, JSON.stringify(payload, null, 2));
@@ -872,19 +1047,58 @@ async function runCampaign(ctx: EmailCliContext) {
         "Usage: dench email campaign recipients add|list|add-from-object",
       );
     }
-    const campaignId = requiredFlag(ctx.args, "--campaign");
+    const campaignId = await resolveCampaignRef(ctx);
     const file = getFlag(ctx.args, "--file");
     const rows = file
       ? await readRecipients(file)
       : ((optionalJsonFlag(ctx.args, "--data") as JsonRecord[] | undefined) ??
         []);
     if (rows.length === 0) throw new EmailCliError("No recipients provided");
-    const payload = await callMutation(
+    const allowUnlinked = hasFlag(ctx.args, "--allow-unlinked");
+    const payload = (await callMutation(
       ctx,
       "functions/emailCampaigns:addRecipients",
-      { campaignId, recipients: toRecipients(rows) },
-    );
-    out(ctx, payload, JSON.stringify(payload, null, 2));
+      {
+        campaignId,
+        recipients: toRecipients(rows),
+        // Cross-campaign duplicate + already-sent check is ON by default;
+        // --allow-duplicates opts out.
+        checkDuplicatesAcrossWorkspace: hasFlag(ctx.args, "--allow-duplicates")
+          ? false
+          : undefined,
+        allowUnlinked: allowUnlinked ? true : undefined,
+      },
+    )) as JsonRecord;
+    const rejected = Array.isArray(payload.rejected)
+      ? (payload.rejected as string[])
+      : [];
+    const shaped: JsonRecord = {
+      ...payload,
+      added: payload.added,
+      skippedAlreadySent: payload.alreadySent ?? 0,
+      skippedSuppressed: payload.suppressed ?? 0,
+      skippedInvalid: payload.invalid ?? 0,
+      skippedInCampaign: payload.duplicates ?? 0,
+      skippedInOtherLiveCampaigns: payload.duplicatesElsewhere ?? 0,
+      unlinkedRecipients: rejected.length,
+    };
+    const warnings: string[] = [];
+    if (rejected.length > 0) {
+      warnings.push(
+        `WARNING: unlinkedRecipients: ${rejected.length} — these rows could not be linked to a CRM person/lead and were NOT added; engagement for unlinked recipients will NOT sync to the CRM. Prefer \`recipients add-from-object\` (CRM-linked) or re-run with --allow-unlinked to add them anyway.`,
+        ...rejected.slice(0, 20).map((email) => `  rejected: ${email}`),
+        ...(rejected.length > 20
+          ? [`  … and ${rejected.length - 20} more`]
+          : []),
+      );
+    }
+    if ((shaped.skippedAlreadySent as number) > 0) {
+      warnings.push(
+        `Skipped ${shaped.skippedAlreadySent} recipient(s) already emailed by another campaign in this workspace (pass --allow-duplicates to re-send).`,
+      );
+    }
+    if (warnings.length > 0) shaped.warnings = warnings;
+    out(ctx, shaped, [JSON.stringify(shaped, null, 2), ...warnings].join("\n"));
     return;
   }
   if (sub === "preview") {
@@ -893,7 +1107,7 @@ async function runCampaign(ctx: EmailCliContext) {
       ctx,
       "functions/emailCampaigns:previewCampaign",
       {
-        campaignId: requiredFlag(ctx.args, "--campaign"),
+        campaignId: await resolveCampaignRef(ctx),
         sample: sampleRaw ? Number(sampleRaw) : undefined,
       },
     );
@@ -905,19 +1119,19 @@ async function runCampaign(ctx: EmailCliContext) {
       ctx,
       "functions/emailCampaigns:submitCampaign",
       {
-        campaignId: requiredFlag(ctx.args, "--campaign"),
+        campaignId: await resolveCampaignRef(ctx),
         approvalId: getFlag(ctx.args, "--approval"),
       },
     );
     out(ctx, payload, JSON.stringify(payload, null, 2));
     return;
   }
-  if (sub === "status") {
+  if (sub === "status" || sub === "get") {
     const payload = await callQuery(
       ctx,
       "functions/emailCampaigns:getCampaign",
       {
-        campaignId: requiredFlag(ctx.args, "--campaign"),
+        campaignId: await resolveCampaignRef(ctx),
       },
     );
     out(ctx, payload, JSON.stringify(payload, null, 2));
@@ -931,13 +1145,13 @@ async function runCampaign(ctx: EmailCliContext) {
           ? "resumeCampaign"
           : "cancelCampaign";
     const payload = await callMutation(ctx, `functions/emailCampaigns:${fn}`, {
-      campaignId: requiredFlag(ctx.args, "--campaign"),
+      campaignId: await resolveCampaignRef(ctx),
     });
     out(ctx, payload, JSON.stringify(payload, null, 2));
     return;
   }
   throw new EmailCliError(
-    "Usage: dench email campaign create|list|recipients|preview|submit|status|pause|resume|cancel",
+    "Usage: dench email campaign create|resolve|list|recipients|preview|submit|status|pause|resume|cancel",
   );
 }
 

package/lib/cli-args.ts

@@ -89,6 +89,47 @@ export function parseJson(value: string | undefined): unknown {
   }
 }
 
+export type ParsedLimit = {
+  /** What the caller asked for (or the default when --limit was absent). */
+  requested: number;
+  /** What will actually be sent to the server (requested clamped to cap). */
+  effective: number;
+  /** True when requested exceeded the cap and was silently reduced. */
+  clamped: boolean;
+};
+
+/**
+ * Parse a `--limit` value against a server-side row cap.
+ *
+ * Servers clamp silently (e.g. `crm query` caps at 1000, `crm search`
+ * at 100), which historically let agents believe a `--limit 5000` call
+ * returned the full dataset — dedupe/count scripts then operated on a
+ * subset and deleted real rows. The caller MUST surface
+ * `clamped === true` to the user (stderr warning and/or a
+ * `limitClamped` field in JSON output).
+ */
+export function parseLimit(
+  raw: string | undefined,
+  opts: { defaultValue: number; cap: number; command: string },
+): ParsedLimit {
+  if (raw === undefined) {
+    const effective = Math.min(opts.defaultValue, opts.cap);
+    return { requested: effective, effective, clamped: false };
+  }
+  const requested = Number.parseInt(raw, 10);
+  if (
+    !Number.isFinite(requested) ||
+    requested < 1 ||
+    String(requested) !== raw.trim()
+  ) {
+    throw new CliArgError(
+      `--limit must be a positive integer for ${opts.command}, got "${raw}"`,
+    );
+  }
+  const effective = Math.min(requested, opts.cap);
+  return { requested, effective, clamped: effective < requested };
+}
+
 export function assertNoUnknownFlags(
   args: readonly string[],
   command: string,

package/lib/command-registry.ts

@@ -2549,7 +2549,8 @@ const rawApiOperations = [
     group: "gateway",
     summary:
       "List every connected integration — Composio apps plus the Gmail, " +
-      "Outlook, Calendar and LinkedIn accounts Dench connects itself.",
+      "Outlook, Calendar, LinkedIn and Slack connections Dench brokers " +
+      "itself (Slack rows report source: dench).",
     cli: "dench integrations",
     method: "GET",
     path: "/integrations",
@@ -2659,7 +2660,11 @@ const rawApiOperations = [
   op({
     id: "tool.connect",
     group: "gateway",
-    summary: "Create a tool OAuth connection link.",
+    summary:
+      "Create a tool OAuth connection link. Slack is in-house, never " +
+      "Composio: for toolkit slack the CLI prints the first-party install " +
+      "URL (/api/slack/install?slug=<workspace>, org admin) instead of " +
+      "calling this endpoint.",
     cli: "dench tool connect",
     method: "POST",
     path: "/tools/connections",
@@ -2681,7 +2686,12 @@ const rawApiOperations = [
   op({
     id: "tool.run",
     group: "gateway",
-    summary: "Run an external tool action.",
+    summary:
+      "Run an external tool action. SLACK_* slugs (SLACK_SEND_MESSAGE " +
+      "with Block Kit blocks/buttons, SLACK_FETCH_HISTORY, " +
+      "SLACK_LIST_CHANNELS, …) run through Dench's in-house Slack app " +
+      "install — any channel in the connected workspace — and are always " +
+      "preferred over Composio Slack.",
     cli: "dench tool run",
     method: "POST",
     path: "/tools/run",