deepline 0.3.325 → 0.3.327

package/dist/cli/{chunk-YXRPWMGN.js → chunk-NWIJLTRL.js}

@@ -3,11 +3,14 @@
 
 
 
-var _chunkXNL3SEMCjs = require('./chunk-XNL3SEMC.js');
+var _chunkAFNEQ43Jjs = require('./chunk-AFNEQ43J.js');
 
 
+var _chunkAID3OYVJjs = require('./chunk-AID3OYVJ.js');
 
-var _chunkKZNFYOHXjs = require('./chunk-KZNFYOHX.js');
+
+
+var _chunkMOP6D7Z5js = require('./chunk-MOP6D7Z5.js');
 
 
 
@@ -18,14 +21,14 @@ var _chunkKZNFYOHXjs = require('./chunk-KZNFYOHX.js');
 var _chunkNXDRDJ4Kjs = require('./chunk-NXDRDJ4K.js');
 
 
-var _chunkMNKDSR2Jjs = require('./chunk-MNKDSR2J.js');
 
+var _chunk4ZARCCPTjs = require('./chunk-4ZARCCPT.js');
 
 
 
 
-var _chunkQJBJZVG6js = require('./chunk-QJBJZVG6.js');
 
+var _chunkQJBJZVG6js = require('./chunk-QJBJZVG6.js');
 
 
 
@@ -33,11 +36,11 @@ var _chunkQJBJZVG6js = require('./chunk-QJBJZVG6.js');
 
 
 
-var _chunkQQ2FG5W3js = require('./chunk-QQ2FG5W3.js');
+var _chunkUROXKPNDjs = require('./chunk-UROXKPND.js');
 
 
 
-var _chunkPVDQ55PSjs = require('./chunk-PVDQ55PS.js');
+var _chunkDM3SHV6Ujs = require('./chunk-DM3SHV6U.js');
 
 
 var _chunk7P5AA3SNjs = require('./chunk-7P5AA3SN.js');
@@ -82,10 +85,10 @@ var ToolCallRecovery = class _ToolCallRecovery {
   }
 };
 function pendingToolExecutionPath(input) {
-  const config = _chunkPVDQ55PSjs.resolveConfig.call(void 0, );
+  const config = _chunkDM3SHV6Ujs.resolveConfig.call(void 0, );
   const fingerprint = _crypto.createHash.call(void 0, "sha256").update(config.baseUrl).update("\0").update(_crypto.createHash.call(void 0, "sha256").update(config.apiKey).digest("hex")).update("\0").update(input.toolId).update("\0").update(_chunkNXDRDJ4Kjs.stableStringify.call(void 0, input.params)).update("\0").update(input.responseIntent).digest("hex");
   return _path.join.call(void 0, 
-    _chunkPVDQ55PSjs.sdkCliStateDirPath.call(void 0, config.baseUrl),
+    _chunkDM3SHV6Ujs.sdkCliStateDirPath.call(void 0, config.baseUrl),
     `pending-tool-execution-${fingerprint}.json`
   );
 }
