deepline 0.1.261 → 0.1.263

package/dist/bundling-sources/sdk/src/release.ts

@@ -123,7 +123,7 @@ export const SDK_RELEASE = {
   // Deepline-native radars. Older clients must update before discovering,
   // checking, or deploying an unlaunched monitor integration.
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
-  version: '0.1.261',
+  version: '0.1.263',
   apiContract: '2026-07-native-monitor-launch-hard-cutover',
   supportPolicy: {
     minimumSupported: '0.1.53',

package/dist/bundling-sources/shared_libs/play-runtime/row-isolation.ts

@@ -1,5 +1,6 @@
 import { isHardBillingToolHttpError } from './tool-http-errors';
 import { isRuntimePersistenceCircuitOpenError } from './persistence-latch';
+import { isWorkspaceStorageNotReadyFailure } from './run-failure';
 
 /**
  * Thrown by runner Adapters when a Play Run is externally cancelled. Row
@@ -41,6 +42,7 @@ export function isRowIsolationExemptError(error: unknown): boolean {
   if (isRuntimeReceiptPersistenceError(error)) return true;
   if (isRuntimeStoragePersistenceError(error)) return true;
   if (isRuntimePersistenceCircuitOpenError(error)) return true;
+  if (isWorkspaceStorageNotReadyFailure(error)) return true;
   return isHardBillingToolHttpError(error);
 }
 

package/dist/bundling-sources/shared_libs/play-runtime/run-failure.ts

@@ -59,6 +59,24 @@ export class WorkspaceStorageNotReadyError extends Error {
   }
 }
 
+export function isWorkspaceStorageNotReadyFailure(error: unknown): boolean {
+  if (error instanceof WorkspaceStorageNotReadyError) return true;
+  if (!error) return false;
+  if (typeof error === 'object') {
+    const code = (error as { code?: unknown }).code;
+    if (code === WORKSPACE_STORAGE_NOT_READY_CODE) return true;
+    const nestedErrors = (error as { errors?: unknown }).errors;
+    if (
+      Array.isArray(nestedErrors) &&
+      nestedErrors.some(isWorkspaceStorageNotReadyFailure)
+    ) {
+      return true;
+    }
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return /\bWORKSPACE_STORAGE_NOT_READY\b/.test(message);
+}
+
 export const PROVIDER_EXHAUSTED_CODE = 'PROVIDER_EXHAUSTED';
 
 /**
@@ -331,7 +349,7 @@ export function normalizePlayRunFailure(error: unknown): PlayRunFailureDetails {
     };
   }
   if (
-    error instanceof WorkspaceStorageNotReadyError ||
+    isWorkspaceStorageNotReadyFailure(error) ||
     /\bWORKSPACE_STORAGE_NOT_READY\b/.test(rawCause)
   ) {
     return {

package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/backends/daytona.ts

@@ -490,6 +490,25 @@ function isRetryableDaytonaInfrastructureFailure(error: unknown): boolean {
   return DAYTONA_INFRASTRUCTURE_RETRY_PATTERN.test(message);
 }
 
+function isRetryableUnstartedDaytonaRunner(
+  error: unknown,
+): error is DaytonaRunnerInitializationError {
+  if (!(error instanceof DaytonaRunnerInitializationError)) return false;
+  const diagnostic = error.startupDiagnostic;
+  // The sandbox runner cannot execute customer code until the worker observes
+  // its heartbeat, parks the scheduler attempt, and the gateway acknowledges
+  // that waiting state. If no heartbeat was observed and Daytona has no exit
+  // evidence, deleting this fenced sandbox and retrying once cannot duplicate
+  // customer side effects.
+  return (
+    diagnostic.commandFound &&
+    diagnostic.sessionFound &&
+    diagnostic.exitCode === null &&
+    diagnostic.exitCodeFile === null &&
+    !diagnostic.schedulerReadinessObserved
+  );
+}
+
 function prepareDaytonaExecution(
   input: PlayRunnerPrepareInput,
   callbacks: Parameters<PlayRunnerBackend['execute']>[1],
@@ -930,14 +949,19 @@ export const daytonaPlayRunnerBackend: PlayRunnerBackend = {
             onCancel();
             throw new Error(DAYTONA_CANCELLED_ERROR);
           }
+          const retryReason = isRetryableUnstartedDaytonaRunner(error)
+            ? 'runner_startup_not_live'
+            : isRetryableDaytonaInfrastructureFailure(error)
+              ? 'daytona_infrastructure'
+              : null;
           if (
             executionAttempt < DAYTONA_INFRASTRUCTURE_MAX_ATTEMPTS &&
-            isRetryableDaytonaInfrastructureFailure(error)
+            retryReason
           ) {
             emitDaytonaStage(callbacks, config.context, 'execute:retry', {
               sandboxId: sandboxForAttempt?.id ?? null,
               attempt: executionAttempt + 1,
-              reason: 'daytona_infrastructure',
+              reason: retryReason,
               error: error instanceof Error ? error.message : String(error),
               elapsedMs: Date.now() - startedAt,
             });

package/dist/bundling-sources/shared_libs/plays/tool-category-descriptions.ts

@@ -0,0 +1,51 @@
+// One-line definitions for the tool categories surfaced by `deepline tools list`.
+//
+// Tool categories are free-form strings that each provider tool declares in the
+// generated catalog (see `src/lib/integrations/**`), not a single closed enum.
+// The canonical set of well-known category slugs lives next to this file in
+// `DEEPLINE_TOOL_CATEGORIES` (bootstrap-routes.ts) and in the richer
+// `IntegrationCatalogTag` enum (src/lib/integrations/catalog-tags.ts). This map
+// MUST track the categories that actually appear on live tools. The CLI derives
+// the category enumeration from the live catalog, so a new category slug shows
+// up automatically; only its human-readable definition comes from here. When a
+// category has no entry the CLI renders it without a definition (never invents
+// one), which is the loud signal to add it here.
+//
+// Keep each definition to a single, plain sentence fragment.
+
+export const TOOL_CATEGORY_DESCRIPTIONS: Readonly<Record<string, string>> = {
+  company_search: 'Find companies matching firmographic, ad, or web criteria.',
+  people_search: 'Find people matching role, company, or persona criteria.',
+  people_enrich:
+    'Enrich a known person with contact, social, and profile data.',
+  company_enrich: 'Enrich a known company with firmographic and account data.',
+  email_finder: 'Find work or personal email addresses for a person.',
+  email_verify: 'Validate email deliverability and catch-all status.',
+  phone_finder: 'Find mobile or direct phone numbers for a person.',
+  phone_verify: 'Validate phone-number reachability and line type.',
+  research:
+    'Research accounts, people, news, and signals for context and scoring.',
+  autocomplete: 'Resolve names and entities to canonical catalog records.',
+  automation:
+    'Kick off provider-side jobs, exports, and asynchronous workflows.',
+  outbound_tools:
+    'Run outbound sequencing, deliverability, and campaign operations.',
+  admin:
+    'Provider-side status, metadata, and account operations behind other tools.',
+  smb: 'Look up small-business listings, local records, and public filings.',
+  identity_resolution:
+    'Match a partial identity to a single resolved person or company.',
+  reverse_lookup: 'Resolve an email, phone, or profile back to a person.',
+  enrichment: 'General-purpose record enrichment across people and companies.',
+  batch: 'Run an enrichment or search operation over many rows at once.',
+  premium: 'Higher-cost tools with premium provider coverage.',
+  free: 'Free tools that do not spend Deepline credits.',
+};
+
+/**
+ * One-line definition for a tool category slug, or null when none is declared.
+ * Never fabricates a definition for unknown slugs.
+ */
+export function describeToolCategory(category: string): string | null {
+  return TOOL_CATEGORY_DESCRIPTIONS[category] ?? null;
+}

package/dist/cli/index.js

@@ -716,7 +716,7 @@ var SDK_RELEASE = {
   // Deepline-native radars. Older clients must update before discovering,
   // checking, or deploying an unlaunched monitor integration.
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
-  version: "0.1.261",
+  version: "0.1.263",
   apiContract: "2026-07-native-monitor-launch-hard-cutover",
   supportPolicy: {
     minimumSupported: "0.1.53",
@@ -12465,13 +12465,21 @@ function getStatusFromLiveEvent(event) {
   const payload = getEventPayload(event);
   return playStatusValue(payload.status) ?? playStatusValue(getRunRecordFromPackage(payload)?.status);
 }
+function getWaitKindFromLiveEvent(event) {
+  const payload = getEventPayload(event);
+  const progress = payload.progress && typeof payload.progress === "object" ? payload.progress : null;
+  const waitKind = payload.waitKind ?? progress?.waitKind;
+  return typeof waitKind === "string" && waitKind.trim() ? waitKind.trim() : null;
+}
 function writePlayWaitingHint(input2) {
   if (getStatusFromLiveEvent(input2.event) !== "waiting") return;
   const runId = getRunIdFromLiveEvent(input2.event);
   if (!runId || input2.state.waitingRunId === runId) return;
   input2.state.waitingRunId = runId;
+  const waitKind = getWaitKindFromLiveEvent(input2.event);
+  const message = waitKind === "integration_event" || waitKind === "integration_event_batch" ? "is waiting for an external event." : waitKind === "sleep" ? "is waiting for its scheduled resume." : waitKind === "detached_runner" ? "is executing in the runtime." : "is waiting on a durable runtime boundary.";
   input2.progress.writeLine(
-    `[play waiting] ${runId} is waiting for an external approval or event. The command will continue watching; inspect it with 'deepline runs get ${runId} --full --json'.`
+    `[play waiting] ${runId} ${message} The command will continue watching; inspect it with 'deepline runs get ${runId} --full --json'.`
   );
 }
 function getFinalStatusFromLiveEvent(event) {
@@ -12734,6 +12742,9 @@ function getRunningHeartbeatLine(input2) {
     return `queued ${target}: waiting for worker capacity`;
   }
   if (status === "waiting") {
+    if (getWaitKindFromLiveEvent(input2.event) === "detached_runner") {
+      return `running ${target}: executing in detached runtime`;
+    }
     return `waiting ${target}: waiting on external work`;
   }
   return `running ${target}: still processing`;
@@ -26616,6 +26627,33 @@ function extractSummaryFields(payload) {
   return {};
 }
 
+// ../shared_libs/plays/tool-category-descriptions.ts
+var TOOL_CATEGORY_DESCRIPTIONS = {
+  company_search: "Find companies matching firmographic, ad, or web criteria.",
+  people_search: "Find people matching role, company, or persona criteria.",
+  people_enrich: "Enrich a known person with contact, social, and profile data.",
+  company_enrich: "Enrich a known company with firmographic and account data.",
+  email_finder: "Find work or personal email addresses for a person.",
+  email_verify: "Validate email deliverability and catch-all status.",
+  phone_finder: "Find mobile or direct phone numbers for a person.",
+  phone_verify: "Validate phone-number reachability and line type.",
+  research: "Research accounts, people, news, and signals for context and scoring.",
+  autocomplete: "Resolve names and entities to canonical catalog records.",
+  automation: "Kick off provider-side jobs, exports, and asynchronous workflows.",
+  outbound_tools: "Run outbound sequencing, deliverability, and campaign operations.",
+  admin: "Provider-side status, metadata, and account operations behind other tools.",
+  smb: "Look up small-business listings, local records, and public filings.",
+  identity_resolution: "Match a partial identity to a single resolved person or company.",
+  reverse_lookup: "Resolve an email, phone, or profile back to a person.",
+  enrichment: "General-purpose record enrichment across people and companies.",
+  batch: "Run an enrichment or search operation over many rows at once.",
+  premium: "Higher-cost tools with premium provider coverage.",
+  free: "Free tools that do not spend Deepline credits."
+};
+function describeToolCategory(category) {
+  return TOOL_CATEGORY_DESCRIPTIONS[category] ?? null;
+}
+
 // src/cli/commands/model-description.ts
 function formatModelDescription(description) {
   const lines = [];
@@ -26782,21 +26820,181 @@ function zeroMatchRender(emptyResult) {
     ]
   };
 }
-async function listTools(args) {
+function firstSentence(text) {
+  const clean = (text ?? "").replace(/\s+/g, " ").trim();
+  if (!clean) return "";
+  const match = clean.match(/^.*?[.!?](?=\s|$)/);
+  return (match ? match[0] : clean).trim();
+}
+function requiredInputIds(tool) {
+  const inputSchema = recordField2(
+    tool,
+    "inputSchema",
+    "input_schema"
+  );
+  return toolInputFieldsForDisplay(inputSchema).filter((field) => field.required === true).map((field) => String(field.name ?? "")).filter(Boolean);
+}
+function shortPricingHint(tool) {
+  const pricing = recordField2(
+    tool,
+    "pricing"
+  );
+  const credits = numberField2(pricing, "creditsPerUnit", "credits_per_unit");
+  const unit = stringField2(pricing, "unit");
+  if (credits !== null) {
+    return `${formatDecimal(credits)} cr/${unit || "unit"}`;
+  }
+  const summary = stringField2(pricing, "summary");
+  if (summary) return summary;
+  const displayText = stringField2(pricing, "displayText", "display_text");
+  return displayText || null;
+}
+function aggregateCategorySummaries(tools) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const tool of tools) {
+    for (const category of tool.categories ?? []) {
+      counts.set(category, (counts.get(category) ?? 0) + 1);
+    }
+  }
+  return [...counts.entries()].map(([name, count]) => ({
+    name,
+    count,
+    description: describeToolCategory(name)
+  })).sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
+}
+function categoryEnumerationRender(summaries) {
+  const nameWidth = summaries.reduce(
+    (max, item) => Math.max(max, item.name.length),
+    0
+  );
+  const countWidth = summaries.reduce(
+    (max, item) => Math.max(max, String(item.count).length),
+    0
+  );
+  return {
+    sections: [
+      {
+        title: `${summaries.length} tool categories:`,
+        lines: summaries.map((item) => {
+          const name = item.name.padEnd(nameWidth);
+          const count = String(item.count).padStart(countWidth);
+          const definition = item.description ? ` - ${item.description}` : "";
+          return `${name}  ${count}${definition}`;
+        })
+      },
+      {
+        title: "next",
+        lines: ["Pass a category: deepline tools list email_finder"]
+      }
+    ]
+  };
+}
+async function listToolCategories(emitJson, compact) {
+  const client2 = new DeeplineClient();
+  const rawTools = await client2.listTools({ compact });
+  const items = rawTools.map(toListedTool);
+  const summaries = aggregateCategorySummaries(rawTools);
+  const outputItems = compact ? items.map(compactTool) : items;
+  printCommandEnvelope(
+    {
+      tools: outputItems,
+      count: outputItems.length,
+      categories: summaries,
+      filters: {
+        categories: []
+      },
+      commandTemplates: TOOL_COMMAND_TEMPLATES,
+      render: categoryEnumerationRender(summaries)
+    },
+    { json: emitJson }
+  );
+  return 0;
+}
+function unknownCategoryError(category, summaries, emitJson) {
+  const known = summaries.map((item) => item.name);
+  const message = `Unknown tool category "${category}". Run \`deepline tools list\` to browse categories.`;
+  if (emitJson) {
+    printJson({
+      ok: false,
+      exitCode: 4,
+      code: "TOOL_CATEGORY_NOT_FOUND",
+      message,
+      category,
+      categories: summaries,
+      next: "deepline tools list"
+    });
+    return 4;
+  }
+  const render = categoryEnumerationRender(summaries);
+  console.error(message);
+  console.error("");
+  console.error(renderCommandEnvelopeText({ render }).trimEnd());
+  console.error("");
+  console.error(`Valid categories: ${known.join(", ")}`);
+  return 4;
+}
+async function listToolsInCategory(category, emitJson) {
+  const client2 = new DeeplineClient();
+  const rawTools = await client2.listTools({
+    categories: category,
+    compact: false
+  });
+  const allTools = await client2.listTools({ compact: true });
+  const summaries = aggregateCategorySummaries(allTools);
+  if (!summaries.some((item) => item.name === category)) {
+    return unknownCategoryError(category, summaries, emitJson);
+  }
+  const rows = rawTools.filter((tool) => tool.categories?.includes(category)).map((tool) => ({
+    id: tool.toolId,
+    provider: tool.provider,
+    required: requiredInputIds(tool),
+    pricing: shortPricingHint(tool),
+    description: firstSentence(tool.description)
+  })).sort((a, b) => a.id.localeCompare(b.id));
+  const idWidth = rows.reduce((max, row) => Math.max(max, row.id.length), 0);
+  const render = {
+    sections: [
+      {
+        title: `${rows.length} tools in ${category}:`,
+        lines: rows.map((row) => {
+          const id = row.id.padEnd(idWidth);
+          const required = row.required.length ? `(${row.required.join(", ")})` : "(no required inputs)";
+          const pricing = row.pricing ? ` [${row.pricing}]` : "";
+          const description = row.description ? ` - ${row.description}` : "";
+          return `${id}  ${required}${pricing}${description}`;
+        })
+      },
+      {
+        title: "next",
+        lines: [
+          "Run `deepline tools describe <toolId>` for the full contract."
+        ]
+      }
+    ]
+  };
+  printCommandEnvelope(
+    {
+      category,
+      total: rows.length,
+      tools: rows,
+      commandTemplates: TOOL_COMMAND_TEMPLATES,
+      render
+    },
+    { json: emitJson }
+  );
+  return 0;
+}
+async function listToolsForCategoryFilter(requestedCategories, emitJson, compact) {
   const client2 = new DeeplineClient();
-  const categoryArgIndex = args.findIndex((arg) => arg === "--categories");
-  const categoryFilter = categoryArgIndex >= 0 ? args[categoryArgIndex + 1] : "";
-  const compact = !args.includes("--full");
-  const requestedCategories = categoryFilter ? categoryFilter.split(",").map((item) => item.trim()).filter(Boolean) : [];
   const items = (await client2.listTools({
-    ...categoryFilter ? { categories: categoryFilter } : {},
+    categories: requestedCategories.join(","),
     compact
   })).map(toListedTool).filter(
-    (item) => requestedCategories.length === 0 || requestedCategories.some(
+    (item) => requestedCategories.some(
       (category) => item.categories.includes(category)
     )
   );
-  const emptyResult = items.length === 0 && requestedCategories.length > 0 ? zeroMatchToolGuidance({ categories: requestedCategories }) : null;
+  const emptyResult = items.length === 0 ? zeroMatchToolGuidance({ categories: requestedCategories }) : null;
   const render = {
     sections: emptyResult ? zeroMatchRender(emptyResult).sections : [
       {
@@ -26827,10 +27025,41 @@ async function listTools(args) {
       commandTemplates: TOOL_COMMAND_TEMPLATES,
       render
     },
-    { json: argsWantJson(args) }
+    { json: emitJson }
   );
   return 0;
 }
+async function listTools(category, options = {}) {
+  const positional = category?.trim() ?? "";
+  const flagCategories = (options.categories ?? "").split(",").map((item) => item.trim()).filter(Boolean);
+  const compact = options.compact !== false;
+  const emitJson = options.json === true || shouldEmitJson();
+  if (positional && flagCategories.length > 0) {
+    const flagIsSameSingle = flagCategories.length === 1 && flagCategories[0] === positional;
+    if (!flagIsSameSingle) {
+      const message = `Category "${positional}" and --categories ${flagCategories.join(",")} disagree. Pass one: deepline tools list ${positional}`;
+      if (emitJson) {
+        printJson({
+          ok: false,
+          exitCode: 2,
+          code: "TOOL_LIST_CATEGORY_CONFLICT",
+          message,
+          next: `deepline tools list ${positional}`
+        });
+      } else {
+        console.error(message);
+      }
+      return 2;
+    }
+  }
+  if (positional) {
+    return listToolsInCategory(positional, emitJson);
+  }
+  if (flagCategories.length > 0) {
+    return listToolsForCategoryFilter(flagCategories, emitJson, compact);
+  }
+  return listToolCategories(emitJson, compact);
+}
 async function searchTools(queryInput, options = {}) {
   const query = queryInput?.trim() ?? "";
   const hasStructuredSearch = Boolean(
@@ -27029,27 +27258,37 @@ Output:
   Use execute to run a tool.
 `
   );
-  tools.command("list").description("List available tools.").addHelpText(
+  tools.command("list [category]").description("Browse tool categories, or list every tool in a category.").addHelpText(
     "after",
     `
 Notes:
-  Inventory command for known tool ids. Use search for ranked discovery by
-  intent, aliases, descriptions, and schema fields.
+  Bare \`tools list\` prints the category enumeration: one line per category with
+  its tool count and definition. Pass a category to list every tool in it, one
+  succinct row each (required inputs, Deepline pricing hint, first sentence).
+  The listing is exhaustive and never truncated. Use search for ranked discovery
+  by intent, aliases, descriptions, and schema fields.
+
+  --categories is a back-compat inventory filter. Passing it alone returns the
+  legacy flat inventory envelope (one row per tool). The positional category is
+  the newer exhaustive per-category view. If both are given they must name the
+  same category (the positional view wins); otherwise it is a usage error.
 
 Examples:
   deepline tools list
+  deepline tools list email_finder
+  deepline tools list email_finder --json
   deepline tools list --categories email_finder --json
   deepline tools search email --json
 `
   ).option(
     "--categories <categories>",
-    "Comma-separated categories to filter inventory"
-  ).option("--compact", "Drop verbose fields from JSON output").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
-    process.exitCode = await listTools([
-      ...options.categories ? ["--categories", options.categories] : [],
-      ...options.compact ? ["--compact"] : [],
-      ...options.json ? ["--json"] : []
-    ]);
+    "Comma-separated categories filter (back-compat alias for the positional)"
+  ).option("--compact", "Drop verbose fields from JSON output").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (category, options) => {
+    process.exitCode = await listTools(category, {
+      categories: typeof options.categories === "string" ? options.categories : void 0,
+      compact: options.compact !== false,
+      json: Boolean(options.json)
+    });
   });
   const addToolSearchCommand = (command) => command.description(
     "Search available tools by intent query or structured filters."

package/dist/cli/index.mjs

@@ -701,7 +701,7 @@ var SDK_RELEASE = {
   // Deepline-native radars. Older clients must update before discovering,
   // checking, or deploying an unlaunched monitor integration.
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
-  version: "0.1.261",
+  version: "0.1.263",
   apiContract: "2026-07-native-monitor-launch-hard-cutover",
   supportPolicy: {
     minimumSupported: "0.1.53",
@@ -12494,13 +12494,21 @@ function getStatusFromLiveEvent(event) {
   const payload = getEventPayload(event);
   return playStatusValue(payload.status) ?? playStatusValue(getRunRecordFromPackage(payload)?.status);
 }
+function getWaitKindFromLiveEvent(event) {
+  const payload = getEventPayload(event);
+  const progress = payload.progress && typeof payload.progress === "object" ? payload.progress : null;
+  const waitKind = payload.waitKind ?? progress?.waitKind;
+  return typeof waitKind === "string" && waitKind.trim() ? waitKind.trim() : null;
+}
 function writePlayWaitingHint(input2) {
   if (getStatusFromLiveEvent(input2.event) !== "waiting") return;
   const runId = getRunIdFromLiveEvent(input2.event);
   if (!runId || input2.state.waitingRunId === runId) return;
   input2.state.waitingRunId = runId;
+  const waitKind = getWaitKindFromLiveEvent(input2.event);
+  const message = waitKind === "integration_event" || waitKind === "integration_event_batch" ? "is waiting for an external event." : waitKind === "sleep" ? "is waiting for its scheduled resume." : waitKind === "detached_runner" ? "is executing in the runtime." : "is waiting on a durable runtime boundary.";
   input2.progress.writeLine(
-    `[play waiting] ${runId} is waiting for an external approval or event. The command will continue watching; inspect it with 'deepline runs get ${runId} --full --json'.`
+    `[play waiting] ${runId} ${message} The command will continue watching; inspect it with 'deepline runs get ${runId} --full --json'.`
   );
 }
 function getFinalStatusFromLiveEvent(event) {
@@ -12763,6 +12771,9 @@ function getRunningHeartbeatLine(input2) {
     return `queued ${target}: waiting for worker capacity`;
   }
   if (status === "waiting") {
+    if (getWaitKindFromLiveEvent(input2.event) === "detached_runner") {
+      return `running ${target}: executing in detached runtime`;
+    }
     return `waiting ${target}: waiting on external work`;
   }
   return `running ${target}: still processing`;
@@ -26664,6 +26675,33 @@ function extractSummaryFields(payload) {
   return {};
 }
 
+// ../shared_libs/plays/tool-category-descriptions.ts
+var TOOL_CATEGORY_DESCRIPTIONS = {
+  company_search: "Find companies matching firmographic, ad, or web criteria.",
+  people_search: "Find people matching role, company, or persona criteria.",
+  people_enrich: "Enrich a known person with contact, social, and profile data.",
+  company_enrich: "Enrich a known company with firmographic and account data.",
+  email_finder: "Find work or personal email addresses for a person.",
+  email_verify: "Validate email deliverability and catch-all status.",
+  phone_finder: "Find mobile or direct phone numbers for a person.",
+  phone_verify: "Validate phone-number reachability and line type.",
+  research: "Research accounts, people, news, and signals for context and scoring.",
+  autocomplete: "Resolve names and entities to canonical catalog records.",
+  automation: "Kick off provider-side jobs, exports, and asynchronous workflows.",
+  outbound_tools: "Run outbound sequencing, deliverability, and campaign operations.",
+  admin: "Provider-side status, metadata, and account operations behind other tools.",
+  smb: "Look up small-business listings, local records, and public filings.",
+  identity_resolution: "Match a partial identity to a single resolved person or company.",
+  reverse_lookup: "Resolve an email, phone, or profile back to a person.",
+  enrichment: "General-purpose record enrichment across people and companies.",
+  batch: "Run an enrichment or search operation over many rows at once.",
+  premium: "Higher-cost tools with premium provider coverage.",
+  free: "Free tools that do not spend Deepline credits."
+};
+function describeToolCategory(category) {
+  return TOOL_CATEGORY_DESCRIPTIONS[category] ?? null;
+}
+
 // src/cli/commands/model-description.ts
 function formatModelDescription(description) {
   const lines = [];
@@ -26830,21 +26868,181 @@ function zeroMatchRender(emptyResult) {
     ]
   };
 }
-async function listTools(args) {
+function firstSentence(text) {
+  const clean = (text ?? "").replace(/\s+/g, " ").trim();
+  if (!clean) return "";
+  const match = clean.match(/^.*?[.!?](?=\s|$)/);
+  return (match ? match[0] : clean).trim();
+}
+function requiredInputIds(tool) {
+  const inputSchema = recordField2(
+    tool,
+    "inputSchema",
+    "input_schema"
+  );
+  return toolInputFieldsForDisplay(inputSchema).filter((field) => field.required === true).map((field) => String(field.name ?? "")).filter(Boolean);
+}
+function shortPricingHint(tool) {
+  const pricing = recordField2(
+    tool,
+    "pricing"
+  );
+  const credits = numberField2(pricing, "creditsPerUnit", "credits_per_unit");
+  const unit = stringField2(pricing, "unit");
+  if (credits !== null) {
+    return `${formatDecimal(credits)} cr/${unit || "unit"}`;
+  }
+  const summary = stringField2(pricing, "summary");
+  if (summary) return summary;
+  const displayText = stringField2(pricing, "displayText", "display_text");
+  return displayText || null;
+}
+function aggregateCategorySummaries(tools) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const tool of tools) {
+    for (const category of tool.categories ?? []) {
+      counts.set(category, (counts.get(category) ?? 0) + 1);
+    }
+  }
+  return [...counts.entries()].map(([name, count]) => ({
+    name,
+    count,
+    description: describeToolCategory(name)
+  })).sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
+}
+function categoryEnumerationRender(summaries) {
+  const nameWidth = summaries.reduce(
+    (max, item) => Math.max(max, item.name.length),
+    0
+  );
+  const countWidth = summaries.reduce(
+    (max, item) => Math.max(max, String(item.count).length),
+    0
+  );
+  return {
+    sections: [
+      {
+        title: `${summaries.length} tool categories:`,
+        lines: summaries.map((item) => {
+          const name = item.name.padEnd(nameWidth);
+          const count = String(item.count).padStart(countWidth);
+          const definition = item.description ? ` - ${item.description}` : "";
+          return `${name}  ${count}${definition}`;
+        })
+      },
+      {
+        title: "next",
+        lines: ["Pass a category: deepline tools list email_finder"]
+      }
+    ]
+  };
+}
+async function listToolCategories(emitJson, compact) {
+  const client2 = new DeeplineClient();
+  const rawTools = await client2.listTools({ compact });
+  const items = rawTools.map(toListedTool);
+  const summaries = aggregateCategorySummaries(rawTools);
+  const outputItems = compact ? items.map(compactTool) : items;
+  printCommandEnvelope(
+    {
+      tools: outputItems,
+      count: outputItems.length,
+      categories: summaries,
+      filters: {
+        categories: []
+      },
+      commandTemplates: TOOL_COMMAND_TEMPLATES,
+      render: categoryEnumerationRender(summaries)
+    },
+    { json: emitJson }
+  );
+  return 0;
+}
+function unknownCategoryError(category, summaries, emitJson) {
+  const known = summaries.map((item) => item.name);
+  const message = `Unknown tool category "${category}". Run \`deepline tools list\` to browse categories.`;
+  if (emitJson) {
+    printJson({
+      ok: false,
+      exitCode: 4,
+      code: "TOOL_CATEGORY_NOT_FOUND",
+      message,
+      category,
+      categories: summaries,
+      next: "deepline tools list"
+    });
+    return 4;
+  }
+  const render = categoryEnumerationRender(summaries);
+  console.error(message);
+  console.error("");
+  console.error(renderCommandEnvelopeText({ render }).trimEnd());
+  console.error("");
+  console.error(`Valid categories: ${known.join(", ")}`);
+  return 4;
+}
+async function listToolsInCategory(category, emitJson) {
+  const client2 = new DeeplineClient();
+  const rawTools = await client2.listTools({
+    categories: category,
+    compact: false
+  });
+  const allTools = await client2.listTools({ compact: true });
+  const summaries = aggregateCategorySummaries(allTools);
+  if (!summaries.some((item) => item.name === category)) {
+    return unknownCategoryError(category, summaries, emitJson);
+  }
+  const rows = rawTools.filter((tool) => tool.categories?.includes(category)).map((tool) => ({
+    id: tool.toolId,
+    provider: tool.provider,
+    required: requiredInputIds(tool),
+    pricing: shortPricingHint(tool),
+    description: firstSentence(tool.description)
+  })).sort((a, b) => a.id.localeCompare(b.id));
+  const idWidth = rows.reduce((max, row) => Math.max(max, row.id.length), 0);
+  const render = {
+    sections: [
+      {
+        title: `${rows.length} tools in ${category}:`,
+        lines: rows.map((row) => {
+          const id = row.id.padEnd(idWidth);
+          const required = row.required.length ? `(${row.required.join(", ")})` : "(no required inputs)";
+          const pricing = row.pricing ? ` [${row.pricing}]` : "";
+          const description = row.description ? ` - ${row.description}` : "";
+          return `${id}  ${required}${pricing}${description}`;
+        })
+      },
+      {
+        title: "next",
+        lines: [
+          "Run `deepline tools describe <toolId>` for the full contract."
+        ]
+      }
+    ]
+  };
+  printCommandEnvelope(
+    {
+      category,
+      total: rows.length,
+      tools: rows,
+      commandTemplates: TOOL_COMMAND_TEMPLATES,
+      render
+    },
+    { json: emitJson }
+  );
+  return 0;
+}
+async function listToolsForCategoryFilter(requestedCategories, emitJson, compact) {
   const client2 = new DeeplineClient();
-  const categoryArgIndex = args.findIndex((arg) => arg === "--categories");
-  const categoryFilter = categoryArgIndex >= 0 ? args[categoryArgIndex + 1] : "";
-  const compact = !args.includes("--full");
-  const requestedCategories = categoryFilter ? categoryFilter.split(",").map((item) => item.trim()).filter(Boolean) : [];
   const items = (await client2.listTools({
-    ...categoryFilter ? { categories: categoryFilter } : {},
+    categories: requestedCategories.join(","),
     compact
   })).map(toListedTool).filter(
-    (item) => requestedCategories.length === 0 || requestedCategories.some(
+    (item) => requestedCategories.some(
       (category) => item.categories.includes(category)
     )
   );
-  const emptyResult = items.length === 0 && requestedCategories.length > 0 ? zeroMatchToolGuidance({ categories: requestedCategories }) : null;
+  const emptyResult = items.length === 0 ? zeroMatchToolGuidance({ categories: requestedCategories }) : null;
   const render = {
     sections: emptyResult ? zeroMatchRender(emptyResult).sections : [
       {
@@ -26875,10 +27073,41 @@ async function listTools(args) {
       commandTemplates: TOOL_COMMAND_TEMPLATES,
       render
     },
-    { json: argsWantJson(args) }
+    { json: emitJson }
   );
   return 0;
 }
+async function listTools(category, options = {}) {
+  const positional = category?.trim() ?? "";
+  const flagCategories = (options.categories ?? "").split(",").map((item) => item.trim()).filter(Boolean);
+  const compact = options.compact !== false;
+  const emitJson = options.json === true || shouldEmitJson();
+  if (positional && flagCategories.length > 0) {
+    const flagIsSameSingle = flagCategories.length === 1 && flagCategories[0] === positional;
+    if (!flagIsSameSingle) {
+      const message = `Category "${positional}" and --categories ${flagCategories.join(",")} disagree. Pass one: deepline tools list ${positional}`;
+      if (emitJson) {
+        printJson({
+          ok: false,
+          exitCode: 2,
+          code: "TOOL_LIST_CATEGORY_CONFLICT",
+          message,
+          next: `deepline tools list ${positional}`
+        });
+      } else {
+        console.error(message);
+      }
+      return 2;
+    }
+  }
+  if (positional) {
+    return listToolsInCategory(positional, emitJson);
+  }
+  if (flagCategories.length > 0) {
+    return listToolsForCategoryFilter(flagCategories, emitJson, compact);
+  }
+  return listToolCategories(emitJson, compact);
+}
 async function searchTools(queryInput, options = {}) {
   const query = queryInput?.trim() ?? "";
   const hasStructuredSearch = Boolean(
@@ -27077,27 +27306,37 @@ Output:
   Use execute to run a tool.
 `
   );
-  tools.command("list").description("List available tools.").addHelpText(
+  tools.command("list [category]").description("Browse tool categories, or list every tool in a category.").addHelpText(
     "after",
     `
 Notes:
-  Inventory command for known tool ids. Use search for ranked discovery by
-  intent, aliases, descriptions, and schema fields.
+  Bare \`tools list\` prints the category enumeration: one line per category with
+  its tool count and definition. Pass a category to list every tool in it, one
+  succinct row each (required inputs, Deepline pricing hint, first sentence).
+  The listing is exhaustive and never truncated. Use search for ranked discovery
+  by intent, aliases, descriptions, and schema fields.
+
+  --categories is a back-compat inventory filter. Passing it alone returns the
+  legacy flat inventory envelope (one row per tool). The positional category is
+  the newer exhaustive per-category view. If both are given they must name the
+  same category (the positional view wins); otherwise it is a usage error.
 
 Examples:
   deepline tools list
+  deepline tools list email_finder
+  deepline tools list email_finder --json
   deepline tools list --categories email_finder --json
   deepline tools search email --json
 `
   ).option(
     "--categories <categories>",
-    "Comma-separated categories to filter inventory"
-  ).option("--compact", "Drop verbose fields from JSON output").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
-    process.exitCode = await listTools([
-      ...options.categories ? ["--categories", options.categories] : [],
-      ...options.compact ? ["--compact"] : [],
-      ...options.json ? ["--json"] : []
-    ]);
+    "Comma-separated categories filter (back-compat alias for the positional)"
+  ).option("--compact", "Drop verbose fields from JSON output").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (category, options) => {
+    process.exitCode = await listTools(category, {
+      categories: typeof options.categories === "string" ? options.categories : void 0,
+      compact: options.compact !== false,
+      json: Boolean(options.json)
+    });
   });
   const addToolSearchCommand = (command) => command.description(
     "Search available tools by intent query or structured filters."

package/dist/index.js

@@ -435,7 +435,7 @@ var SDK_RELEASE = {
   // Deepline-native radars. Older clients must update before discovering,
   // checking, or deploying an unlaunched monitor integration.
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
-  version: "0.1.261",
+  version: "0.1.263",
   apiContract: "2026-07-native-monitor-launch-hard-cutover",
   supportPolicy: {
     minimumSupported: "0.1.53",

package/dist/index.mjs

@@ -365,7 +365,7 @@ var SDK_RELEASE = {
   // Deepline-native radars. Older clients must update before discovering,
   // checking, or deploying an unlaunched monitor integration.
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
-  version: "0.1.261",
+  version: "0.1.263",
   apiContract: "2026-07-native-monitor-launch-hard-cutover",
   supportPolicy: {
     minimumSupported: "0.1.53",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepline",
-  "version": "0.1.261",
+  "version": "0.1.263",
   "description": "Deepline SDK + CLI — B2B data enrichment powered by durable cloud execution",
   "license": "MIT",
   "repository": {