deepline 0.1.145 → 0.1.147

package/dist/cli/index.js

@@ -619,10 +619,11 @@ var SDK_RELEASE = {
   // 0.1.108 ships explicit dataset column/tool recompute policy and removes
   // the SDK enrich generator's one-second stale policy.
   // 0.1.110 ships authored V2 prebuilts and required top-level play descriptions.
-  version: "0.1.145",
-  apiContract: "2026-06-dataset-column-cell-stale-hard-cutover",
+  // 0.1.111 ships dataset-native tool list getters and result row datasets.
+  version: "0.1.147",
+  apiContract: "2026-06-dataset-handle-results-hard-cutover",
   supportPolicy: {
-    latest: "0.1.145",
+    latest: "0.1.147",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53",
     commandMinimumSupported: [
@@ -633,52 +634,79 @@ var SDK_RELEASE = {
       },
       {
         command: "plays",
-        minimumSupported: "0.1.110",
-        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+        minimumSupported: "0.1.111",
+        reason: "Play file commands now use dataset-native list getters and result row datasets."
       },
       {
         command: "plays run",
-        minimumSupported: "0.1.110",
-        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+        minimumSupported: "0.1.111",
+        reason: "Play run results now promote row-shaped outputs into dataset handles for safe export."
       },
       {
         command: "run",
         displayCommand: "plays run",
-        minimumSupported: "0.1.110",
-        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+        minimumSupported: "0.1.111",
+        reason: "Play run results now promote row-shaped outputs into dataset handles for safe export."
       },
       {
         command: "plays check",
-        minimumSupported: "0.1.110",
-        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+        minimumSupported: "0.1.111",
+        reason: "Play file checks now validate dataset-native list getter authoring."
       },
       {
         command: "check",
         displayCommand: "plays check",
-        minimumSupported: "0.1.110",
-        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+        minimumSupported: "0.1.111",
+        reason: "Play file checks now validate dataset-native list getter authoring."
       },
       {
         command: "plays publish",
-        minimumSupported: "0.1.110",
-        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+        minimumSupported: "0.1.111",
+        reason: "Published play artifacts now target dataset-native list getters and result row datasets."
       },
       {
         command: "publish",
         displayCommand: "plays publish",
-        minimumSupported: "0.1.110",
-        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+        minimumSupported: "0.1.111",
+        reason: "Published play artifacts now target dataset-native list getters and result row datasets."
       },
       {
         command: "plays set-live",
-        minimumSupported: "0.1.110",
-        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+        minimumSupported: "0.1.111",
+        reason: "Published play artifacts now target dataset-native list getters and result row datasets."
       },
       {
         command: "set-live",
         displayCommand: "plays set-live",
-        minimumSupported: "0.1.110",
-        reason: "Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays."
+        minimumSupported: "0.1.111",
+        reason: "Published play artifacts now target dataset-native list getters and result row datasets."
+      },
+      {
+        command: "runs",
+        minimumSupported: "0.1.111",
+        reason: "Run result rows now render as dataset handles with explicit export commands."
+      },
+      {
+        command: "runs get",
+        minimumSupported: "0.1.111",
+        reason: "Run result rows now render as dataset handles with explicit export commands."
+      },
+      {
+        command: "get",
+        displayCommand: "runs get",
+        minimumSupported: "0.1.111",
+        reason: "Run result rows now render as dataset handles with explicit export commands."
+      },
+      {
+        command: "runs export",
+        minimumSupported: "0.1.111",
+        reason: "Run result row datasets now use the dataset-handle export contract."
+      },
+      {
+        command: "export",
+        displayCommand: "runs export",
+        minimumSupported: "0.1.111",
+        reason: "Run result row datasets now use the dataset-handle export contract."
       }
     ],
     autoUpdatePatchLag: 2
@@ -8302,9 +8330,10 @@ function generateProviderSourceBlock(input2) {
     input: ${inputName},
     description: ${jsString(`Seed ${input2.entity} rows from ${input2.provider}.`)},
   });
-  // extractedLists.${getter}.get() returns provider-shaped rows. Do not assume canonical fields;
+  // extractedLists.${getter}.get() returns a dataset handle of provider-shaped rows. Do not assume canonical fields;
   // inspect source_${input2.index}.extractedLists.${getter}.keys or the provider output schema, then map explicitly below.
-  const sourceRows_${input2.index} = ${accessorExpression(`source_${input2.index}.extractedLists`, getter)}.get() as ${input2.collectionType}[];`;
+  const sourceRowsDataset_${input2.index} = ${accessorExpression(`source_${input2.index}.extractedLists`, getter)}.get();
+  const sourceRows_${input2.index} = (await sourceRowsDataset_${input2.index}.peek(limit)) as ${input2.collectionType}[];`;
 }
 function generateProviderSourceRowsBlock(input2) {
   const blocks = input2.source.values.map(
@@ -10990,6 +11019,9 @@ function formatPlayLogLine(line, status, state) {
   }
   return `${prefix}${message}`;
 }
+function isDatasetResultEnvelope(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) && value.kind === "dataset";
+}
 function compactReturnValue(value, depth = 0) {
   if (depth >= 4) {
     return value && typeof value === "object" ? "[Object]" : value;
@@ -11001,6 +11033,7 @@ function compactReturnValue(value, depth = 0) {
   if (!value || typeof value !== "object") {
     return value;
   }
+  const isDatasetEnvelope = isDatasetResultEnvelope(value);
   const output2 = {};
   for (const [key, entry] of Object.entries(value)) {
     if (depth === 0 && key === "_metadata") {
@@ -11009,13 +11042,41 @@ function compactReturnValue(value, depth = 0) {
     if (BULKY_RETURN_KEYS.has(key)) {
       continue;
     }
-    if (key === "access") {
+    if (isDatasetEnvelope && key === "access") {
+      continue;
+    }
+    if (isDatasetEnvelope && (key === "queryDatasetCommand" || key === "cliCommand")) {
+      continue;
+    }
+    if (isDatasetEnvelope && key === "slowExportAsCsvCommand") {
+      output2.fullExportCommand = entry;
       continue;
     }
     output2[key] = compactReturnValue(entry, depth + 1);
   }
   return output2;
 }
+function defaultResultForEnvelope(value, depth = 0) {
+  if (depth > 20 || value == null || typeof value !== "object") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => defaultResultForEnvelope(entry, depth + 1));
+  }
+  const isDatasetEnvelope = isDatasetResultEnvelope(value);
+  const output2 = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (isDatasetEnvelope && (key === "queryDatasetCommand" || key === "cliCommand")) {
+      continue;
+    }
+    if (isDatasetEnvelope && key === "slowExportAsCsvCommand") {
+      output2.fullExportCommand = entry;
+      continue;
+    }
+    output2[key] = defaultResultForEnvelope(entry, depth + 1);
+  }
+  return output2;
+}
 function formatJsonPreview(value) {
   const json = JSON.stringify(value, null, 2);
   if (!json || json === "{}") {
@@ -11059,9 +11120,6 @@ function collectDatasetHandleLines(value, path = "result", datasetStats) {
     if (datasetStats && (datasetStats.source === path || datasetStats.source === record.path)) {
       lines2.push(...formatDatasetStatsLines(datasetStats.stats, "    "));
     }
-    if (typeof record.queryDatasetCommand === "string") {
-      lines2.push(`  query dataset: ${record.queryDatasetCommand}`);
-    }
     if (typeof record.slowExportAsCsvCommand === "string") {
       lines2.push(`  export CSV: ${record.slowExportAsCsvCommand}`);
     }
@@ -11472,7 +11530,7 @@ function compactPlayStatus(status) {
     logs: normalizeLogsForEnvelope(status),
     ...displayError ? { error: displayError } : {},
     ...warnings.length > 0 ? { warnings } : {},
-    ...result !== void 0 ? { result } : {},
+    ...result !== void 0 ? { result: defaultResultForEnvelope(result) } : {},
     ...billing ? { billing } : {},
     next: buildRunNextCommands(status)
   };
@@ -18946,6 +19004,221 @@ Examples:
   }
 }
 
+// src/cli/commands/monitors.ts
+var FORBIDDEN_AS_API_ERROR = { forbiddenAsApiError: true };
+function buildHttpClient() {
+  return new HttpClient(resolveConfig());
+}
+function parseJsonObjectArg(raw, flag) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(
+      `${flag} must be a JSON object. ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`${flag} must be a JSON object.`);
+  }
+  return parsed;
+}
+function encodeKey(key) {
+  return encodeURIComponent(key);
+}
+async function handleMonitorsTools(options) {
+  const http = buildHttpClient();
+  const params = new URLSearchParams();
+  if (options.provider) params.set("provider", options.provider);
+  if (options.tool) params.set("tool", options.tool);
+  if (options.search) params.set("search", options.search);
+  if (options.limit) params.set("limit", options.limit);
+  const query = params.toString();
+  const payload = await http.request(
+    `/api/v2/monitors/tools${query ? `?${query}` : ""}`,
+    { method: "GET", ...FORBIDDEN_AS_API_ERROR }
+  );
+  printCommandEnvelope(payload, { json: options.json });
+}
+async function handleMonitorsCheck(definition, options) {
+  const http = buildHttpClient();
+  const body = parseJsonObjectArg(definition, "--definition");
+  const payload = await http.request(
+    "/api/v2/monitors/check",
+    { method: "POST", body, ...FORBIDDEN_AS_API_ERROR }
+  );
+  printCommandEnvelope(payload, { json: options.json });
+}
+async function handleMonitorsDeploy(definition, options) {
+  const http = buildHttpClient();
+  const body = parseJsonObjectArg(definition, "--definition");
+  const payload = await http.request(
+    "/api/v2/monitors/deploy",
+    { method: "POST", body, ...FORBIDDEN_AS_API_ERROR }
+  );
+  printCommandEnvelope(payload, { json: options.json });
+}
+async function handleDeployedList(options) {
+  const http = buildHttpClient();
+  const params = new URLSearchParams();
+  if (options.status) params.set("status", options.status);
+  if (options.limit) params.set("limit", options.limit);
+  const query = params.toString();
+  const payload = await http.request(
+    `/api/v2/monitors/deployed${query ? `?${query}` : ""}`,
+    { method: "GET", ...FORBIDDEN_AS_API_ERROR }
+  );
+  printCommandEnvelope(payload, { json: options.json });
+}
+async function handleDeployedGet(key, options) {
+  const http = buildHttpClient();
+  const payload = await http.request(
+    `/api/v2/monitors/deployed/${encodeKey(key)}`,
+    { method: "GET", ...FORBIDDEN_AS_API_ERROR }
+  );
+  printCommandEnvelope(payload, { json: options.json });
+}
+async function handleDeployedDelete(key, options) {
+  const http = buildHttpClient();
+  const params = new URLSearchParams();
+  if (options.localOnly) params.set("local_only", "true");
+  const query = params.toString();
+  const payload = await http.request(
+    `/api/v2/monitors/deployed/${encodeKey(key)}${query ? `?${query}` : ""}`,
+    { method: "DELETE", ...FORBIDDEN_AS_API_ERROR }
+  );
+  printCommandEnvelope(payload, { json: options.json });
+}
+async function handleDeployedUpdate(key, patch, options) {
+  const http = buildHttpClient();
+  const body = parseJsonObjectArg(patch, "<patch>");
+  const payload = await http.request(
+    `/api/v2/monitors/deployed/${encodeKey(key)}`,
+    { method: "PATCH", body, ...FORBIDDEN_AS_API_ERROR }
+  );
+  printCommandEnvelope(payload, { json: options.json });
+}
+async function handleReactivate(key, options) {
+  const http = buildHttpClient();
+  const payload = await http.request(
+    `/api/v2/monitors/deployed/${encodeKey(key)}/reactivate`,
+    { method: "POST", body: {}, ...FORBIDDEN_AS_API_ERROR }
+  );
+  printCommandEnvelope(payload, { json: options.json });
+}
+function registerMonitorsCommands(program) {
+  const monitors = program.command("monitors").description("Discover, deploy, and manage Deepline monitors.").addHelpText(
+    "after",
+    `
+Notes:
+  Monitors are provider-backed signal feeds that deliver events into your
+  workspace. Access is granted by a Deepline admin via Admin -> Rollouts; until
+  then these commands return a clear monitor_access_required error.
+
+Examples:
+  deepline monitors tools --json
+  deepline monitors check '{"key":"my-monitor","tool":"...","payload":{}}'
+  deepline monitors deploy '{"key":"my-monitor","tool":"...","payload":{}}'
+  deepline monitors deployed --json
+  deepline monitors deployed get my-monitor --json
+  deepline monitors reactivate my-monitor --json
+`
+  );
+  monitors.command("tools").description("List or describe the monitor tools available to your org.").addHelpText(
+    "after",
+    `
+Notes:
+  Read-only. Filter the catalog with --provider, --tool, --search, or --limit.
+  Pass --tool to describe a single monitor tool.
+
+Examples:
+  deepline monitors tools
+  deepline monitors tools --provider theirstack --json
+  deepline monitors tools --tool theirstack_jobs --json
+`
+  ).option("--provider <provider>", "Filter by provider").option("--tool <tool>", "Describe a single monitor tool by id").option("--search <query>", "Search monitor tools by text").option("--limit <n>", "Limit the number of monitor tools returned").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleMonitorsTools);
+  monitors.command("check <definition>").description("Validate a monitor definition without deploying it.").addHelpText(
+    "after",
+    `
+Notes:
+  Read-only validation. <definition> is a JSON object with key, tool, payload,
+  and optional controls. Does not deploy or spend credits.
+
+Examples:
+  deepline monitors check '{"key":"my-monitor","tool":"theirstack_jobs","payload":{}}'
+`
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleMonitorsCheck);
+  monitors.command("deploy <definition>").description("Deploy a monitor from a definition.").addHelpText(
+    "after",
+    `
+Notes:
+  Mutates workspace state and may spend Deepline credits. <definition> is a JSON
+  object with key, tool, payload, and optional controls.
+
+Examples:
+  deepline monitors deploy '{"key":"my-monitor","tool":"theirstack_jobs","payload":{}}'
+`
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleMonitorsDeploy);
+  monitors.command("reactivate <key>").description("Reactivate a previously disabled deployed monitor.").addHelpText(
+    "after",
+    `
+Notes:
+  Mutates workspace state and may spend Deepline credits.
+
+Examples:
+  deepline monitors reactivate my-monitor --json
+`
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleReactivate);
+  const deployed = monitors.command("deployed").description("List and manage your deployed monitors.").addHelpText(
+    "after",
+    `
+Notes:
+  With no subcommand, lists deployed monitors. Use get/update/delete to manage a
+  single monitor by its public key.
+
+Examples:
+  deepline monitors deployed --json
+  deepline monitors deployed --status all --json
+  deepline monitors deployed get my-monitor --json
+`
+  ).option("--status <status>", 'Filter by monitor status (or "all")').option("--limit <n>", "Limit the number of deployed monitors returned").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleDeployedList);
+  deployed.command("get <key>").description("Show a single deployed monitor by its public key.").addHelpText(
+    "after",
+    `
+Notes:
+  Read-only.
+
+Examples:
+  deepline monitors deployed get my-monitor --json
+`
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleDeployedGet);
+  deployed.command("update <key> <patch>").description("Update a deployed monitor by its public key.").addHelpText(
+    "after",
+    `
+Notes:
+  Mutates workspace state. <patch> is a JSON object of fields to update.
+
+Examples:
+  deepline monitors deployed update my-monitor '{"controls":{"enabled":false}}' --json
+`
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleDeployedUpdate);
+  deployed.command("delete <key>").description("Delete a deployed monitor by its public key.").addHelpText(
+    "after",
+    `
+Notes:
+  Mutates workspace state. By default deprovisions the upstream provider
+  resource; pass --local-only to remove only the Deepline-managed record.
+
+Examples:
+  deepline monitors deployed delete my-monitor --json
+  deepline monitors deployed delete my-monitor --local-only --json
+`
+  ).option(
+    "--local-only",
+    "Remove only the Deepline-managed record, leaving the upstream resource"
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleDeployedDelete);
+}
+
 // src/cli/commands/org.ts
 async function fetchOrganizations(http, apiKey) {
   return http.post("/api/v2/auth/cli/organizations", { api_key: apiKey });
@@ -20200,16 +20473,24 @@ function tryConvertToList(payload, options) {
     (entry) => typeof entry === "string" && entry.trim().length > 0
   ) : [];
   if (listExtractorPaths.length > 0) {
+    let emptyMatch = null;
     for (const root of candidateRoots(payload)) {
       for (const extractorPath of listExtractorPaths) {
         const resolved = getByDottedPath(root.value, extractorPath);
         const rows = normalizeRows(resolved);
-        if (rows && rows.length > 0) {
-          const sourcePath = root.path ? `${root.path}.${extractorPath}` : extractorPath;
+        if (!rows) {
+          continue;
+        }
+        const sourcePath = root.path ? `${root.path}.${extractorPath}` : extractorPath;
+        if (rows.length > 0) {
           return { rows, strategy: "configured_paths", sourcePath };
         }
+        emptyMatch ??= { rows, strategy: "configured_paths", sourcePath };
       }
     }
+    if (emptyMatch) {
+      return emptyMatch;
+    }
   }
   for (const root of candidateRoots(payload)) {
     const candidate = findBestArrayCandidate(root.value, root.path ?? "");
@@ -20233,9 +20514,9 @@ function writeJsonOutputFile(payload, stem) {
   (0, import_node_fs12.writeFileSync)(outputPath, JSON.stringify(payload, null, 2), "utf-8");
   return outputPath;
 }
-function writeCsvOutputFile(rows, stem) {
-  const outputDir = ensureOutputDir();
-  const outputPath = (0, import_node_path14.join)(outputDir, `${stem}_${Date.now()}.csv`);
+function writeCsvOutputFile(rows, stem, options) {
+  const outputPath = options?.outPath ? options.outPath : (0, import_node_path14.join)(ensureOutputDir(), `${stem}_${Date.now()}.csv`);
+  (0, import_node_fs12.mkdirSync)((0, import_node_path14.dirname)(outputPath), { recursive: true });
   const seen = /* @__PURE__ */ new Set();
   const columns = [];
   for (const row of rows) {
@@ -20764,6 +21045,7 @@ Examples:
   deepline tools execute hunter_email_verifier --input '{"email":"a@b.com"}'
   deepline tools execute hunter_email_verifier -p email=a@b.com
   deepline tools execute test_rate_limit --input '{"key":"smoke"}' --json | jq '.status'
+  deepline tools execute free_simple_company_search --input '{"sql":"SELECT company_name FROM companies LIMIT 10"}' --out companies.csv
 `
   ).option(
     "-p, --param <key=value>",
@@ -20785,6 +21067,9 @@ Examples:
   ).option(
     "--output-format <format>",
     "Output format: auto, csv, csv_file, json, or json_file"
+  ).option(
+    "-o, --out <path>",
+    "Write row-shaped tool output to this CSV path"
   ).option(
     "--no-preview",
     "Only print the extracted output path when applicable"
@@ -20797,6 +21082,7 @@ Examples:
       ...options.input ? ["--input", options.input] : [],
       ...options.payload ? ["--payload", options.payload] : [],
       ...options.outputFormat ? ["--output-format", options.outputFormat] : [],
+      ...options.out ? ["--out", options.out] : [],
       ...options.preview === false ? ["--no-preview"] : []
     ];
     process.exitCode = await executeTool(args);
@@ -21247,7 +21533,7 @@ function toolMetadataJsonForDescribe(tool, requestedToolId) {
       invalidGetterHint: "If TypeScript says an extractedValues/extractedLists property does not exist, that field is not a declared Deepline getter.",
       observeActualShape: observedOutputCommand,
       observedOutput: observedOutputCommand,
-      forPlayGetterBugs: "Run a tiny play, inspect `deepline runs get <run-id> --full --json`, and export returned dataset handles with `deepline runs export`. Backing tables exist only for ctx.map(...).run(...) stages that actually executed.",
+      forPlayGetterBugs: "Run a tiny play, inspect returned handles with `deepline runs get <run-id> --full --json`, then export row datasets with `deepline runs export`.",
       executeOutputFields: "tools execute JSON may include output_preview for this direct probe only; play debugging uses run output and returned dataset handles."
     },
     ...starterScript ? { starterScript } : {}
@@ -21454,12 +21740,13 @@ function parseExecuteOptions(args) {
   const toolId = args[0];
   if (!toolId) {
     throw new Error(
-      `Usage: deepline tools execute <toolId> [--param key=value ...] [--input '{"k":"v"}'] [--output-format auto|csv|csv_file|json|json_file] [--no-preview]`
+      `Usage: deepline tools execute <toolId> [--param key=value ...] [--input '{"k":"v"}'] [--out rows.csv] [--output-format auto|csv|csv_file|json|json_file] [--no-preview]`
     );
   }
   const params = {};
   let outputFormat = "auto";
   let noPreview = false;
+  let outPath = null;
   for (let index = 1; index < args.length; index += 1) {
     const arg = args[index];
     if ((arg === "--param" || arg === "-p") && args[index + 1]) {
@@ -21491,9 +21778,13 @@ function parseExecuteOptions(args) {
       noPreview = true;
       continue;
     }
+    if ((arg === "--out" || arg === "-o") && args[index + 1]) {
+      outPath = (0, import_node_path15.resolve)(args[++index]);
+      continue;
+    }
     throw new Error(`Unknown option: ${arg}`);
   }
-  return { toolId, params, outputFormat, noPreview };
+  return { toolId, params, outputFormat, noPreview, outPath };
 }
 function safeFileStem(value) {
   return value.trim().replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64) || "tool";
@@ -21537,9 +21828,14 @@ export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
   });
 
   const list = Object.values(result.extractedLists)[0];
-  const rows = (list?.get() ?? []).slice(0, 100);
+  if (!list) {
+    throw new Error('Expected ${input2.toolId} to expose an extracted list getter.');
+  }
+  const rows = list.get();
   // ${sampleRows}
   // columns: ${columns}
+  // extractedLists.<name>.get() returns a dataset handle for row-shaped list outputs.
+  // Pass it to ctx.dataset; use rows.peek/count/materialize only for deliberate bounded inspection.
   // .withColumn('email_waterfall', (row, rowCtx) => rowCtx.runPlay('name_domain_email', 'name-and-domain-to-email', { first_name: String(row.first_name ?? ''), last_name: String(row.last_name ?? ''), domain: String(row.domain ?? '') }, { description: 'Resolve email.' }))
   // .withColumn('phone_waterfall', (row, rowCtx) => rowCtx.runPlay('contact_phone', 'contact-to-phone', { first_name: String(row.first_name ?? ''), last_name: String(row.last_name ?? ''), email: String(row.email ?? '') }, { description: 'Resolve phone.' }))
   // ctx.dataset is idempotent by dataset key + row key; reruns reuse completed rows.
@@ -21599,7 +21895,7 @@ function buildToolExecuteBaseEnvelope(input2) {
     ...summaryEntries.length > 0 ? { summary: input2.summary } : {},
     next: {
       inspect: inspectCommand,
-      playDebugging: "When fixing a play getter, inspect the actual play run table with runs get / inspect rows; do not copy CLI preview paths blindly.",
+      playDebugging: "When fixing a play getter, inspect returned dataset handles with runs get and export rows with runs export; do not copy CLI preview paths blindly.",
       ...input2.listConversion ? {
         expandToPlay: "Use stable map and step keys so reruns are idempotent: completed rows are reused, and only missing or stale work runs again.",
         listSourcePath: input2.listConversion.sourcePath ?? "auto-detected list in the CLI response preview"
@@ -21611,7 +21907,7 @@ function buildToolExecuteBaseEnvelope(input2) {
           title: "output",
           lines: [
             `${input2.listConversion.rows.length} row(s) extracted from ${input2.listConversion.sourcePath ?? "auto-detected list"}`,
-            "paths above are observed from this execute response; use run table rows to debug play getters",
+            "paths above are observed from this execute response; use runs get and runs export to validate play output",
             `columns: ${JSON.stringify(Object.keys(input2.listConversion.rows[0] ?? {}))}`,
             `preview: ${JSON.stringify(input2.listConversion.rows.slice(0, 5))}`
           ]
@@ -21691,7 +21987,7 @@ async function executeTool(args) {
     listConversion,
     summary
   });
-  if (parsed.outputFormat === "json" || parsed.outputFormat === "auto" && shouldEmitJson()) {
+  if (!parsed.outPath && (parsed.outputFormat === "json" || parsed.outputFormat === "auto" && shouldEmitJson())) {
     printCommandEnvelope(baseEnvelope, { json: true });
     return 0;
   }
@@ -21713,6 +22009,17 @@ async function executeTool(args) {
     return 0;
   }
   if (!listConversion) {
+    if (parsed.outPath) {
+      const error = new Error(
+        `${parsed.toolId} did not expose row-shaped output to write as CSV. Re-run with --json to inspect the raw tool response.`
+      );
+      if (argsWantJson(args)) {
+        printJsonError(error);
+      } else {
+        console.error(error.message);
+      }
+      return 1;
+    }
     if (parsed.outputFormat === "csv" || parsed.outputFormat === "csv_file") {
       const jsonPath = writeJsonOutputFile(
         rawResponse,
@@ -21734,7 +22041,8 @@ async function executeTool(args) {
   }
   const csv = writeCsvOutputFile(
     listConversion.rows,
-    `${parsed.toolId}_output`
+    `${parsed.toolId}_output`,
+    parsed.outPath ? { outPath: parsed.outPath } : void 0
   );
   const seededScript = seedToolListScript({
     toolId: parsed.toolId,
@@ -21807,6 +22115,27 @@ async function executeTool(args) {
     );
     return 0;
   }
+  if (parsed.outPath) {
+    printCommandEnvelope(
+      {
+        ...materializedEnvelope,
+        csv_path: csv.path,
+        row_count: csv.rowCount,
+        row_count_returned: csv.rowCount,
+        columns: csv.columns,
+        preview: csv.preview,
+        list_strategy: listConversion.strategy,
+        list_source_path: listConversion.sourcePath,
+        summary
+      },
+      {
+        json: argsWantJson(args) || shouldEmitJson(),
+        text: `Wrote ${csv.rowCount} row(s) to ${csv.path}
+`
+      }
+    );
+    return 0;
+  }
   if (parsed.noPreview) {
     printCommandEnvelope(
       {
@@ -23991,6 +24320,7 @@ Exit codes:
   registerWorkflowCommands(program);
   registerSecretsCommands(program);
   registerBillingCommands(program);
+  registerMonitorsCommands(program);
   registerOrgCommands(program);
   registerEnrichCommand(program);
   registerCsvCommands(program);