@@ -517,12 +520,12 @@ function categoryEnumerationRender(summaries) {
   };
 }
 async function listToolCategories(emitJson, compact) {
-  const client = new (0, _chunkMNKDSR2Jjs.DeeplineClient)();
+  const client = new (0, _chunk4ZARCCPTjs.DeeplineClient)();
   const rawTools = await client.listTools({ compact });
   const items = rawTools.map(toListedTool);
   const summaries = aggregateCategorySummaries(rawTools);
   const outputItems = compact ? items.map(compactTool) : items;
-  _chunkQQ2FG5W3js.printCommandEnvelope.call(void 0, 
+  _chunkUROXKPNDjs.printCommandEnvelope.call(void 0, 
     {
       tools: outputItems,
       count: outputItems.length,
@@ -541,7 +544,7 @@ 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) {
-    _chunkQQ2FG5W3js.printJson.call(void 0, {
+    _chunkUROXKPNDjs.printJson.call(void 0, {
       ok: false,
       exitCode: 4,
       code: "TOOL_CATEGORY_NOT_FOUND",
@@ -555,13 +558,13 @@ function unknownCategoryError(category, summaries, emitJson) {
   const render = categoryEnumerationRender(summaries);
   console.error(message);
   console.error("");
-  console.error(_chunkQQ2FG5W3js.renderCommandEnvelopeText.call(void 0, { render }).trimEnd());
+  console.error(_chunkUROXKPNDjs.renderCommandEnvelopeText.call(void 0, { render }).trimEnd());
   console.error("");
   console.error(`Valid categories: ${known.join(", ")}`);
   return 4;
 }
 async function listToolsInCategory(category, emitJson) {
-  const client = new (0, _chunkMNKDSR2Jjs.DeeplineClient)();
+  const client = new (0, _chunk4ZARCCPTjs.DeeplineClient)();
   const rawTools = await client.listTools({
     categories: category,
     compact: false
@@ -598,7 +601,7 @@ async function listToolsInCategory(category, emitJson) {
       }
     ]
   };
-  _chunkQQ2FG5W3js.printCommandEnvelope.call(void 0, 
+  _chunkUROXKPNDjs.printCommandEnvelope.call(void 0, 
     {
       category,
       total: rows.length,
@@ -611,7 +614,7 @@ async function listToolsInCategory(category, emitJson) {
   return 0;
 }
 async function listToolsForCategoryFilter(requestedCategories, emitJson, compact) {
-  const client = new (0, _chunkMNKDSR2Jjs.DeeplineClient)();
+  const client = new (0, _chunk4ZARCCPTjs.DeeplineClient)();
   const items = (await client.listTools({
     categories: requestedCategories.join(","),
     compact
@@ -640,7 +643,7 @@ async function listToolsForCategoryFilter(requestedCategories, emitJson, compact
     ]
   };
   const outputItems = compact ? items.map(compactTool) : items;
-  _chunkQQ2FG5W3js.printCommandEnvelope.call(void 0, 
+  _chunkUROXKPNDjs.printCommandEnvelope.call(void 0, 
     {
       tools: outputItems,
       count: outputItems.length,
@@ -659,13 +662,13 @@ async function listTools(category, options = {}) {
   const positional = _nullishCoalesce(_optionalChain([category, 'optionalAccess', _9 => _9.trim, 'call', _10 => _10()]), () => ( ""));
   const flagCategories = (_nullishCoalesce(options.categories, () => ( ""))).split(",").map((item) => item.trim()).filter(Boolean);
   const compact = options.compact !== false;
-  const emitJson = options.json === true || _chunkQQ2FG5W3js.shouldEmitJson.call(void 0, );
+  const emitJson = options.json === true || _chunkUROXKPNDjs.shouldEmitJson.call(void 0, );
   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) {
-        _chunkQQ2FG5W3js.printJson.call(void 0, {
+        _chunkUROXKPNDjs.printJson.call(void 0, {
           ok: false,
           exitCode: 2,
           code: "TOOL_LIST_CATEGORY_CONFLICT",
@@ -692,7 +695,7 @@ async function grepTools(queryInput, options = {}) {
     console.error("Usage: deepline tools grep <query> [--json]");
     return 1;
   }
-  const client = new (0, _chunkMNKDSR2Jjs.DeeplineClient)();
+  const client = new (0, _chunk4ZARCCPTjs.DeeplineClient)();
   const requestedCategories = options.categories ? options.categories.split(",").map((item) => item.trim()).filter(Boolean) : [];
   const mode = _nullishCoalesce(options.mode, () => ( "all"));
   const jsonOutput = options.json === true;
@@ -735,7 +738,7 @@ async function grepTools(queryInput, options = {}) {
     query,
     mode
   }) : null;
-  _chunkQQ2FG5W3js.printCommandEnvelope.call(void 0, 
+  _chunkUROXKPNDjs.printCommandEnvelope.call(void 0, 
     {
       tools: outputTools,
       count: outputTools.length,
@@ -753,7 +756,7 @@ async function grepTools(queryInput, options = {}) {
       } : {},
       commandTemplates: TOOL_COMMAND_TEMPLATES
     },
-    { json: options.json || _chunkQQ2FG5W3js.shouldEmitJson.call(void 0, ) }
+    { json: options.json || _chunkUROXKPNDjs.shouldEmitJson.call(void 0, ) }
   );
   return 0;
 }
@@ -909,7 +912,7 @@ Examples:
       json: Boolean(options.json)
     });
   });
-  _chunkKZNFYOHXjs.registerDeprecatedSearchCommand.call(void 0, tools, () => ["tools", "monitors"]);
+  _chunkMOP6D7Z5js.registerDeprecatedSearchCommand.call(void 0, tools, () => ["tools", "monitors"]);
   tools.command("grep <query>").description(
     "Literal grep over tool ids, descriptions, categories, and input fields."
   ).addHelpText(
@@ -1010,7 +1013,7 @@ Examples:
         process.exitCode = await narrowView();
         return;
       }
-      const { describeAnything } = await Promise.resolve().then(() => _interopRequireWildcard(require("./describe-M26LHDBQ.js")));
+      const { describeAnything } = await Promise.resolve().then(() => _interopRequireWildcard(require("./describe-QENLDLM2.js")));
       process.exitCode = await describeAnything(
         toolId,
         { ...options, kinds: ["tools", "monitors"], fetchedTool: metadata },
@@ -1020,12 +1023,12 @@ Examples:
     });
   };
   addToolMetadataCommand(
-    _chunkXNL3SEMCjs.addDescribeOptions.call(void 0, 
+    _chunkAFNEQ43Jjs.addDescribeOptions.call(void 0, 
       tools.command("describe <toolId>", { hidden: true }).alias("get"),
       { json: false }
     )
   );
-  tools.command("execute <toolId>").description("Execute a tool by id.").addHelpText(
+  tools.command("execute <toolId>").alias("call").description("Execute a tool by id.").addHelpText(
     "after",
     `
 Notes:
@@ -1084,22 +1087,7 @@ Examples:
     "--recovery-timeout-ms <milliseconds>",
     "Maximum wait for a keyed execution to finish (default: 900000)"
   ).action(async (toolId, options) => {
-    const args = [
-      toolId,
-      ...options.param.flatMap((value) => ["--param", value]),
-      ...options.json === true ? ["--json"] : [],
-      ...typeof options.json === "string" ? ["--json", options.json] : [],
-      ...options.input ? ["--input", options.input] : [],
-      ...options.payload ? ["--payload", options.payload] : [],
-      ...options.timeout ? ["--timeout", options.timeout] : [],
-      ...options.outputFormat ? ["--output-format", options.outputFormat] : [],
-      ...options.out ? ["--out", options.out] : [],
-      ...options.preview === false ? ["--no-preview"] : [],
-      ...options.idempotencyKey ? ["--idempotency-key", options.idempotencyKey] : [],
-      ...options.recover ? ["--recover"] : [],
-      ...options.recoveryTimeoutMs ? ["--recovery-timeout-ms", options.recoveryTimeoutMs] : []
-    ];
-    process.exitCode = await executeTool(args);
+    process.exitCode = await executeTool(toolId, options);
   });
 }
 async function getTool(toolId, options = {}, compatibilityMetadata) {
@@ -1107,7 +1095,7 @@ async function getTool(toolId, options = {}, compatibilityMetadata) {
     console.error("Usage: deepline tools describe <toolId> [--json]");
     return 1;
   }
-  const client = new (0, _chunkMNKDSR2Jjs.DeeplineClient)();
+  const client = new (0, _chunk4ZARCCPTjs.DeeplineClient)();
   let tool;
   try {
     tool = await _asyncNullishCoalesce(compatibilityMetadata, async () => ( await client.getTool(toolId)));
@@ -1161,7 +1149,7 @@ async function getTool(toolId, options = {}, compatibilityMetadata) {
     const lines = toolPricingOnlyLines(tool, toolId);
     if (inferenceQuote)
       lines.push(...inferenceQuoteSummaryLines(inferenceQuote));
-    _chunkQQ2FG5W3js.printCommandEnvelope.call(void 0, 
+    _chunkUROXKPNDjs.printCommandEnvelope.call(void 0, 
       {
         toolId: String(tool.toolId || toolId),
         cost: Capability.fromCatalogEntry(tool).describe().customerCost(),
@@ -1179,7 +1167,7 @@ async function getTool(toolId, options = {}, compatibilityMetadata) {
   }
   if ((options.schemaOnly || options.examplesOnly || options.gettersOnly) && !isMonitorTypeTool(tool) && !isPlayLikeTool(tool) && (options.json || options.contractJson)) {
     const contract = toolContractJsonForDescribe(tool, toolId);
-    _chunkQQ2FG5W3js.printCompactJson.call(void 0, {
+    _chunkUROXKPNDjs.printCompactJson.call(void 0, {
       toolId: contract.toolId,
       ...options.schemaOnly ? {
         inputSchema: contract.inputSchema,
@@ -1202,7 +1190,7 @@ async function getTool(toolId, options = {}, compatibilityMetadata) {
     return 0;
   }
   if (options.contractJson) {
-    _chunkQQ2FG5W3js.printCompactJson.call(void 0, {
+    _chunkUROXKPNDjs.printCompactJson.call(void 0, {
       ...toolContractJsonForDescribe(tool, toolId),
       ...modelDescription ? { modelOptions: modelDescription } : {},
       ...inferenceQuote ? { inferenceQuote } : {}
@@ -1211,7 +1199,7 @@ async function getTool(toolId, options = {}, compatibilityMetadata) {
   }
   const emitJson = options.json === true;
   if (emitJson) {
-    _chunkQQ2FG5W3js.printCompactJson.call(void 0, {
+    _chunkUROXKPNDjs.printCompactJson.call(void 0, {
       ...toolMetadataJsonForDescribe(tool, toolId),
       ...modelDescription ? { modelOptions: modelDescription } : {},
       ...inferenceQuote ? { inferenceQuote } : {}
@@ -1242,8 +1230,8 @@ ${formatModelDescription(modelDescription)}`);
     if (inferenceQuote) printInferenceQuoteSummary(inferenceQuote);
     return 0;
   }
-  if (_chunkQQ2FG5W3js.shouldEmitJson.call(void 0, )) {
-    _chunkQQ2FG5W3js.printCompactJson.call(void 0, {
+  if (_chunkUROXKPNDjs.shouldEmitJson.call(void 0, )) {
+    _chunkUROXKPNDjs.printCompactJson.call(void 0, {
       ...toolContractJsonForDescribe(tool, toolId),
       ...modelDescription ? { modelOptions: modelDescription } : {},
       ...inferenceQuote ? { inferenceQuote } : {}
@@ -1527,7 +1515,7 @@ function describedTool(tool, requestedToolId) {
       description,
       cost: stringField2(recordField(tool, "pricing"), "displayText") || void 0,
       guidance: [],
-      inputs: _chunkXNL3SEMCjs.schemaFields.call(void 0, 
+      inputs: _chunkAFNEQ43Jjs.schemaFields.call(void 0, 
         recordField(tool, "payload_schema", "payloadSchema")
       ),
       outputs: [],
@@ -1559,7 +1547,7 @@ function describedTool(tool, requestedToolId) {
         "rawToolOutputPaths"
       ).map((path) => String(path).replace(/^toolResponse\.raw\./, ""));
       const node = roots.flatMap((root) => paths.map((path) => schemaNodeAt(root, path))).find(isRecord);
-      const { fields, ...typed } = _chunkXNL3SEMCjs.schemaField.call(void 0, name, node, true);
+      const { fields, ...typed } = _chunkAFNEQ43Jjs.schemaField.call(void 0, name, node, true);
       const valueType = stringField2(_nullishCoalesce(details.get(name), () => ( {})), "valueType");
       const field = {
         ...typed,
@@ -1594,12 +1582,12 @@ function describedTool(tool, requestedToolId) {
         (line) => typeof line === "string" && /[a-z0-9]/i.test(line)
       )
     ],
-    rateLimit: _chunkXNL3SEMCjs.rateLimitSummary.call(void 0, 
+    rateLimit: _chunkAFNEQ43Jjs.rateLimitSummary.call(void 0, 
       recordField(contract, "executionMetadata").configuredRateLimits
     ),
-    inputs: _chunkXNL3SEMCjs.schemaFields.call(void 0, jsonSchemaOf(recordField(contract, "inputSchema"))),
+    inputs: _chunkAFNEQ43Jjs.schemaFields.call(void 0, jsonSchemaOf(recordField(contract, "inputSchema"))),
     outputs: [...lists, ...values].map(({ field }) => field),
-    rawResponse: _chunkXNL3SEMCjs.schemaFields.call(void 0, outputSchema),
+    rawResponse: _chunkAFNEQ43Jjs.schemaFields.call(void 0, outputSchema),
     runner: playReference ? { via: "play", reference: playReference } : { via: "tool", toolId: String(contract.toolId) }
   };
 }
@@ -1808,6 +1796,7 @@ function printToolExamplesOnly(tool, requestedToolId) {
   console.log(`Use in a play:`);
   console.log("```ts");
   console.log("const result = await ctx.tools.execute({");
+  console.log("  staleAfterSeconds: 0,");
   console.log(`  id: '${stableStepIdForTool(toolId)}',`);
   console.log(`  tool: '${toolId}',`);
   console.log(
@@ -2423,9 +2412,9 @@ function apifySyncRecoveryNext(rawResponse) {
   const getDatasetItemsTool = stringField2(getDatasetItems, "tool");
   const getDatasetItemsPayload = recordField(getDatasetItems, "payload");
   return {
-    getActorRun: `deepline tools execute ${getActorRunTool} --input ${shellQuote(JSON.stringify(getActorRunPayload))} --json`,
+    getActorRun: `deepline tools execute ${getActorRunTool} --input ${_chunkAID3OYVJjs.shellQuote.call(void 0, JSON.stringify(getActorRunPayload))} --json`,
     ...getDatasetItemsTool && Object.keys(getDatasetItemsPayload).length > 0 ? {
-      getDatasetItems: `deepline tools execute ${getDatasetItemsTool} --input ${shellQuote(JSON.stringify(getDatasetItemsPayload))} --json`
+      getDatasetItems: `deepline tools execute ${getDatasetItemsTool} --input ${_chunkAID3OYVJjs.shellQuote.call(void 0, JSON.stringify(getDatasetItemsPayload))} --json`
     } : {}
   };
 }
@@ -2545,87 +2534,63 @@ function parseJsonObjectArgument(raw, flagName) {
   }
   return parsed;
 }
-function parseExecuteOptions(args) {
-  const toolId = args[0];
+function toolExecuteJsonOption(value) {
+  const legacyInput = typeof value === "string" ? value : void 0;
+  return {
+    requested: value === true || legacyInput !== void 0,
+    legacyInput
+  };
+}
+function parseExecuteOptions(toolId, options, output) {
   if (!toolId) {
     throw new Error(
       `Usage: deepline tools execute <toolId> [--param key=value ...] [--input '{"k":"v"}'] [--timeout <duration>] [--recover | --idempotency-key <key>] [--recovery-timeout-ms <ms>] [--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;
-  let timeoutMs;
-  let idempotencyKey;
-  let recover = false;
+  let outputFormat = output.requested ? "json" : "auto";
   let recoveryTimeoutMs;
-  for (let index = 1; index < args.length; index += 1) {
-    const arg = args[index];
-    if ((arg === "--param" || arg === "-p") && args[index + 1]) {
-      const kv = args[++index];
-      const eqIdx = kv.indexOf("=");
-      if (eqIdx > 0) params[kv.slice(0, eqIdx)] = kv.slice(eqIdx + 1);
-      continue;
-    }
-    if (arg === "--json") {
-      const next = args[index + 1];
-      outputFormat = "json";
-      if (next && !next.startsWith("--")) {
-        Object.assign(
-          params,
-          parseJsonObjectArgument(args[++index], "--json")
-        );
-      }
-      continue;
-    }
-    if ((arg === "--input" || arg === "--payload") && args[index + 1]) {
-      Object.assign(params, parseJsonObjectArgument(args[++index], arg));
-      continue;
-    }
-    if (arg === "--timeout" && args[index + 1]) {
-      timeoutMs = parseToolExecuteTimeout(args[++index]);
-      continue;
-    }
-    if (arg === "--output-format" && args[index + 1]) {
-      outputFormat = normalizeOutputFormat(args[++index]);
-      continue;
-    }
-    if (arg === "--no-preview") {
-      noPreview = true;
-      continue;
-    }
-    if (arg === "--idempotency-key" && args[index + 1]) {
-      idempotencyKey = args[++index];
-      continue;
-    }
-    if (arg === "--recover") {
-      recover = true;
-      continue;
-    }
-    if (arg === "--recovery-timeout-ms" && args[index + 1]) {
-      const parsed = Number(args[++index]);
-      if (!Number.isFinite(parsed) || parsed < 0) {
-        throw new Error("--recovery-timeout-ms must be a non-negative number.");
-      }
-      recoveryTimeoutMs = parsed;
-      continue;
-    }
-    if ((arg === "--out" || arg === "-o") && args[index + 1]) {
-      outPath = _path.resolve.call(void 0, args[++index]);
-      continue;
+  for (const kv of _nullishCoalesce(options.param, () => ( []))) {
+    const eqIdx = kv.indexOf("=");
+    if (eqIdx > 0) params[kv.slice(0, eqIdx)] = kv.slice(eqIdx + 1);
+  }
+  if (output.legacyInput !== void 0) {
+    Object.assign(
+      params,
+      parseJsonObjectArgument(output.legacyInput, "--json")
+    );
+  }
+  if (options.input !== void 0) {
+    Object.assign(params, parseJsonObjectArgument(options.input, "--input"));
+  }
+  if (options.payload !== void 0) {
+    Object.assign(
+      params,
+      parseJsonObjectArgument(options.payload, "--payload")
+    );
+  }
+  if (options.outputFormat !== void 0) {
+    outputFormat = normalizeOutputFormat(options.outputFormat);
+  }
+  if (options.idempotencyKey !== void 0) {
+    _chunk4ZARCCPTjs.validateExecutionIdempotencyKey.call(void 0, options.idempotencyKey);
+  }
+  if (options.recoveryTimeoutMs !== void 0) {
+    const parsed = Number(options.recoveryTimeoutMs);
+    if (!options.recoveryTimeoutMs.trim() || !Number.isFinite(parsed) || parsed < 0) {
+      throw new Error("--recovery-timeout-ms must be a non-negative number.");
     }
-    throw new Error(`Unknown option: ${arg}`);
+    recoveryTimeoutMs = parsed;
   }
   return {
     toolId,
     params,
     outputFormat,
-    noPreview,
-    outPath,
-    timeoutMs,
-    idempotencyKey,
-    recover,
+    noPreview: options.preview === false,
+    outPath: options.out !== void 0 ? _path.resolve.call(void 0, options.out) : null,
+    timeoutMs: options.timeout !== void 0 ? parseToolExecuteTimeout(options.timeout) : void 0,
+    idempotencyKey: options.idempotencyKey,
+    recover: options.recover === true,
     recoveryTimeoutMs
   };
 }
@@ -2650,9 +2615,6 @@ function parseToolExecuteTimeout(raw) {
 function safeFileStem(value) {
   return value.trim().replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64) || "tool";
 }
-function shellQuote(value) {
-  return `'${value.replace(/'/g, `'\\''`)}'`;
-}
 function powerShellQuote(value) {
   return `'${value.replace(/'/g, "''")}'`;
 }
@@ -2682,6 +2644,7 @@ function seedToolListScript(input) {
 
 export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
   const result = await ctx.tools.execute({
+    staleAfterSeconds: 0,
     id: ${JSON.stringify(input.toolId)},
     tool: ${JSON.stringify(input.toolId)},
     input: ${JSON.stringify(input.payload)},
@@ -2699,7 +2662,7 @@ export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
   // 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.
+  // ctx.dataset is idempotent for completed rows during same-run recovery. New runs follow each call's freshness.
   const enrichedData = await ctx
     .dataset('enriched_data', rows)
     .run({
@@ -2720,10 +2683,16 @@ export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
     path: scriptPath,
     sourceCode: script,
     projectDir,
-    macCopyCommand: `mkdir -p ${shellQuote(projectDir)} && cp ${shellQuote(scriptPath)} ${shellQuote(`${projectDir}/${fileName}`)}`,
+    macCopyCommand: `mkdir -p ${_chunkAID3OYVJjs.shellQuote.call(void 0, projectDir)} && cp ${_chunkAID3OYVJjs.shellQuote.call(void 0, scriptPath)} ${_chunkAID3OYVJjs.shellQuote.call(void 0, `${projectDir}/${fileName}`)}`,
     windowsCopyCommand: `New-Item -ItemType Directory -Force -Path ${powerShellQuote(projectDir.replace(/\//g, "\\"))} | Out-Null; Copy-Item -LiteralPath ${powerShellQuote(scriptPath)} -Destination ${powerShellQuote(`${projectDir.replace(/\//g, "\\")}\\${fileName}`)}`
   };
 }
+function toolExecutionInspection(input) {
+  return {
+    inspect: input.idempotencyKey !== void 0 ? `deepline executions get --idempotency-key ${_chunkAID3OYVJjs.shellQuote.call(void 0, input.idempotencyKey)} --json` : `deepline describe ${_chunkAID3OYVJjs.shellQuote.call(void 0, input.toolId)} --json`,
+    inspectDescription: input.idempotencyKey !== void 0 ? "Read the saved execution without starting new work." : "Read the tool contract; this unkeyed call has no saved recovery identity."
+  };
+}
 function buildToolExecuteBaseEnvelope(input) {
   const envelope = commandEnvelopeFromRawResponse(input.rawResponse);
   const guidanceLines = toolExecuteExitCode(envelope) !== 0 || input.listExpected === true && !input.listConversion ? toolGuidanceLines(input.guidance) : [];
@@ -2748,8 +2717,8 @@ function buildToolExecuteBaseEnvelope(input) {
     envelope,
     "output"
   );
-  const billingLookup = typeof envelope.job_id === "string" && envelope.job_id.trim() ? `deepline billing usage --request-id ${shellQuote(envelope.job_id)} --json` : null;
-  const inspectCommand = `deepline tools execute ${input.toolId} --input ${shellQuote(JSON.stringify(input.params))} --json`;
+  const billingLookup = typeof envelope.job_id === "string" && envelope.job_id.trim() ? `deepline billing usage --request-id ${_chunkAID3OYVJjs.shellQuote.call(void 0, envelope.job_id)} --json` : null;
+  const inspection = toolExecutionInspection(input);
   const actions = input.listConversion ? [
     {
       label: "next",
@@ -2767,6 +2736,7 @@ function buildToolExecuteBaseEnvelope(input) {
   if (billingLookup) {
     actions.push({ label: "charge", command: billingLookup });
   }
+  actions.unshift({ label: "inspect", command: inspection.inspect });
   return {
     ...envelope,
     ...input.idempotencyKey ? { idempotency_key: input.idempotencyKey } : {},
@@ -2775,13 +2745,13 @@ function buildToolExecuteBaseEnvelope(input) {
     ...summaryEntries.length > 0 ? { summary: input.summary } : {},
     ...warningMessages.length > 0 ? { warnings: warningMessages } : {},
     next: {
-      inspect: inspectCommand,
+      ...inspection,
       ...billingLookup ? { billing: billingLookup } : {},
       ..._nullishCoalesce(apifyRecovery, () => ( {})),
       ...guidanceLines.length > 0 ? { guidance: input.guidance } : {},
       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.",
       ...input.listConversion ? {
-        expandToPlay: "Use stable map and step keys so reruns are idempotent: completed rows are reused, and only missing or stale work runs again.",
+        expandToPlay: "Use stable map and step keys for recovery within a run. New runs follow each call's explicit freshness.",
         listSourcePath: _nullishCoalesce(input.listConversion.sourcePath, () => ( "auto-detected list in the CLI response preview"))
       } : {}
     },
@@ -2832,6 +2802,7 @@ function buildToolExecuteRowArtifactEnvelope(input) {
   void _next;
   void _local;
   const billingLookup = isRecord(input.baseEnvelope.next) && typeof input.baseEnvelope.next.billing === "string" ? input.baseEnvelope.next.billing : null;
+  const inspection = toolExecutionInspection(input);
   return {
     ...base,
     status: typeof base.status === "string" ? base.status : "completed",
@@ -2873,10 +2844,10 @@ function buildToolExecuteRowArtifactEnvelope(input) {
       windows_powershell: input.seededScript.windowsCopyCommand
     },
     next: {
-      inspect: "Re-run with --json only when you need the raw provider/tool response.",
+      ...inspection,
       ...billingLookup ? { billing: billingLookup } : {},
       listSourcePath: input.rowOutput.sourcePath,
-      expandToPlay: "Use stable map and step keys so reruns are idempotent: completed rows are reused, and only missing or stale work runs again."
+      expandToPlay: "Use stable map and step keys for recovery within a run. New runs follow each call's explicit freshness."
     },
     render: {
       sections: [
@@ -2893,10 +2864,11 @@ function buildToolExecuteRowArtifactEnvelope(input) {
         }
       ],
       actions: [
+        { label: "inspect", command: inspection.inspect },
         ...billingLookup ? [{ label: "charge", command: billingLookup }] : [],
         {
           label: "next",
-          command: "Move the script into a project folder and expand it into a Deepline play. Use stable map and step keys so reruns are idempotent: completed rows are reused, and only missing or stale work runs again."
+          command: "Move the script into a project folder and expand it into a Deepline play. Use stable map and step keys for same-run recovery; choose explicit freshness for calls in new runs."
         },
         {
           label: "macOS/Linux",
@@ -2910,20 +2882,22 @@ function buildToolExecuteRowArtifactEnvelope(input) {
     }
   };
 }
-async function executeTool(args) {
+async function executeTool(toolId, options) {
+  const output = toolExecuteJsonOption(options.json);
+  const wantsJson = _chunkUROXKPNDjs.shouldEmitJson.call(void 0, output.requested);
   let parsed;
   try {
-    parsed = parseExecuteOptions(args);
+    parsed = parseExecuteOptions(toolId, options, output);
   } catch (error) {
-    if (_chunkQQ2FG5W3js.argsWantJson.call(void 0, args)) {
-      _chunkQQ2FG5W3js.printJsonError.call(void 0, error);
+    if (wantsJson) {
+      _chunkUROXKPNDjs.printJsonError.call(void 0, error);
     } else {
       console.error(error instanceof Error ? error.message : String(error));
     }
-    return 1;
+    return error instanceof _chunk7P5AA3SNjs.DeeplineError && error.code === "IDEMPOTENCY_KEY_INVALID" ? 2 : 1;
   }
   const cliInvocationId = _nullishCoalesce(_chunkQJBJZVG6js.getToolExecuteInvocationId.call(void 0, ), () => ( _chunkQJBJZVG6js.beginToolExecuteCommand.call(void 0, )));
-  const client = new (0, _chunkMNKDSR2Jjs.DeeplineClient)();
+  const client = new (0, _chunk4ZARCCPTjs.DeeplineClient)();
   let metadata;
   try {
     metadata = await _chunkQJBJZVG6js.runToolExecuteStage.call(void 0, 
@@ -2937,8 +2911,8 @@ async function executeTool(args) {
         () => findPlayForToolId(client, parsed.toolId, cliInvocationId)
       );
       if (play) {
-        if (_chunkQQ2FG5W3js.argsWantJson.call(void 0, args)) {
-          _chunkQQ2FG5W3js.printJsonError.call(void 0, 
+        if (wantsJson) {
+          _chunkUROXKPNDjs.printJsonError.call(void 0, 
             new Error(playAliasToolErrorMessage(parsed.toolId, play))
           );
         } else {
@@ -2950,8 +2924,8 @@ async function executeTool(args) {
     throw error;
   }
   if (isPlayLikeTool(metadata)) {
-    if (_chunkQQ2FG5W3js.argsWantJson.call(void 0, args)) {
-      _chunkQQ2FG5W3js.printJsonError.call(void 0, 
+    if (wantsJson) {
+      _chunkUROXKPNDjs.printJsonError.call(void 0, 
         new Error(
           playLikeToolExecuteErrorMessage(
             parsed.toolId,
@@ -2987,12 +2961,12 @@ async function executeTool(args) {
       responseIntent,
       ...idempotencyKey ? { idempotencyKey } : {},
       ...parsed.recoveryTimeoutMs !== void 0 ? { recoveryTimeoutMs: parsed.recoveryTimeoutMs } : {},
-      searchRef: _chunkKZNFYOHXjs.recentSearchRef.call(void 0, ),
+      searchRef: _chunkMOP6D7Z5js.recentSearchRef.call(void 0, ),
       cliInvocationId
     }).catch((error) => {
       const guidanceLines = toolGuidanceLines(metadata.guidance);
       if (guidanceLines.length > 0) {
-        if (args.includes("--json") && error instanceof Error) {
+        if (wantsJson && error instanceof Error) {
           Object.assign(error, { guidance: metadata.guidance });
         } else {
           console.error(
@@ -3026,8 +3000,8 @@ async function executeTool(args) {
   );
   const executeExitCode = toolExecuteExitCode(baseEnvelope);
   const delivered = await _chunkQJBJZVG6js.runToolExecuteStage.call(void 0, "output delivery", () => {
-    if (!parsed.outPath && (parsed.outputFormat === "json" || parsed.outputFormat === "auto" && _chunkQQ2FG5W3js.shouldEmitJson.call(void 0, ))) {
-      _chunkQQ2FG5W3js.printCommandEnvelope.call(void 0, baseEnvelope, { json: true });
+    if (!parsed.outPath && (parsed.outputFormat === "json" || parsed.outputFormat === "auto" && _chunkUROXKPNDjs.shouldEmitJson.call(void 0, ))) {
+      _chunkUROXKPNDjs.printCommandEnvelope.call(void 0, baseEnvelope, { json: true });
       return true;
     }
     if (parsed.outputFormat === "json_file") {
@@ -3035,7 +3009,7 @@ async function executeTool(args) {
         rawResponse,
         `payload_${parsed.toolId}`
       );
-      _chunkQQ2FG5W3js.printCommandEnvelope.call(void 0, 
+      _chunkUROXKPNDjs.printCommandEnvelope.call(void 0, 
         {
           ...baseEnvelope,
           local: {
@@ -3049,11 +3023,15 @@ async function executeTool(args) {
     }
     if (!listConversion) {
       if (parsed.outPath) {
+        const inspection = toolExecutionInspection({
+          toolId: parsed.toolId,
+          idempotencyKey
+        });
         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.`
+          `${parsed.toolId} did not expose row-shaped output to write as CSV. ${inspection.inspectDescription} Run: ${inspection.inspect}`
         );
-        if (_chunkQQ2FG5W3js.argsWantJson.call(void 0, args)) {
-          _chunkQQ2FG5W3js.printJsonError.call(void 0, error);
+        if (wantsJson) {
+          _chunkUROXKPNDjs.printJsonError.call(void 0, error);
         } else {
           console.error(error.message);
         }
@@ -3064,18 +3042,18 @@ async function executeTool(args) {
           rawResponse,
           `payload_${parsed.toolId}`
         );
-        _chunkQQ2FG5W3js.printCommandEnvelope.call(void 0, 
+        _chunkUROXKPNDjs.printCommandEnvelope.call(void 0, 
           {
             ...baseEnvelope,
             local: {
               payload_file: jsonPath
             }
           },
-          { json: parsed.outputFormat === "csv_file" || _chunkQQ2FG5W3js.shouldEmitJson.call(void 0, ) }
+          { json: parsed.outputFormat === "csv_file" || _chunkUROXKPNDjs.shouldEmitJson.call(void 0, ) }
         );
         return true;
       }
-      _chunkQQ2FG5W3js.printCommandEnvelope.call(void 0, baseEnvelope, { json: false });
+      _chunkUROXKPNDjs.printCommandEnvelope.call(void 0, baseEnvelope, { json: false });
       return true;
     }
     const rowOutput = _chunkNXDRDJ4Kjs.projectRowOutput.call(void 0, listConversion);
@@ -3090,6 +3068,8 @@ async function executeTool(args) {
       rows: listConversion.rows
     });
     const materializedEnvelope = buildToolExecuteRowArtifactEnvelope({
+      toolId: parsed.toolId,
+      idempotencyKey,
       baseEnvelope,
       csv,
       rowOutput,
@@ -3097,19 +3077,24 @@ async function executeTool(args) {
       seededScript
     });
     if (parsed.outputFormat === "csv_file") {
-      _chunkQQ2FG5W3js.printCommandEnvelope.call(void 0, materializedEnvelope, { json: true });
+      _chunkUROXKPNDjs.printCommandEnvelope.call(void 0, materializedEnvelope, { json: true });
       return true;
     }
     if (parsed.outPath) {
-      _chunkQQ2FG5W3js.printCommandEnvelope.call(void 0, materializedEnvelope, {
-        json: _chunkQQ2FG5W3js.argsWantJson.call(void 0, args) || _chunkQQ2FG5W3js.shouldEmitJson.call(void 0, ),
+      const inspection = toolExecutionInspection({
+        toolId: parsed.toolId,
+        idempotencyKey
+      });
+      _chunkUROXKPNDjs.printCommandEnvelope.call(void 0, materializedEnvelope, {
+        json: wantsJson,
         text: `Wrote ${csv.rowCount} row(s) to ${csv.path}
+inspect: ${inspection.inspect}
 `
       });
       return true;
     }
     if (parsed.noPreview) {
-      _chunkQQ2FG5W3js.printCommandEnvelope.call(void 0, 
+      _chunkUROXKPNDjs.printCommandEnvelope.call(void 0, 
         {
           ...materializedEnvelope,
           local: {
@@ -3117,12 +3102,12 @@ async function executeTool(args) {
             output_path: csv.path
           }
         },
-        { json: _chunkQQ2FG5W3js.shouldEmitJson.call(void 0, ), text: `${csv.path}
+        { json: _chunkUROXKPNDjs.shouldEmitJson.call(void 0, ), text: `${csv.path}
 ` }
       );
       return true;
     }
-    _chunkQQ2FG5W3js.printCommandEnvelope.call(void 0, materializedEnvelope, { json: false });
+    _chunkUROXKPNDjs.printCommandEnvelope.call(void 0, materializedEnvelope, { json: false });
     return true;
   });
   if (delivered) {