deepline 0.1.36 → 0.1.38

package/dist/cli/index.js

@@ -216,8 +216,8 @@ function resolveConfig(options) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.1.36";
-var SDK_API_CONTRACT = "2026-05-v2-tool-response";
+var SDK_VERSION = "0.1.38";
+var SDK_API_CONTRACT = "2026-05-v2-tool-response-play-guardrails";
 
 // ../shared_libs/play-runtime/coordinator-headers.ts
 var COORDINATOR_INTERNAL_TOKEN_HEADER = "x-deepline-internal-token";
@@ -7491,6 +7491,126 @@ function shouldUseLocalOnlyPlayCheck() {
   const value = process.env.DEEPLINE_PLAY_CHECK_LOCAL_ONLY?.trim().toLowerCase();
   return value === "1" || value === "true" || value === "yes" || value === "on";
 }
+function isRecord3(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function stringValue(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+function extractionEntries(value) {
+  if (Array.isArray(value)) return value.filter(isRecord3);
+  if (!isRecord3(value)) return [];
+  return Object.entries(value).map(
+    ([name, entry]) => isRecord3(entry) ? { name, ...entry } : { name }
+  );
+}
+function firstRawPath(entry) {
+  const details = isRecord3(entry.details) ? entry.details : {};
+  const paths = [
+    ...asArray(details.rawToolOutputPaths),
+    ...asArray(details.raw_tool_output_paths),
+    ...asArray(details.candidatePaths),
+    ...asArray(details.candidate_paths)
+  ].map(stringValue).filter(Boolean);
+  return paths[0];
+}
+function checkHintExpression(value) {
+  return stringValue(value).replace(/^toolExecutionResult\./, "result.");
+}
+function checkHintRawPath(value) {
+  return value?.replace(/^toolResponse\./, "result.toolResponse.");
+}
+function collectStaticPipelineToolIds(staticPipeline) {
+  const seen = /* @__PURE__ */ new Set();
+  const visitPipeline = (pipeline) => {
+    if (!isRecord3(pipeline)) return;
+    for (const step of [
+      ...asArray(pipeline.stages),
+      ...asArray(pipeline.substeps)
+    ]) {
+      if (!isRecord3(step)) continue;
+      if (step.type === "tool") {
+        const toolId = stringValue(step.toolId) || stringValue(step.tool);
+        if (toolId) seen.add(toolId);
+      }
+      if (step.type === "play_call") {
+        visitPipeline(step.pipeline);
+      }
+    }
+  };
+  visitPipeline(staticPipeline);
+  return [...seen].sort();
+}
+function toolGetterHintFromMetadata(toolId, tool) {
+  const usageGuidance = isRecord3(tool.usageGuidance) ? tool.usageGuidance : {};
+  const resultGuidance = isRecord3(usageGuidance.toolExecutionResult) ? usageGuidance.toolExecutionResult : isRecord3(usageGuidance.tool_execution_result) ? usageGuidance.tool_execution_result : {};
+  const toolResponse = isRecord3(resultGuidance.toolResponse) ? resultGuidance.toolResponse : isRecord3(resultGuidance.tool_response) ? resultGuidance.tool_response : {};
+  const lists = extractionEntries(
+    resultGuidance.extractedLists ?? resultGuidance.extracted_lists
+  ).map((entry) => ({
+    name: stringValue(entry.name),
+    expression: checkHintExpression(entry.expression),
+    raw: checkHintRawPath(firstRawPath(entry))
+  })).filter((entry) => entry.name && entry.expression);
+  const values = extractionEntries(
+    resultGuidance.extractedValues ?? resultGuidance.extracted_values
+  ).map((entry) => ({
+    name: stringValue(entry.name),
+    expression: checkHintExpression(entry.expression),
+    raw: checkHintRawPath(firstRawPath(entry))
+  })).filter((entry) => entry.name && entry.expression);
+  return {
+    toolId,
+    lists,
+    values,
+    raw: checkHintExpression(toolResponse.raw) || "result.toolResponse.raw"
+  };
+}
+async function buildToolGetterHints(client, staticPipeline) {
+  const toolIds = collectStaticPipelineToolIds(staticPipeline);
+  return Promise.all(
+    toolIds.map(async (toolId) => {
+      try {
+        const tool = await client.getTool(toolId);
+        return toolGetterHintFromMetadata(toolId, tool);
+      } catch (error) {
+        return {
+          toolId,
+          lists: [],
+          values: [],
+          raw: "result.toolResponse.raw",
+          unavailable: error instanceof Error ? error.message : String(error)
+        };
+      }
+    })
+  );
+}
+function printToolGetterHints(hints) {
+  if (!hints?.length) return;
+  console.log("  Tool result getter hints:");
+  for (const hint of hints) {
+    console.log(`    ${hint.toolId} output:`);
+    if (hint.lists.length) {
+      for (const entry of hint.lists) {
+        const raw = entry.raw ? ` (raw: ${entry.raw})` : "";
+        console.log(`      - list ${entry.name}: ${entry.expression}${raw}`);
+      }
+    }
+    if (hint.values.length) {
+      const valueNames = hint.values.map((entry) => entry.name).join(", ");
+      console.log(`      - values: ${valueNames}`);
+      for (const entry of hint.values) {
+        const raw = entry.raw ? ` (raw: ${entry.raw})` : "";
+        console.log(`        ${entry.name}: ${entry.expression}${raw}`);
+      }
+    }
+    if (hint.raw) console.log(`      - raw: ${hint.raw}`);
+    if (hint.unavailable) console.log(`      - warning: ${hint.unavailable}`);
+  }
+}
 async function handlePlayCheck(args) {
   const options = parsePlayCheckOptions(args);
   if (!isFileTarget(options.target)) {
@@ -7521,6 +7641,7 @@ async function handlePlayCheck(args) {
       valid: true,
       errors: [],
       staticPipeline: graph.root.compilerManifest?.staticPipeline ?? null,
+      toolGetterHints: [],
       artifactHash: graph.root.artifact.artifactHash,
       graphHash: graph.root.artifact.graphHash
     };
@@ -7530,6 +7651,7 @@ async function handlePlayCheck(args) {
     } else {
       console.log(`\u2713 ${playName} passed local play check`);
       console.log(`  artifact: ${result2.artifactHash.slice(0, 12)}`);
+      printToolGetterHints(result2.toolGetterHints);
     }
     return 0;
   }
@@ -7540,21 +7662,27 @@ async function handlePlayCheck(args) {
     sourceFiles: graph.root.sourceFiles,
     artifact: graph.root.artifact
   });
+  const enrichedResult = {
+    ...result,
+    toolGetterHints: result.toolGetterHints ?? await buildToolGetterHints(client, result.staticPipeline)
+  };
   if (options.jsonOutput) {
-    process.stdout.write(`${JSON.stringify({ name: playName, ...result })}
+    process.stdout.write(`${JSON.stringify({ name: playName, ...enrichedResult })}
 `);
-  } else if (result.valid) {
+  } else if (enrichedResult.valid) {
     console.log(`\u2713 ${playName} passed cloud play check`);
-    if (result.artifactHash) {
-      console.log(`  artifact: ${result.artifactHash.slice(0, 12)}`);
+    if (enrichedResult.artifactHash) {
+      console.log(`  artifact: ${enrichedResult.artifactHash.slice(0, 12)}`);
     }
+    printToolGetterHints(enrichedResult.toolGetterHints);
   } else {
     console.error(`\u2717 ${playName} failed cloud play check`);
-    for (const error of result.errors) {
+    for (const error of enrichedResult.errors) {
       console.error(`  ${error}`);
     }
+    printToolGetterHints(enrichedResult.toolGetterHints);
   }
-  return result.valid ? 0 : 1;
+  return enrichedResult.valid ? 0 : 1;
 }
 async function handleFileBackedRun(options) {
   if (options.target.kind !== "file") {
@@ -8657,7 +8785,7 @@ Pass-through input flags:
       ...options.logs ? ["--logs"] : [],
       ...options.tailTimeoutMs ? ["--tail-timeout-ms", options.tailTimeoutMs] : [],
       ...options.force ? ["--force"] : [],
-      ...options.open === false ? ["--no-open"] : [],
+      ...options.noOpen || options.open === false ? ["--no-open"] : [],
       ...options.json ? ["--json"] : [],
       ...passthroughArgs
     ]);
@@ -9113,6 +9241,15 @@ function extractSummaryFields(payload) {
 
 // src/cli/commands/tools.ts
 function toListedTool(tool) {
+  if (isPlayLikeTool(tool)) {
+    const playReference = playReferenceForTool(tool);
+    return {
+      ...tool,
+      id: tool.toolId,
+      type: "play",
+      executeCommand: `deepline plays run ${playReference} --input '{...}' --watch`
+    };
+  }
   return {
     ...tool,
     id: tool.toolId,
@@ -9151,11 +9288,12 @@ async function searchTools(queryInput, options = {}) {
     searchMode: options.searchMode,
     includeSearchDebug: options.includeSearchDebug
   });
-  const items = result.tools.map(toListedTool);
+  const items = result.tools.filter((tool) => !isPlayLikeTool(tool)).map(toListedTool);
   const envelope = {
     ...result,
     tools: items,
     count: items.length,
+    omitted_plays_hint: "Use `deepline plays search <query> --json` for prebuilt and org-owned plays.",
     render: {
       sections: [
         {
@@ -9168,6 +9306,10 @@ async function searchTools(queryInput, options = {}) {
               ...item.inputSchema ? ["  inputSchema: yes"] : []
             ];
           })
+        },
+        {
+          title: "plays",
+          lines: ["For prebuilt or org-owned workflows, run: deepline plays search <query>"]
         }
       ]
     }
@@ -9186,13 +9328,36 @@ async function findPlayForToolId(client, toolId) {
   const plays = await client.searchPlays({ query: requested, compact: true });
   return plays.find((play) => playIdentifiers(play).includes(requested)) ?? null;
 }
-function printPlayAliasToolError(toolId, play) {
+function playAliasToolErrorMessage(toolId, play) {
   const playName = play.reference ?? play.name;
-  console.error(
-    `${toolId} is a play, not a tool.
+  return `${toolId} is a play, not a tool.
 Use: deepline plays run ${playName} --input '{...}' --watch
-Inspect its schema with: deepline plays describe ${playName} --json`
-  );
+Inspect its schema with: deepline plays describe ${playName} --json`;
+}
+function printPlayAliasToolError(toolId, play) {
+  console.error(playAliasToolErrorMessage(toolId, play));
+}
+function isPlayLikeTool(tool) {
+  const record = tool;
+  if (record.isPlay === true || record.is_play === true) return true;
+  const playExpansion = recordField(record, "playExpansion", "play_expansion");
+  if (Object.keys(playExpansion).length > 0) return true;
+  const toolId = typeof record.toolId === "string" ? record.toolId : "";
+  return toolId.endsWith("_waterfall");
+}
+function playReferenceForTool(tool) {
+  const record = tool;
+  const toolId = typeof record.toolId === "string" ? record.toolId : "play";
+  return `prebuilt/${toolId.replace(/_/g, "-")}`;
+}
+function playLikeToolExecuteErrorMessage(toolId) {
+  const playReference = `prebuilt/${toolId.replace(/_/g, "-")}`;
+  return `${toolId} is a workflow/play entry, not an atomic provider tool.
+Use: deepline plays run ${playReference} --input '{...}' --watch
+Or search provider tools only with: deepline tools search "<query>" --json`;
+}
+function printPlayLikeToolExecuteError(toolId) {
+  console.error(playLikeToolExecuteErrorMessage(toolId));
 }
 function registerToolsCommands(program) {
   const tools = program.command("tools").description("Search, describe, and execute atomic provider tools.").addHelpText(
@@ -9367,7 +9532,7 @@ function printToolDetails(tool, requestedToolId) {
   const operation = typeof tool.operation === "string" ? tool.operation : "";
   const displayBase = operation && operation.startsWith(`${tool.provider}_`) ? operation.slice(String(tool.provider).length + 1) : operation ? `${tool.provider} ${operation}`.trim() : toolId;
   const displayName = titleCase(displayBase || String(tool.displayName || toolId));
-  const cost = isRecord3(tool.cost) ? tool.cost : null;
+  const cost = isRecord4(tool.cost) ? tool.cost : null;
   const deeplineCredits = numberField(tool, "deeplineCreditsPerPricingUnit", "deepline_credits_per_pricing_unit");
   const deeplineUsdPerPricingUnit = numberField(tool, "deeplineUsdPerPricingUnit", "deepline_usd_per_pricing_unit");
   const deeplineUsdPerCredit = numberField(tool, "deeplineUsdPerCredit", "deepline_usd_per_credit");
@@ -9417,7 +9582,7 @@ function printToolDetails(tool, requestedToolId) {
     if (stepContributions.length) {
       console.log("    step contributions:");
       for (const item of stepContributions) {
-        if (!isRecord3(item)) continue;
+        if (!isRecord4(item)) continue;
         const stepTool = typeof item.tool === "string" ? item.tool.trim() : "";
         const low = typeof item.lowCredits === "number" ? item.lowCredits : null;
         const high = typeof item.highCredits === "number" ? item.highCredits : null;
@@ -9457,7 +9622,7 @@ function printToolDetails(tool, requestedToolId) {
     }
     const toolExecutionResult = recordField(usageGuidance, "toolExecutionResult");
     const extractedValues = arrayField(toolExecutionResult, "extractedValues", "extracted_values");
-    const targets = extractedValues.map((entry) => isRecord3(entry) && typeof entry.name === "string" ? entry.name : "").filter(Boolean).sort();
+    const targets = extractedValues.map((entry) => isRecord4(entry) && typeof entry.name === "string" ? entry.name : "").filter(Boolean).sort();
     if (targets.length) {
       console.log(`    - Built-in extract targets: ${targets.join(", ")}`);
     }
@@ -9498,7 +9663,7 @@ function printExtractions(label, entries) {
   if (!entries.length) return;
   console.log(`    ${label}:`);
   for (const entry of entries) {
-    if (!isRecord3(entry)) continue;
+    if (!isRecord4(entry)) continue;
     const name = stringField(entry, "name");
     const expression = stringField(entry, "expression");
     const details = recordField(entry, "details");
@@ -9538,12 +9703,12 @@ function printToolCost(input) {
   return false;
 }
 function toolInputFieldsForDisplay(inputSchema) {
-  if (Array.isArray(inputSchema.fields)) return inputSchema.fields.filter(isRecord3);
-  const jsonSchema = isRecord3(inputSchema.jsonSchema) ? inputSchema.jsonSchema : inputSchema;
-  const properties = isRecord3(jsonSchema.properties) ? jsonSchema.properties : {};
+  if (Array.isArray(inputSchema.fields)) return inputSchema.fields.filter(isRecord4);
+  const jsonSchema = isRecord4(inputSchema.jsonSchema) ? inputSchema.jsonSchema : inputSchema;
+  const properties = isRecord4(jsonSchema.properties) ? jsonSchema.properties : {};
   const required = Array.isArray(jsonSchema.required) ? new Set(jsonSchema.required.map(String)) : /* @__PURE__ */ new Set();
   return Object.entries(properties).map(([name, value]) => {
-    const property = isRecord3(value) ? value : {};
+    const property = isRecord4(value) ? value : {};
     return {
       name,
       type: typeof property.type === "string" ? property.type : "unknown",
@@ -9570,15 +9735,15 @@ function printJsonPreview(label, payload) {
 }
 function samplePayload(samples, key) {
   const entry = samples[key];
-  if (!isRecord3(entry)) return void 0;
+  if (!isRecord4(entry)) return void 0;
   return Object.prototype.hasOwnProperty.call(entry, "payload") ? entry.payload : entry;
 }
 function commandEnvelopeFromRawResponse(rawResponse) {
-  return isRecord3(rawResponse) ? { ...rawResponse } : { status: "completed", result: rawResponse };
+  return isRecord4(rawResponse) ? { ...rawResponse } : { status: "completed", result: rawResponse };
 }
 function listExtractorPathsFromUsageGuidance(tool) {
   const toolExecutionResult = tool.usageGuidance?.toolExecutionResult;
-  const extractedLists = Array.isArray(toolExecutionResult?.extractedLists) ? toolExecutionResult.extractedLists : isRecord3(toolExecutionResult?.extractedLists) ? Object.values(toolExecutionResult.extractedLists) : [];
+  const extractedLists = Array.isArray(toolExecutionResult?.extractedLists) ? toolExecutionResult.extractedLists : isRecord4(toolExecutionResult?.extractedLists) ? Object.values(toolExecutionResult.extractedLists) : [];
   return extractedLists.flatMap((entry) => {
     const paths = entry.details?.candidatePaths ?? entry.details?.rawToolOutputPaths;
     if (!Array.isArray(paths)) return [];
@@ -9605,7 +9770,7 @@ function formatDecimal(value) {
 function formatUsd(value) {
   return `$${formatDecimal(value)}`;
 }
-function isRecord3(value) {
+function isRecord4(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 function stringField(source, ...keys) {
@@ -9632,7 +9797,7 @@ function arrayField(source, ...keys) {
 function recordField(source, ...keys) {
   for (const key of keys) {
     const value = source[key];
-    if (isRecord3(value)) return value;
+    if (isRecord4(value)) return value;
   }
   return {};
 }
@@ -9730,8 +9895,11 @@ export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
   // .step('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.map is idempotent by map key + row key; reruns reuse completed rows.
   const enrichedData = await ctx
-    .map('enriched_data', rows, { key: ${rowKey} })
-    .run({ description: 'Enrich seeded rows.' });
+    .map('enriched_data', rows)
+    .run({
+      key: ${rowKey},
+      description: 'Enrich seeded rows.',
+    });
 
   return {
     rows: enrichedData,
@@ -9761,7 +9929,7 @@ function buildToolExecuteBaseEnvelope(input) {
     kind: summaryEntries.length > 0 ? "object" : "raw",
     summary: input.summary
   };
-  const envelopeHasCanonicalOutput = isRecord3(envelope.toolResponse) && Object.prototype.hasOwnProperty.call(envelope.toolResponse, "raw");
+  const envelopeHasCanonicalOutput = isRecord4(envelope.toolResponse) && Object.prototype.hasOwnProperty.call(envelope.toolResponse, "raw");
   const inspectCommand = `deepline tools execute ${input.toolId} --input ${shellQuote(JSON.stringify(input.params))} --json`;
   const actions = input.listConversion ? [
     {
@@ -9821,7 +9989,11 @@ async function executeTool(args) {
   } catch (error) {
     const play = await findPlayForToolId(client, parsed.toolId);
     if (play) {
-      printPlayAliasToolError(parsed.toolId, play);
+      if (argsWantJson(args)) {
+        printJsonError(new Error(playAliasToolErrorMessage(parsed.toolId, play)));
+      } else {
+        printPlayAliasToolError(parsed.toolId, play);
+      }
       return 2;
     }
     if (error instanceof DeeplineError) {
@@ -9829,6 +10001,14 @@ async function executeTool(args) {
     }
     throw error;
   }
+  if (isPlayLikeTool(metadata)) {
+    if (argsWantJson(args)) {
+      printJsonError(new Error(playLikeToolExecuteErrorMessage(parsed.toolId)));
+    } else {
+      printPlayLikeToolExecuteError(parsed.toolId);
+    }
+    return 2;
+  }
   const rawResponse = await client.executeTool(parsed.toolId, parsed.params);
   const listConversion = tryConvertToList(rawResponse, {
     listExtractorPaths: listExtractorPathsFromUsageGuidance(metadata)
@@ -9851,7 +10031,7 @@ async function executeTool(args) {
       {
         ...baseEnvelope,
         local: {
-          ...isRecord3(baseEnvelope.local) ? baseEnvelope.local : {},
+          ...isRecord4(baseEnvelope.local) ? baseEnvelope.local : {},
           payload_file: jsonPath
         }
       },
@@ -10449,9 +10629,15 @@ Notes:
 
 Examples:
   deepline version
+  deepline version --json
   deepline --version
 `
-  ).action(() => {
+  ).option("--json", "Emit JSON output").action((options) => {
+    if (options.json) {
+      process.stdout.write(`${JSON.stringify({ version: SDK_VERSION })}
+`);
+      return;
+    }
     process.stdout.write(`deepline ${SDK_VERSION}
 `);
   });