deepline 0.1.145 → 0.1.147

package/dist/cli/index.mjs

@@ -604,10 +604,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: [
@@ -618,52 +619,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
@@ -8319,9 +8347,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(
@@ -11007,6 +11036,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;
@@ -11018,6 +11050,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") {
@@ -11026,13 +11059,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 === "{}") {
@@ -11076,9 +11137,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}`);
     }
@@ -11489,7 +11547,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)
   };
@@ -18970,6 +19028,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 });
@@ -20157,7 +20430,7 @@ import { join as join10, resolve as resolve10 } from "path";
 // src/tool-output.ts
 import { mkdirSync as mkdirSync7, writeFileSync as writeFileSync11 } from "fs";
 import { homedir as homedir9 } from "os";
-import { join as join9 } from "path";
+import { dirname as dirname9, join as join9 } from "path";
 function isPlainObject(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -20230,16 +20503,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 ?? "");
@@ -20263,9 +20544,9 @@ function writeJsonOutputFile(payload, stem) {
   writeFileSync11(outputPath, JSON.stringify(payload, null, 2), "utf-8");
   return outputPath;
 }
-function writeCsvOutputFile(rows, stem) {
-  const outputDir = ensureOutputDir();
-  const outputPath = join9(outputDir, `${stem}_${Date.now()}.csv`);
+function writeCsvOutputFile(rows, stem, options) {
+  const outputPath = options?.outPath ? options.outPath : join9(ensureOutputDir(), `${stem}_${Date.now()}.csv`);
+  mkdirSync7(dirname9(outputPath), { recursive: true });
   const seen = /* @__PURE__ */ new Set();
   const columns = [];
   for (const row of rows) {
@@ -20794,6 +21075,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>",
@@ -20815,6 +21097,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"
@@ -20827,6 +21112,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);
@@ -21277,7 +21563,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 } : {}
@@ -21484,12 +21770,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]) {
@@ -21521,9 +21808,13 @@ function parseExecuteOptions(args) {
       noPreview = true;
       continue;
     }
+    if ((arg === "--out" || arg === "-o") && args[index + 1]) {
+      outPath = resolve10(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";
@@ -21567,9 +21858,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.
@@ -21629,7 +21925,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"
@@ -21641,7 +21937,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))}`
           ]
@@ -21721,7 +22017,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;
   }
