deepline 0.3.328 → 0.3.330

package/dist/cli/{chunk-UDIPEHNJ.js → chunk-46IVSO6O.js}

@@ -1,20 +1,21 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
 
-var _chunkITFUZEHEjs = require('./chunk-ITFUZEHE.js');
+var _chunkYGFQ7YSMjs = require('./chunk-YGFQ7YSM.js');
 
 
-var _chunkDNMV2L7Qjs = require('./chunk-DNMV2L7Q.js');
 
+var _chunkWHKTRZ3Jjs = require('./chunk-WHKTRZ3J.js');
 
 
-var _chunkO5GPNPOCjs = require('./chunk-O5GPNPOC.js');
+
+var _chunkGHHLLEZKjs = require('./chunk-GHHLLEZK.js');
 
 // src/cli/search-ref.ts
 var _fs = require('fs');
 var _path = require('path');
 var SEARCH_REF_TTL_MS = 15 * 6e4;
 function lastSearchPath() {
-  return _path.join.call(void 0, _chunkO5GPNPOCjs.sdkCliStateDirPath.call(void 0, _chunkO5GPNPOCjs.resolveConfig.call(void 0, ).baseUrl), "last-search.json");
+  return _path.join.call(void 0, _chunkGHHLLEZKjs.sdkCliStateDirPath.call(void 0, _chunkGHHLLEZKjs.resolveConfig.call(void 0, ).baseUrl), "last-search.json");
 }
 function rememberSearchRef(searchRef) {
   try {
@@ -36,6 +37,132 @@ function recentSearchRef() {
   }
 }
 
+// src/cli/text-table.ts
+var _table = require('table');
+function formatTextTable(rows, columns) {
+  if (columns.length === 0) return "";
+  const data = [
+    columns.map((column) => column.header),
+    ...rows.map((row) => columns.map((column) => column.value(row)))
+  ];
+  return _table.table.call(void 0, data, {
+    border: _table.getBorderCharacters.call(void 0, "void"),
+    drawHorizontalLine: () => false,
+    columnDefault: { paddingLeft: 0, paddingRight: 2 },
+    columns: columns.map((column, index) => ({
+      alignment: _nullishCoalesce(column.alignment, () => ( "left")),
+      // table@6's word wrapper counts UTF-16 characters instead of display
+      // cells. Use its display-width-safe character wrapper for Unicode;
+      // unbounded identifiers never need wrapping in the first place.
+      wrapWord: column.width !== void 0 && data.every((row) => new RegExp("^\\p{ASCII}*$", "u").test(row[index])),
+      ...column.width === void 0 ? {} : { width: column.width }
+    }))
+  }).split("\n").map((line) => line.trimEnd()).join("\n").trimEnd();
+}
+
+// src/cli/search-output.ts
+function clipSummary(value) {
+  const characters = Array.from(value.replace(/\s+/gu, " ").trim());
+  return characters.length <= 78 ? characters.join("") : `${characters.slice(0, 77).join("")}\u2026`;
+}
+function pricingDisplay(item) {
+  const pricing = item.pricing;
+  if (!pricing)
+    return { cost: item.kind === "tool" ? "unknown" : "\u2014", notes: [] };
+  const range = pricing.estimatedRange;
+  if (range && item.billingSource !== "own_provider_credentials") {
+    return {
+      cost: `${range.minCreditsPerUnit}\u2013${range.maxCreditsPerUnit}/${pricing.unit} (estimate)`,
+      notes: [range.scope]
+    };
+  }
+  const observed = pricing.observedReference;
+  if (observed) {
+    return {
+      cost: `${observed.creditsPerCall}/call (observed)`,
+      notes: [
+        `Observed reference: ${observed.sampleSize} call(s), ${observed.observedAt}; ${observed.inputMode} Not a quote.`
+      ]
+    };
+  }
+  if (item.billingSource === "own_provider_credentials") {
+    return {
+      cost: "0 (own credentials)",
+      notes: ["Your provider quota still applies."]
+    };
+  }
+  const display = _nullishCoalesce(pricing.displayText, () => ( ""));
+  const rate = display.match(
+    /^([\d.,]+) Deepline credits(?: \/ \$[\d.,]+)? per (call|result|page)( \(estimate\))?$/
+  );
+  if (rate)
+    return {
+      cost: `${rate[1]}/${rate[2]}${_nullishCoalesce(rate[3], () => ( ""))}${pricing.summary || _optionalChain([pricing, 'access', _ => _.details, 'optionalAccess', _2 => _2.length]) ? "*" : ""}`,
+      notes: []
+    };
+  if (pricing.creditsPerUnit === 0 && /^Free\b/.test(display)) {
+    return { cost: "0 (free)", notes: [] };
+  }
+  if (!display || display === "Pricing unavailable.")
+    return { cost: "unknown", notes: [] };
+  return {
+    cost: pricing.unit === "usage" ? "usage-based" : "variable",
+    notes: display ? [clipSummary(display)] : []
+  };
+}
+function searchRow(item) {
+  const { cost, notes } = pricingDisplay(item);
+  if (item.credentialStatus === "requires_connection") {
+    notes.push("Requires your credentials \u2014 not connected (connect to use).");
+  } else if (item.connected === false && item.credentialStatus === "managed") {
+    notes.push("Temporarily unavailable.");
+  }
+  return {
+    id: item.id,
+    kind: item.kind,
+    cost,
+    summary: clipSummary(_nullishCoalesce(item.description, () => ( ""))),
+    notes
+  };
+}
+function renderSearchResults(result) {
+  if (result.results.length === 0)
+    return _chunkWHKTRZ3Jjs.renderCommandEnvelopeText.call(void 0, result);
+  const rows = result.results.map(searchRow);
+  const kinds = new Set(rows.map((row) => row.kind));
+  const onlyTools = kinds.size === 1 && kinds.has("tool");
+  const columns = [
+    { header: onlyTools ? "TOOL" : "ID", value: (row) => row.id },
+    ...!onlyTools ? [{ header: "KIND", value: (row) => row.kind }] : [],
+    { header: "CREDITS", value: (row) => row.cost, alignment: "right" },
+    { header: "SUMMARY", value: (row) => row.summary }
+  ];
+  const render = result.render;
+  const title = _nullishCoalesce(_optionalChain([render, 'optionalAccess', _3 => _3.sections, 'optionalAccess', _4 => _4[0], 'optionalAccess', _5 => _5.title]), () => ( `${_nullishCoalesce(result.total, () => ( rows.length))} matches \u2014 showing ${rows.length}`));
+  const remaining = {
+    sections: _optionalChain([render, 'optionalAccess', _6 => _6.sections, 'optionalAccess', _7 => _7.slice, 'call', _8 => _8(1)]),
+    actions: _optionalChain([render, 'optionalAccess', _9 => _9.actions])
+  };
+  const followUps = _optionalChain([remaining, 'access', _10 => _10.sections, 'optionalAccess', _11 => _11.length]) || _optionalChain([remaining, 'access', _12 => _12.actions, 'optionalAccess', _13 => _13.length]) ? `
+${_chunkWHKTRZ3Jjs.renderCommandEnvelopeText.call(void 0, { render: remaining })}` : "";
+  const notes = rows.flatMap(
+    (row) => row.notes.map((note) => `  ${row.id}: ${note}`)
+  );
+  const details = [
+    ...notes.length ? ["Notes", ...notes, ""] : [],
+    ...rows.some((row) => row.cost.endsWith("*")) ? [
+      "* Additional pricing conditions apply; see full pricing before execution."
+    ] : [],
+    "Full descriptions and pricing: deepline tools describe <toolId> or search --json."
+  ].join("\n");
+  return `${title}
+
+${formatTextTable(rows, columns)}
+
+${details}
+${followUps}`;
+}
+
 // src/cli/commands/search.ts
 var SEARCH_TYPES = [
   "tools",
@@ -78,8 +205,8 @@ function addSearchOptions(command) {
 function pointAtDescribe(result) {
   const old = /`deepline (tools|plays) describe [^`]*`/;
   const render = result.render;
-  for (const section of _nullishCoalesce(_optionalChain([render, 'optionalAccess', _ => _.sections]), () => ( []))) {
-    if (!_optionalChain([section, 'access', _2 => _2.lines, 'optionalAccess', _3 => _3.some, 'call', _4 => _4((line) => old.test(line))])) continue;
+  for (const section of _nullishCoalesce(_optionalChain([render, 'optionalAccess', _14 => _14.sections]), () => ( []))) {
+    if (!_optionalChain([section, 'access', _15 => _15.lines, 'optionalAccess', _16 => _16.some, 'call', _17 => _17((line) => old.test(line))])) continue;
     section.lines = [
       "Run `deepline describe <id>` before executing a tool or running a play.",
       ...section.lines.filter((line) => !old.test(line))
@@ -91,13 +218,13 @@ function pointAtDescribe(result) {
   }
 }
 async function runSearch(queryInput, options, types, exclude = []) {
-  const query = _nullishCoalesce(_optionalChain([queryInput, 'optionalAccess', _5 => _5.trim, 'call', _6 => _6()]), () => ( ""));
+  const query = _nullishCoalesce(_optionalChain([queryInput, 'optionalAccess', _18 => _18.trim, 'call', _19 => _19()]), () => ( ""));
   const searchTerms = _nullishCoalesce(options.searchTerms, () => ( options.search_terms));
-  if (!query && !_optionalChain([options, 'access', _7 => _7.categories, 'optionalAccess', _8 => _8.trim, 'call', _9 => _9()]) && !_optionalChain([searchTerms, 'optionalAccess', _10 => _10.trim, 'call', _11 => _11()])) {
+  if (!query && !_optionalChain([options, 'access', _20 => _20.categories, 'optionalAccess', _21 => _21.trim, 'call', _22 => _22()]) && !_optionalChain([searchTerms, 'optionalAccess', _23 => _23.trim, 'call', _24 => _24()])) {
     console.error(USAGE);
     return 1;
   }
-  const { search_ref: searchRef, ...result } = await new (0, _chunkITFUZEHEjs.DeeplineClient)().search({
+  const { search_ref: searchRef, ...result } = await new (0, _chunkYGFQ7YSMjs.DeeplineClient)().search({
     query,
     types,
     exclude,
@@ -111,8 +238,9 @@ async function runSearch(queryInput, options, types, exclude = []) {
   });
   if (searchRef) rememberSearchRef(searchRef);
   pointAtDescribe(result);
-  _chunkDNMV2L7Qjs.printCommandEnvelope.call(void 0, result, {
-    json: options.json === true
+  _chunkWHKTRZ3Jjs.printCommandEnvelope.call(void 0, result, {
+    json: options.json === true,
+    text: renderSearchResults(result)
   });
   return 0;
 }
@@ -166,6 +294,8 @@ Notes:
   materially improves ranking, especially for short queries.
   Search prints a readable result list by default, piped or not, and that is
   the recommended form. Pass --json only when a program parses the result.
+  Readable prices are Deepline credits with a per-row unit. Estimates and
+  observed historical charges are labelled; usage-based prices are not quotes.
 
 Examples:
   deepline search "find work email"

package/dist/cli/{chunk-GZV5F6CL.mjs → chunk-56RM5AQF.mjs}

@@ -10,7 +10,7 @@ import {
 import {
   recentSearchRef,
   registerDeprecatedSearchCommand
-} from "./chunk-7MABE3ZK.mjs";
+} from "./chunk-VFC6CZLF.mjs";
 import {
   extractSummaryFields,
   projectRowOutput,
@@ -22,7 +22,7 @@ import {
 import {
   DeeplineClient,
   validateExecutionIdempotencyKey
-} from "./chunk-7R6KQSFA.mjs";
+} from "./chunk-GTBS6LQH.mjs";
 import {
   beginToolExecuteCommand,
   getToolExecuteInvocationId,
@@ -36,11 +36,14 @@ import {
   printJsonError,
   renderCommandEnvelopeText,
   shouldEmitJson
-} from "./chunk-B2R66UTW.mjs";
+} from "./chunk-7DGZCMXQ.mjs";
 import {
   resolveConfig,
   sdkCliStateDirPath
-} from "./chunk-WWVE4HFN.mjs";
+} from "./chunk-MBI3BVSQ.mjs";
+import {
+  playToolListGetterMode
+} from "./chunk-NTVTZAVZ.mjs";
 import {
   DeeplineError
 } from "./chunk-NXGCO4JB.mjs";
@@ -302,7 +305,19 @@ var CapabilityDescription = class _CapabilityDescription {
       billingSource,
       billingSourceLabel,
       deeplineCreditsPerPricingUnit: isFree ? 0 : canonicalCredits,
-      deeplineUsdPerPricingUnit: isFree ? 0 : canonicalUsd
+      deeplineUsdPerPricingUnit: isFree ? 0 : canonicalUsd,
+      ...pricing.estimatedRange && !isFree && billingSource !== "own_provider_credentials" ? {
+        estimatedRange: pricing.estimatedRange,
+        details: Array.isArray(pricing.details) ? pricing.details.filter(
+          (value) => typeof value === "string"
+        ) : []
+      } : {},
+      ...pricing.observedReference && !isFree && billingSource !== "own_provider_credentials" ? {
+        observedReference: pricing.observedReference,
+        details: Array.isArray(pricing.details) ? pricing.details.filter(
+          (value) => typeof value === "string"
+        ) : []
+      } : {}
     };
   }
 };
@@ -959,6 +974,7 @@ Notes:
   preserve the nesting shown in the tool's example. Schemas and examples are
   separate describe fields.
   get is accepted as a compatibility alias for describe.
+  Text by default, including when piped; pass --json for structured output.
 
 Examples:
   deepline tools describe hunter_email_verifier
@@ -971,7 +987,7 @@ Examples:
   deepline tools describe ai_evaluate --estimate-payload @payload.json --json
   deepline tools execute hunter_email_verifier --input '{"email":"a@b.com"}'
 `
-    ).option("--json", "Emit JSON output. Also automatic when stdout is piped").option(
+    ).option("--json", "Emit JSON output").option(
       "--model <model>",
       "For language tools, include AI Gateway metadata; for ai_evaluate, set the quote payload model"
     ).option(
@@ -1013,7 +1029,7 @@ Examples:
         process.exitCode = await narrowView();
         return;
       }
-      const { describeAnything } = await import("./describe-W6X5G4JR.mjs");
+      const { describeAnything } = await import("./describe-WECII7FS.mjs");
       process.exitCode = await describeAnything(
         toolId,
         { ...options, kinds: ["tools", "monitors"], fetchedTool: metadata },
@@ -1230,14 +1246,6 @@ ${formatModelDescription(modelDescription)}`);
     if (inferenceQuote) printInferenceQuoteSummary(inferenceQuote);
     return 0;
   }
-  if (shouldEmitJson()) {
-    printCompactJson({
-      ...toolContractJsonForDescribe(tool, toolId),
-      ...modelDescription ? { modelOptions: modelDescription } : {},
-      ...inferenceQuote ? { inferenceQuote } : {}
-    });
-    return 0;
-  }
   printCompactToolContract(tool, toolId);
   if (modelDescription) {
     process.stdout.write(`
@@ -1257,7 +1265,7 @@ function inferenceQuoteSummaryLines(_quote) {
 function printInferenceQuoteSummary(quote) {
   for (const line of inferenceQuoteSummaryLines(quote)) console.log(line);
 }
-function toolContractJsonForDescribe(tool, requestedToolId) {
+function toolContractJsonForDescribe(tool, requestedToolId, authoringContractEdition) {
   const toolId = String(tool.toolId || requestedToolId);
   const inputFields = toolInputFieldsForDisplay(
     recordField(tool, "inputSchema", "input_schema")
@@ -1276,7 +1284,11 @@ function toolContractJsonForDescribe(tool, requestedToolId) {
   );
   const extractedLists = extractionContractEntries(
     arrayField2(toolExecutionResult, "extractedLists", "extracted_lists")
-  );
+  ).map((entry) => ({
+    ...entry,
+    returnType: playToolListGetterMode(authoringContractEdition) === "array" ? "Array" : "PlayDataset",
+    rowsExpression: playToolListGetterMode(authoringContractEdition) === "array" ? entry.expression : `await ${entry.expression}.materialize()`
+  }));
   const extractedValues = extractionContractEntries(
     arrayField2(toolExecutionResult, "extractedValues", "extracted_values")
   );
@@ -1685,7 +1697,7 @@ function printCompactToolContract(tool, requestedToolId) {
   if (listGetters.length || valueGetters.length) {
     console.log("");
     console.log("Getters:");
-    if (listGetters.length) console.log("Lists:");
+    if (listGetters.length) console.log(listGetterHeading());
     for (const entry of listGetters) {
       if (isRecord(entry))
         console.log(
@@ -1723,6 +1735,10 @@ function toolPricingOnlyLines(tool, requestedToolId, options = {}) {
   const price = displayText || summary || (credits !== null ? `${formatDecimal(credits)} Deepline credits${usd !== null ? ` / ${formatUsd(usd)}` : ""} per ${unit}` : "pricing unavailable");
   return [
     `${options.heading ?? `Pricing: ${toolId}`}: ${price}`,
+    ...cost.observedReference || cost.estimatedRange ? [
+      ...summary ? [`  ${summary}`] : [],
+      ...(cost.details ?? []).map((detail) => `  ${detail}`)
+    ] : [],
     `Billing: ${billing}`
   ];
 }
@@ -1807,7 +1823,7 @@ function printToolExamplesOnly(tool, requestedToolId) {
   const getters = isRecord(contract.getters) ? contract.getters : {};
   const valueGetters = Array.isArray(getters.extractedValues) ? getters.extractedValues : [];
   const listGetters = Array.isArray(getters.extractedLists) ? getters.extractedLists : [];
-  const firstGetter = [...valueGetters, ...listGetters].find(isRecord);
+  const firstGetter = valueGetters.find(isRecord);
   if (firstGetter) {
     const name = stringField2(firstGetter, "name") || "value";
     const expression = stringField2(firstGetter, "expression");
@@ -1816,7 +1832,28 @@ function printToolExamplesOnly(tool, requestedToolId) {
         `const ${safeIdentifier(name)} = ${expression.replace(/^toolExecutionResult\./, "result.")};`
       );
   }
+  const arrayNames = new Set(
+    recursiveToolInputFieldsForDisplay(
+      recordField(tool, "outputSchema", "output_schema")
+    ).filter((field) => String(field.type).split("|").includes("array")).map((field) => String(field.name).split(".").at(-1))
+  );
+  const firstList = listGetters.find(
+    (entry) => isRecord(entry) && arrayNames.has(stringField2(entry, "name"))
+  ) ?? listGetters.find(isRecord);
+  if (isRecord(firstList)) {
+    const name = safeIdentifier(stringField2(firstList, "name") || "list");
+    if (playToolListGetterMode() === "array") {
+      console.log(`const ${name}_rows = ${playResultExpression(firstList)};`);
+    } else {
+      console.log(`const ${name}_ds = ${playResultExpression(firstList)};`);
+      console.log(
+        "// Complete small list from this response; throws above the memory cap."
+      );
+      console.log(`const ${name}_rows = await ${name}_ds.materialize();`);
+    }
+  }
   console.log("```");
+  if (firstList) printListGetterConsumption();
   for (const example of examples) {
     const description = stringField2(example, "description");
     if (description) console.log(description);
@@ -1863,13 +1900,14 @@ function printToolGettersOnly(tool, requestedToolId) {
     return;
   }
   if (listGetters.length) {
-    console.log("Lists:");
+    console.log(listGetterHeading());
     for (const entry of listGetters) {
       if (isRecord(entry))
         console.log(
           `- ${stringField2(entry, "name")}: ${playResultExpression(entry)}`
         );
     }
+    printListGetterConsumption();
   }
   if (valueGetters.length) {
     console.log("Values:");
@@ -1881,6 +1919,20 @@ function printToolGettersOnly(tool, requestedToolId) {
     }
   }
 }
+function printListGetterConsumption() {
+  if (playToolListGetterMode() === "array") {
+    console.log(
+      "Use the ordinary array directly, or pass it to ctx.dataset to persist row work. No provider pagination is fetched. Lazy or incomplete lists throw; use readList for an explicit dataset read. A missing getter is not an empty list."
+    );
+    return;
+  }
+  console.log(
+    "Pass the handle to ctx.dataset, use first() for one row, or for await...of to stream rows. materialize() loads the complete current list within the memory cap; materialize(n) and peek(n) return only a prefix. None fetch additional provider pagination. A missing getter is not an empty list."
+  );
+}
+function listGetterHeading() {
+  return playToolListGetterMode() === "array" ? "Lists (ordinary JavaScript arrays):" : "Lists (PlayDataset, not a JavaScript array):";
+}
 function sampleValueForField(field) {
   const name = stringField2(field, "name").toLowerCase();
   const type = stringField2(field, "type").toLowerCase();
@@ -2010,15 +2062,16 @@ function usageGuidanceWithAccessDefaults(usageGuidance) {
     },
     access: {
       ...existingAccess,
-      extractedLists: {
-        expression: "toolExecutionResult.extractedLists.<name>.get()",
-        meaning: "Declared Deepline list extractors only."
-      },
       extractedValues: {
         expression: "toolExecutionResult.extractedValues.<name>.get()",
         meaning: "Declared Deepline scalar or normalized object extractors only."
       },
       ...existingAccess,
+      extractedLists: {
+        ...recordField(existingAccess, "extractedLists"),
+        expression: "toolExecutionResult.extractedLists.<name>.get()",
+        meaning: playToolListGetterMode() === "array" ? "Returns an ordinary array from this response. Use array methods directly or pass it to ctx.dataset to persist row work. Lazy or incomplete lists throw; use readList for an explicit dataset read. It does not fetch provider pages." : "Returns a PlayDataset, not a JavaScript array. Pass the handle to ctx.dataset, use first(), async iteration, or await handle.materialize() for the complete current list within the memory cap. materialize(n) and peek(n) return a prefix; none fetch additional provider pages. A missing getter is not an empty list."
+      },
       rawToolResponse: {
         expression: "toolExecutionResult.toolResponse.rawV2",
         meaning: "Complete tool response with its original nesting. Read tool-specific fields here; use declared getters for extracted values and lists."
@@ -2658,8 +2711,8 @@ export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
   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.
+  // ${playToolListGetterMode() === "array" ? "extractedLists.<name>.get() returns an ordinary array from this response." : "extractedLists.<name>.get() returns a dataset handle for row-shaped list outputs."}
+  // ${playToolListGetterMode() === "array" ? "Use array methods directly; pass rows to ctx.dataset to persist row work." : "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 for completed rows during same-run recovery. New runs follow each call's freshness.

package/dist/cli/{chunk-UM4ZE3P7.mjs → chunk-5W636CDP.mjs}

@@ -2,10 +2,10 @@ import {
   getAuthedHttpClient,
   openInBrowser,
   printCommandEnvelope
-} from "./chunk-B2R66UTW.mjs";
+} from "./chunk-7DGZCMXQ.mjs";
 import {
   resolveBaseUrlOnly
-} from "./chunk-WWVE4HFN.mjs";
+} from "./chunk-MBI3BVSQ.mjs";
 
 // src/cli/commands/git.ts
 function shellQuote(value) {