deepline 0.3.327 → 0.3.329

package/dist/cli/{chunk-2HKPAZVJ.js → chunk-FKKNYKDY.js}

@@ -1,7 +1,7 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); var _class;// ../plays/authoring-contract.ts
 var _typebox = require('@sinclair/typebox');
 var _value = require('@sinclair/typebox/value');
-var PLAY_AUTHORING_CONTRACT_EDITION = 8;
+var PLAY_AUTHORING_CONTRACT_EDITION = 10;
 var SUPPORTED_PLAY_AUTHORING_CONTRACT_EDITIONS = [
   1,
   2,
@@ -11,7 +11,8 @@ var SUPPORTED_PLAY_AUTHORING_CONTRACT_EDITIONS = [
   6,
   7,
   8,
-  9
+  9,
+  10
 ];
 var PLAY_AUTHORING_CONTRACT_CHANGELOG_DETAILS = [
   {
@@ -67,8 +68,17 @@ var PLAY_AUTHORING_CONTRACT_CHANGELOG_DETAILS = [
     compatibilityOwner: "Plays Runtime",
     newWritesEnd: null,
     readerRemoval: null
+  },
+  {
+    changed: "List getters return ordinary arrays from the complete resident tool response. Lazy database datasets require an explicit dataset read; incomplete historical previews fail rather than masquerade as complete arrays. Editions 1\u20139 retain dataset-valued getters; stored tool receipts are unchanged.",
+    compatibilityOwner: "Plays Runtime",
+    newWritesEnd: null,
+    readerRemoval: null
   }
 ];
+function playToolListGetterMode(edition = PLAY_AUTHORING_CONTRACT_EDITION) {
+  return edition >= 10 ? "array" : "dataset";
+}
 var PLAY_AUTHORING_CONTRACT_CHANGELOG = SUPPORTED_PLAY_AUTHORING_CONTRACT_EDITIONS.map((edition, index) => ({
   edition,
   ...PLAY_AUTHORING_CONTRACT_CHANGELOG_DETAILS[index]
@@ -1637,4 +1647,5 @@ var PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
 
 
 
-exports.PLAY_AUTHORING_CONTRACT_EDITION = PLAY_AUTHORING_CONTRACT_EDITION; exports.CtxFetchHttpError = CtxFetchHttpError;
+
+exports.PLAY_AUTHORING_CONTRACT_EDITION = PLAY_AUTHORING_CONTRACT_EDITION; exports.playToolListGetterMode = playToolListGetterMode; exports.CtxFetchHttpError = CtxFetchHttpError;

package/dist/cli/{chunk-G5774EFF.mjs → chunk-GCNER3HV.mjs}

@@ -49,7 +49,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.327",
+  version: "0.3.329",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1

package/dist/cli/{chunk-4ZARCCPT.js → chunk-GY2EEO2Y.js}

@@ -15,7 +15,7 @@ var _chunkLA46MMTLjs = require('./chunk-LA46MMTL.js');
 
 
 
-var _chunkDM3SHV6Ujs = require('./chunk-DM3SHV6U.js');
+var _chunkVDIHLKGGjs = require('./chunk-VDIHLKGG.js');
 
 
 
@@ -146,7 +146,7 @@ async function queryCustomerDatabase(http, input) {
     if (error instanceof _chunk7P5AA3SNjs.DeeplineError && (_optionalChain([error, 'access', _2 => _2.code, 'optionalAccess', _3 => _3.startsWith, 'call', _4 => _4("NETWORK_")]) || // Older API readers return PostgreSQL errors as HTTP 400, including
     // lost connections and explicitly unknown transaction resolution.
     /^08[A-Z0-9]{3}$/.test(_nullishCoalesce(error.code, () => ( ""))) || ["57P01", "57P02", "57P03"].includes(_nullishCoalesce(error.code, () => ( ""))) || error.statusCode === 408 || (_nullishCoalesce(error.statusCode, () => ( 0))) >= 500)) {
-      throw new (0, _chunkDM3SHV6Ujs.CustomerDbQueryOutcomeUnknownError)(
+      throw new (0, _chunkVDIHLKGGjs.CustomerDbQueryOutcomeUnknownError)(
         error,
         plan.request.body.operation_key
       );
@@ -154,7 +154,7 @@ async function queryCustomerDatabase(http, input) {
     throw error;
   }
   if (!result || typeof result !== "object" || Array.isArray(result) || typeof result.command !== "string" || !Array.isArray(result.columns) || !Array.isArray(result.rows) || typeof result.truncated !== "boolean" || result.row_count !== null && (!Number.isSafeInteger(result.row_count) || result.row_count < 0) || !Number.isSafeInteger(result.row_count_returned) || result.row_count_returned < 0) {
-    throw new (0, _chunkDM3SHV6Ujs.CustomerDbQueryOutcomeUnknownError)(
+    throw new (0, _chunkVDIHLKGGjs.CustomerDbQueryOutcomeUnknownError)(
       new (0, _chunk7P5AA3SNjs.DeeplineError)(
         "The SQL response did not contain a valid result.",
         200,
@@ -165,7 +165,7 @@ async function queryCustomerDatabase(http, input) {
   }
   const operation = result.operation;
   if (input.operationKey !== void 0 && (!operation || operation.operation_key !== input.operationKey || !Number.isSafeInteger(operation.completed_at_ms) || operation.completed_at_ms < 0 || !["executed", "operation_recovery"].includes(operation.source))) {
-    throw new (0, _chunkDM3SHV6Ujs.CustomerDbQueryOutcomeUnknownError)(
+    throw new (0, _chunkVDIHLKGGjs.CustomerDbQueryOutcomeUnknownError)(
       new (0, _chunk7P5AA3SNjs.DeeplineError)(
         "The server did not confirm the original atomic SQL operation.",
         200,
@@ -2854,8 +2854,8 @@ function runtimeSelectionHeaders(runtime) {
   }
   const receivers = _optionalChain([process, 'access', _102 => _102.env, 'access', _103 => _103.DEEPLINE_RUNTIME_RETAINED_PIPELINE_RECEIVERS, 'optionalAccess', _104 => _104.trim, 'call', _105 => _105()]);
   return {
-    [_chunkDM3SHV6Ujs.RUNTIME_ENVIRONMENT_TOKEN_HEADER]: token,
-    ...receivers ? { [_chunkDM3SHV6Ujs.RETAINED_PIPELINE_RECEIVERS_HEADER]: receivers } : {}
+    [_chunkVDIHLKGGjs.RUNTIME_ENVIRONMENT_TOKEN_HEADER]: token,
+    ...receivers ? { [_chunkVDIHLKGGjs.RETAINED_PIPELINE_RECEIVERS_HEADER]: receivers } : {}
   };
 }
 function isolatedCiRuntimeEventReadHeaders() {
@@ -2871,7 +2871,7 @@ function isolatedCiRuntimeEventReadHeaders() {
       "RUNTIME_EVENT_INTERNAL_TOKEN_REQUIRED"
     );
   }
-  return { [_chunkDM3SHV6Ujs.COORDINATOR_INTERNAL_TOKEN_HEADER]: token };
+  return { [_chunkVDIHLKGGjs.COORDINATOR_INTERNAL_TOKEN_HEADER]: token };
 }
 function normalizeTestPolicyOverrides(value, source) {
   if (value && typeof value === "object" && !Array.isArray(value)) {
@@ -3172,8 +3172,8 @@ var DeeplineClient = (_class = class _DeeplineClient {
    * @throws {@link ConfigError} if no API key can be resolved from any source.
    */
   constructor(options) {
-    this.config = _chunkDM3SHV6Ujs.resolveConfig.call(void 0, options);
-    this.http = new (0, _chunkDM3SHV6Ujs.HttpClient)(this.config);
+    this.config = _chunkVDIHLKGGjs.resolveConfig.call(void 0, options);
+    this.http = new (0, _chunkVDIHLKGGjs.HttpClient)(this.config);
     this.toolCalls = new ToolCalls(
       this.http,
       this.config.timeout,

package/dist/cli/{chunk-HOWQKN6J.mjs → chunk-HI7TAWFS.mjs}

@@ -10,7 +10,7 @@ import {
 import {
   recentSearchRef,
   registerDeprecatedSearchCommand
-} from "./chunk-D6GD5AVN.mjs";
+} from "./chunk-3RZJ3GEG.mjs";
 import {
   extractSummaryFields,
   projectRowOutput,
@@ -22,7 +22,7 @@ import {
 import {
   DeeplineClient,
   validateExecutionIdempotencyKey
-} from "./chunk-QZAP5VOS.mjs";
+} from "./chunk-OZGU7P2S.mjs";
 import {
   beginToolExecuteCommand,
   getToolExecuteInvocationId,
@@ -36,11 +36,14 @@ import {
   printJsonError,
   renderCommandEnvelopeText,
   shouldEmitJson
-} from "./chunk-F45425TB.mjs";
+} from "./chunk-EROOAI5G.mjs";
 import {
   resolveConfig,
   sdkCliStateDirPath
-} from "./chunk-CCRQ2VGJ.mjs";
+} from "./chunk-FK7PW6BP.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-KJWOHMKC.mjs");
+      const { describeAnything } = await import("./describe-XWOWAR32.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-RSEVBSFE.mjs → chunk-HVPRQGF4.mjs}

@@ -1,6 +1,6 @@
 import {
   resolveShellSpawn
-} from "./chunk-3ITDKXNC.mjs";
+} from "./chunk-YNSCELIJ.mjs";
 
 // src/cli/npm-script-policy.ts
 import { spawnSync } from "child_process";