@@ -21743,6 +22039,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,
@@ -21764,7 +22071,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,
@@ -21837,6 +22145,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(
       {
@@ -21857,7 +22186,7 @@ async function executeTool(args) {
 
 // src/cli/commands/workflow.ts
 import { mkdir as mkdir4, readFile as readFile2, writeFile as writeFile4 } from "fs/promises";
-import { dirname as dirname9, join as join11, resolve as resolve11 } from "path";
+import { dirname as dirname10, join as join11, resolve as resolve11 } from "path";
 
 // src/cli/workflow-to-play.ts
 import { createHash as createHash3 } from "crypto";
@@ -22136,7 +22465,7 @@ async function transformOne(api, workflowId, outDir, publish) {
       { workflowName: workflow.name, version: revision.version }
     );
     const file = join11(resolve11(outDir), `${compiled.playName}.play.ts`);
-    await mkdir4(dirname9(file), { recursive: true });
+    await mkdir4(dirname10(file), { recursive: true });
     await writeFile4(file, compiled.sourceCode, "utf8");
     let published = false;
     if (publish) {
@@ -22394,12 +22723,12 @@ import {
   writeFileSync as writeFileSync14
 } from "fs";
 import { homedir as homedir10 } from "os";
-import { dirname as dirname11, isAbsolute as isAbsolute2, join as join13, relative as relative2, resolve as resolve12 } from "path";
+import { dirname as dirname12, isAbsolute as isAbsolute2, join as join13, relative as relative2, resolve as resolve12 } from "path";
 
 // src/cli/skills-sync.ts
 import { spawn as spawn2, spawnSync as spawnSync2 } from "child_process";
 import { existsSync as existsSync10, mkdirSync as mkdirSync8, readFileSync as readFileSync10, writeFileSync as writeFileSync13 } from "fs";
-import { dirname as dirname10, join as join12 } from "path";
+import { dirname as dirname11, join as join12 } from "path";
 
 // ../shared_libs/cli/install-commands.json
 var install_commands_default = {
@@ -22533,7 +22862,7 @@ function sdkSkillsVersionPath(baseUrl) {
   return join12(sdkCliStateDirPath(baseUrl), "skills-version");
 }
 function legacySdkSkillsVersionPath(baseUrl) {
-  return join12(dirname10(sdkCliStateDirPath(baseUrl)), "sdk-skills", ".version");
+  return join12(dirname11(sdkCliStateDirPath(baseUrl)), "sdk-skills", ".version");
 }
 function readSdkSkillsLocalVersion(baseUrl) {
   const pluginVersion = readPluginSkillsVersion();
@@ -22548,7 +22877,7 @@ function readSdkSkillsLocalVersion(baseUrl) {
 }
 function writeLocalSkillsVersion(baseUrl, version) {
   const path = sdkSkillsVersionPath(baseUrl);
-  mkdirSync8(dirname10(path), { recursive: true });
+  mkdirSync8(dirname11(path), { recursive: true });
   writeFileSync13(path, `${version}
 `, "utf-8");
 }
@@ -22877,7 +23206,7 @@ function findRepoBackedSdkRoot(startPath) {
     if (existsSync11(join13(current, "sdk", "package.json")) && existsSync11(join13(current, "sdk", "bin", "deepline-dev.ts"))) {
       return current;
     }
-    const parent = dirname11(current);
+    const parent = dirname12(current);
     if (parent === current) return null;
     current = parent;
   }
@@ -22907,7 +23236,7 @@ function resolveUpdatePlan(options = {}) {
   const env = options.env ?? process.env;
   const homeDir2 = options.homeDir ?? homedir10();
   const entrypoint = options.entrypoint ?? (process.argv[1] ? resolve12(process.argv[1]) : "");
-  const sourceRoot = entrypoint ? findRepoBackedSdkRoot(dirname11(entrypoint)) : null;
+  const sourceRoot = entrypoint ? findRepoBackedSdkRoot(dirname12(entrypoint)) : null;
   if (sourceRoot) {
     return {
       kind: "source",
@@ -22986,7 +23315,7 @@ function writeAutoUpdateFailure(plan, exitCode) {
     manualCommand: plan.manualCommand
   };
   try {
-    mkdirSync9(dirname11(path), { recursive: true });
+    mkdirSync9(dirname12(path), { recursive: true });
     writeFileSync14(path, `${JSON.stringify(marker, null, 2)}
 `, "utf8");
   } catch {
@@ -23073,7 +23402,7 @@ function runCommand(command, args, env = process.env) {
   });
 }
 function writeSidecarLauncher(input2) {
-  mkdirSync9(dirname11(input2.path), { recursive: true });
+  mkdirSync9(dirname12(input2.path), { recursive: true });
   if (process.platform === "win32") {
     writeFileSync14(
       input2.path,
@@ -23110,7 +23439,7 @@ async function runPythonSidecarUpdatePlan(plan) {
   writeFileSync14(join13(tempDir, "package.json"), NPM_SDK_SIDECAR_PACKAGE_JSON);
   const env = {
     ...process.env,
-    PATH: `${dirname11(plan.nodeBin)}${process.platform === "win32" ? ";" : ":"}${process.env.PATH ?? ""}`
+    PATH: `${dirname12(plan.nodeBin)}${process.platform === "win32" ? ";" : ":"}${process.env.PATH ?? ""}`
   };
   const installExitCode = await runCommand(
     plan.npmCommand,
@@ -24030,6 +24359,7 @@ Exit codes:
   registerWorkflowCommands(program);
   registerSecretsCommands(program);
   registerBillingCommands(program);
+  registerMonitorsCommands(program);
   registerOrgCommands(program);
   registerEnrichCommand(program);
   registerCsvCommands(program);