@dench.com/cli 2.7.5 → 2.7.6-staging.1

package/lib/exa-search-constraints.ts

@@ -0,0 +1,70 @@
+/**
+ * Which Exa `/search` params are unusable per `category`.
+ *
+ * MEASURED against the live API on 2026-08-12, because the published docs are
+ * wrong in both directions and the two categories do NOT share a list:
+ *
+ * | param              | category: "people"        | category: "company"   |
+ * |--------------------|---------------------------|-----------------------|
+ * | includeDomains     | 200, then SILENTLY IGNORED| 200, genuinely applied|
+ * | excludeDomains     | HTTP 400                  | 200, genuinely applied|
+ * | startPublishedDate | HTTP 400                  | HTTP 400              |
+ * | endPublishedDate   | HTTP 400                  | HTTP 400              |
+ *
+ * The docs claim all four 400 for people (wrong: `includeDomains` does not)
+ * and that `excludeDomains` 400s for company (wrong: it works). Verified by
+ * observation, not by reading: `includeDomains: ["github.com"]` on a people
+ * search returned five linkedin.com profiles, while the same filter on a
+ * company search returned zero results, and `excludeDomains: ["stripe.com"]`
+ * removed Stripe from a company search that otherwise ranked it first.
+ *
+ * The silently-ignored case is the dangerous one — a caller gets plausible
+ * results and no signal their filter did nothing — so it is listed here
+ * alongside the hard failures even though it does not error. Domain filters
+ * are deliberately NOT listed for company, because there they work.
+ */
+export const EXA_UNSUPPORTED_PARAMS_BY_CATEGORY: Record<
+  string,
+  readonly string[]
+> = {
+  people: [
+    "includeDomains",
+    "excludeDomains",
+    "startPublishedDate",
+    "endPublishedDate",
+  ],
+  company: ["startPublishedDate", "endPublishedDate"],
+};
+
+/** Params unusable for `category`; empty for categories with no restrictions. */
+export function unsupportedParamsForCategory(
+  category: string | undefined,
+): readonly string[] {
+  if (!category) return [];
+  return EXA_UNSUPPORTED_PARAMS_BY_CATEGORY[category] ?? [];
+}
+
+/**
+ * Delete the params that do not work for this category, returning what was
+ * removed so the caller can report it. Mutates `body`; a no-op for
+ * unrestricted categories.
+ *
+ * Callers deliberately differ in how they use the return value: the agent
+ * workflow step strips silently and reports `droppedParams` (a model cannot
+ * foresee a provider incompatibility, and a hard 400 costs it a whole turn),
+ * while `dench search` refuses outright (a human who typed the flag meant it,
+ * and neither erroring nor silently ignoring it is an acceptable answer).
+ */
+export function stripUnsupportedParamsForCategory(
+  body: Record<string, unknown>,
+  category: string | undefined,
+): string[] {
+  const dropped: string[] = [];
+  for (const key of unsupportedParamsForCategory(category)) {
+    if (body[key] !== undefined) {
+      delete body[key];
+      dropped.push(key);
+    }
+  }
+  return dropped;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dench.com/cli",
-  "version": "2.7.5",
+  "version": "2.7.6-staging.1",
   "description": "Dench agent workspace CLI.",
   "type": "module",
   "bin": {

package/search.ts

@@ -10,12 +10,32 @@
  *   search "<query>"       [--num-results N] [--type auto|fast|deep|deep-reasoning|neural]
  *                          [--category news|company|people|...]
  *                          [--include-domains a.com,b.com] [--exclude-domains c.com]
+ *                          [--start-published-date ISO] [--end-published-date ISO]
  *                          [--max-chars 800] [--json]
  *   search contents <url> [<url>...] [--max-chars 4000] [--summary "..."] [--json]
  *   search answer "<query>" [--json]
+ *
+ * `--category people` and `--category company` upgrade the SAME search rather
+ * than being separate subcommands: those categories hit Exa's dedicated entity
+ * indices, so the results are structured records and are rendered as such.
+ *
+ * Filter support is PER-CATEGORY and measured, not guessed: people search
+ * cannot use domain or published-date filters, while company search uses
+ * domain filters happily and only loses the date ones. See
+ * cli/lib/exa-search-constraints.ts for the observed behaviour. This CLI
+ * refuses an unusable flag; the agent-side equivalent
+ * (src/workflows/exa-web-steps.ts) strips it instead — that file explains why
+ * the two surfaces deliberately differ.
  */
 
-import { getFlag } from "./lib/cli-args";
+import { assertNoUnknownFlags, getFlag } from "./lib/cli-args";
+import { formatUsdCompact, parseExaCompanyResults } from "./lib/exa-companies";
+import {
+  currentRole,
+  parseExaPeopleResults,
+  personFullName,
+} from "./lib/exa-people";
+import { unsupportedParamsForCategory } from "./lib/exa-search-constraints";
 
 type SearchCliContext = {
   args: string[];
@@ -65,6 +85,40 @@ const ALLOWED_CATEGORIES = new Set([
   "people",
 ]);
 
+/** CLI flag → the Exa request param it sets. */
+const FLAG_TO_EXA_PARAM: Record<string, string> = {
+  "--include-domains": "includeDomains",
+  "--exclude-domains": "excludeDomains",
+  "--start-published-date": "startPublishedDate",
+  "--end-published-date": "endPublishedDate",
+};
+
+/**
+ * Refuse flags that do not work for the requested category. The list is
+ * per-category and measured, not guessed — domain filters are unusable for
+ * people but genuinely work for company.
+ */
+function assertFlagsSupportedForCategory(
+  category: string | undefined,
+  provided: string[],
+): void {
+  const unsupported = new Set(unsupportedParamsForCategory(category));
+  const offenders = provided.filter((flag) =>
+    unsupported.has(FLAG_TO_EXA_PARAM[flag] ?? ""),
+  );
+  if (offenders.length === 0) return;
+  throw new SearchCliError(
+    `${offenders.join(", ")} has no effect on ${category} search — Exa ` +
+      "either rejects it or silently ignores it, so the results would not " +
+      "match what you asked for. (Unsupported for " +
+      `${category}: ${[...unsupported].join(", ")}.) ` +
+      "Put those constraints in the query text instead, e.g. " +
+      (category === "company"
+        ? '`dench search "Swiss fintech founded after 2020" --category company`.'
+        : '`dench search "engineers at Stripe in Dublin" --category people`.'),
+  );
+}
+
 function normalizeGatewayBaseUrl(value: string): string {
   return value.replace(/\/+$/, "").replace(/\/v1$/, "");
 }
@@ -216,6 +270,96 @@ function formatSearchResults(payload: unknown, limit?: number): string {
   return lines.join("\n").trimEnd();
 }
 
+/**
+ * Render Exa people results from their structured `entities`, not page text.
+ * Each line is name · current title · company · location, so a list-building
+ * run is readable without `--json`.
+ */
+function formatPeopleResults(payload: unknown, limit?: number): string {
+  const hits = parseExaPeopleResults(payload);
+  const lines: string[] = [];
+  const auto = asString(asObject(payload)?.autopromptString);
+  if (auto) {
+    lines.push(`Auto-prompt: ${auto}`);
+    lines.push("");
+  }
+  if (hits.length === 0) {
+    lines.push("(no people found)");
+    return lines.join("\n");
+  }
+  const cap = limit !== undefined ? Math.min(hits.length, limit) : hits.length;
+  for (let i = 0; i < cap; i++) {
+    const hit = hits[i];
+    const role = currentRole(hit.person);
+    const name = personFullName(hit.person) ?? hit.title ?? "(unnamed)";
+    const roleLine = [role?.title, role?.company?.name]
+      .filter(Boolean)
+      .join(" · ");
+    lines.push(`${i + 1}. ${name}`);
+    if (roleLine) lines.push(`   ${roleLine}`);
+    if (hit.person.location) lines.push(`   ${hit.person.location}`);
+    if (hit.url) lines.push(`   ${hit.url}`);
+    lines.push("");
+  }
+  const cost = asNumber(asObject(asObject(payload)?.costDollars)?.total);
+  if (cost !== undefined) lines.push(`Cost (USD): $${cost.toFixed(4)}`);
+  return lines.join("\n").trimEnd();
+}
+
+/**
+ * Render Exa company results from their structured `entities`. One line of
+ * firmographics per company so an account-list run is readable without
+ * `--json`.
+ */
+function formatCompanyResults(payload: unknown, limit?: number): string {
+  const hits = parseExaCompanyResults(payload);
+  const lines: string[] = [];
+  const auto = asString(asObject(payload)?.autopromptString);
+  if (auto) {
+    lines.push(`Auto-prompt: ${auto}`);
+    lines.push("");
+  }
+  if (hits.length === 0) {
+    lines.push("(no companies found)");
+    return lines.join("\n");
+  }
+  const cap = limit !== undefined ? Math.min(hits.length, limit) : hits.length;
+  for (let i = 0; i < cap; i++) {
+    const { company, url, title } = hits[i];
+    const hq = company.headquarters;
+    const facts = [
+      company.foundedYear ? `founded ${company.foundedYear}` : null,
+      company.headcount
+        ? `${company.headcount.toLocaleString()} employees`
+        : null,
+      [hq?.city, hq?.country].filter(Boolean).join(", ") || null,
+    ].filter(Boolean);
+    const money = [
+      company.financials?.fundingTotal
+        ? `raised ${formatUsdCompact(company.financials.fundingTotal)}`
+        : null,
+      company.financials?.fundingLatestRound?.name
+        ? `latest ${company.financials.fundingLatestRound.name}`
+        : null,
+      company.financials?.revenueAnnual
+        ? `revenue ${formatUsdCompact(company.financials.revenueAnnual)}`
+        : null,
+    ].filter(Boolean);
+
+    lines.push(`${i + 1}. ${company.name ?? title ?? "(unnamed)"}`);
+    if (url) lines.push(`   ${url}`);
+    if (facts.length > 0) lines.push(`   ${facts.join("  ·  ")}`);
+    if (money.length > 0) lines.push(`   ${money.join("  ·  ")}`);
+    if (company.description) {
+      lines.push(`   ${trimSnippet(company.description, 200)}`);
+    }
+    lines.push("");
+  }
+  const cost = asNumber(asObject(asObject(payload)?.costDollars)?.total);
+  if (cost !== undefined) lines.push(`Cost (USD): $${cost.toFixed(4)}`);
+  return lines.join("\n").trimEnd();
+}
+
 function formatContentsResults(payload: unknown): string {
   const root = asObject(payload);
   if (!root) return "(no contents)";
@@ -303,32 +447,61 @@ async function runSearchSubcommand(ctx: SearchCliContext): Promise<void> {
       `Invalid --category: ${category}. Allowed: ${[...ALLOWED_CATEGORIES].join(", ")}`,
     );
   }
-  const includeDomains = splitCsv(getFlag(ctx.args, "--include-domains"));
-  const excludeDomains = splitCsv(getFlag(ctx.args, "--exclude-domains"));
+  const rawIncludeDomains = getFlag(ctx.args, "--include-domains");
+  const rawExcludeDomains = getFlag(ctx.args, "--exclude-domains");
+  const startPublishedDate = getFlag(ctx.args, "--start-published-date");
+  const endPublishedDate = getFlag(ctx.args, "--end-published-date");
+  assertFlagsSupportedForCategory(
+    category,
+    [
+      rawIncludeDomains !== undefined ? "--include-domains" : null,
+      rawExcludeDomains !== undefined ? "--exclude-domains" : null,
+      startPublishedDate !== undefined ? "--start-published-date" : null,
+      endPublishedDate !== undefined ? "--end-published-date" : null,
+    ].filter((flag): flag is string => flag !== null),
+  );
+  const includeDomains = splitCsv(rawIncludeDomains);
+  const excludeDomains = splitCsv(rawExcludeDomains);
   const maxChars =
     parsePositiveInt("--max-chars", getFlag(ctx.args, "--max-chars")) ?? 800;
+  assertNoUnknownFlags(ctx.args, "search");
   const queryParts = ctx.args.slice();
   ctx.args.length = 0;
   const query = queryParts.join(" ").trim();
   if (!query) {
     throw new SearchCliError(
-      'Usage: dench search "<query>" [--num-results N] [--type auto|fast|deep|deep-reasoning] [--category ...] [--include-domains a.com,b.com] [--exclude-domains c.com] [--max-chars 800] [--json]',
+      'Usage: dench search "<query>" [--num-results N] [--type auto|fast|deep|deep-reasoning] [--category ...] [--include-domains a.com,b.com] [--exclude-domains c.com] [--start-published-date ISO] [--end-published-date ISO] [--max-chars 800] [--json]',
     );
   }
+  // `people` and `company` hit Exa's dedicated entity indices, which return
+  // structured records rather than pages. Full page text adds nothing there —
+  // the typed fields are the point — so contents are trimmed to highlights
+  // and the output is rendered from the entities instead of snippets.
+  const isEntitySearch = category === "people" || category === "company";
   const body: Record<string, unknown> = {
     query,
     numResults: numResults ?? 10,
     type: type ?? "auto",
-    contents: {
-      text: { maxCharacters: maxChars },
-      highlights: { maxCharacters: 200 },
-    },
+    contents: isEntitySearch
+      ? { highlights: { maxCharacters: 200 } }
+      : {
+          text: { maxCharacters: maxChars },
+          highlights: { maxCharacters: 200 },
+        },
   };
   if (category) body.category = category;
   if (includeDomains) body.includeDomains = includeDomains;
   if (excludeDomains) body.excludeDomains = excludeDomains;
+  if (startPublishedDate) body.startPublishedDate = startPublishedDate;
+  if (endPublishedDate) body.endPublishedDate = endPublishedDate;
   const payload = await callGateway(ctx, "/v1/search", body);
-  out(ctx, payload, formatSearchResults(payload, numResults));
+  const rendered =
+    category === "people"
+      ? formatPeopleResults(payload, numResults)
+      : category === "company"
+        ? formatCompanyResults(payload, numResults)
+        : formatSearchResults(payload, numResults);
+  out(ctx, payload, rendered);
 }
 
 async function runContentsSubcommand(ctx: SearchCliContext): Promise<void> {
@@ -385,8 +558,30 @@ Search the web (default subcommand):
   dench search "<query>" [--num-results N] [--type auto|fast|deep|deep-reasoning|neural]
                          [--category news|company|people|...]
                          [--include-domains a.com,b.com] [--exclude-domains c.com]
+                         [--start-published-date ISO] [--end-published-date ISO]
                          [--max-chars 800] [--json]
 
+Find people or companies (--category people|company):
+  Those two categories search dedicated indices and print STRUCTURED
+  records instead of page snippets — people give name, current title,
+  company, location, work history and education; companies give domain,
+  description, founded year, headcount, HQ, total funding, latest round
+  and revenue. Neither returns emails or phone numbers.
+
+  Put every constraint in the query text: role, seniority, skill,
+  company, industry, location, funding stage and founding year all work.
+  Similarity queries work well for companies.
+
+    dench search "senior ML engineers at fintech companies" --category people
+    dench search "VP Engineering AI infrastructure SF" --category people
+    dench search "fintech companies in Switzerland" --category company
+    dench search "companies like Notion" --category company
+
+  Filter support differs by category: --include-domains/--exclude-domains
+  work with --category company but NOT with --category people, and
+  published-date filters work with neither. Passing one that does not
+  apply is refused rather than silently ignored.
+
 Deep-read one or more URLs (Exa /search/contents):
   dench search contents <url> [<url>...] [--max-chars 4000] [--summary "..."] [--json]