deepline 0.1.140 → 0.1.141

package/dist/cli/index.js

@@ -413,10 +413,10 @@ var SDK_RELEASE = {
   // 0.1.108 ships explicit dataset column/tool recompute policy and removes
   // the SDK enrich generator's one-second stale policy.
   // 0.1.110 ships authored V2 prebuilts and required top-level play descriptions.
-  version: "0.1.140",
+  version: "0.1.141",
   apiContract: "2026-06-dataset-column-cell-stale-hard-cutover",
   supportPolicy: {
-    latest: "0.1.140",
+    latest: "0.1.141",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53",
     commandMinimumSupported: [
@@ -1177,6 +1177,10 @@ function normalizeStepProgress(value) {
     ...optionalFiniteNumber(value.completed) !== void 0 ? { completed: optionalFiniteNumber(value.completed) } : {},
     ...optionalFiniteNumber(value.total) !== void 0 ? { total: optionalFiniteNumber(value.total) } : {},
     ...optionalFiniteNumber(value.failed) !== void 0 ? { failed: optionalFiniteNumber(value.failed) } : {},
+    ...optionalFiniteNumber(value.startedRows) !== void 0 ? { startedRows: optionalFiniteNumber(value.startedRows) } : {},
+    ...optionalFiniteNumber(value.activeRows) !== void 0 ? { activeRows: optionalFiniteNumber(value.activeRows) } : {},
+    ...optionalFiniteNumber(value.waitingRows) !== void 0 ? { waitingRows: optionalFiniteNumber(value.waitingRows) } : {},
+    ...optionalFiniteNumber(value.completedRows) !== void 0 ? { completedRows: optionalFiniteNumber(value.completedRows) } : {},
     ...optionalString(value.message) ? { message: optionalString(value.message) } : {},
     ...optionalNullableString(value.artifactTableNamespace) !== void 0 ? {
       artifactTableNamespace: optionalNullableString(
@@ -1259,6 +1263,10 @@ function buildSnapshotFromLedger(snapshot) {
       completed: step.progress.completed,
       total: step.progress.total,
       failed: step.progress.failed,
+      startedRows: step.progress.startedRows,
+      activeRows: step.progress.activeRows,
+      waitingRows: step.progress.waitingRows,
+      completedRows: step.progress.completedRows,
       message: step.progress.message,
       artifactTableNamespace: step.progress.artifactTableNamespace ?? step.artifactTableNamespace ?? null,
       startedAt: step.startedAt ?? null,
@@ -1455,6 +1463,10 @@ function diffPlayRunStreamEvents(input2) {
             completed: state.progress.completed,
             total: state.progress.total,
             failed: state.progress.failed,
+            startedRows: state.progress.startedRows,
+            activeRows: state.progress.activeRows,
+            waitingRows: state.progress.waitingRows,
+            completedRows: state.progress.completedRows,
             message: state.progress.message,
             artifactTableNamespace: state.progress.artifactTableNamespace ?? state.artifactTableNamespace ?? null,
             ...resolveTimingWindow({
@@ -2292,6 +2304,28 @@ var DeeplineClient = class {
       }
     );
   }
+  /**
+   * Describe a Deepline Agent model and its provider-specific option surface.
+   *
+   * Combines live AI Gateway model metadata with Deepline's generated AI SDK
+   * provider option registry so agents can construct `providerOptions`
+   * payloads before executing `deeplineagent`.
+   *
+   * The returned option schemas describe accepted provider option shapes, not
+   * guaranteed support for every model. Runtime AI SDK/Gateway errors remain
+   * authoritative for model-gated values.
+   *
+   * @param model - Gateway model id such as `"openai/gpt-5.5"`
+   * @returns Model metadata, provider option shapes, and runnable examples
+   */
+  async describeModel(model) {
+    return this.http.request(
+      `/api/v2/models/describe?model=${encodeURIComponent(model)}`,
+      {
+        method: "GET"
+      }
+    );
+  }
   /**
    * Execute a tool and return the standard execution envelope.
    *
@@ -19473,6 +19507,66 @@ function extractSummaryFields(payload) {
   return {};
 }
 
+// src/cli/commands/model-description.ts
+function formatModelDescription(description) {
+  const lines = [];
+  lines.push(description.model);
+  lines.push(`Provider: ${description.provider}`);
+  const name = stringField(description.modelMetadata, "name");
+  if (name) lines.push(`Name: ${name}`);
+  const contextWindow = numberField(
+    description.modelMetadata,
+    "context_window"
+  );
+  if (contextWindow !== null) lines.push(`Context: ${contextWindow}`);
+  const tags = arrayField(description.modelMetadata, "tags").filter(
+    (value) => typeof value === "string"
+  );
+  if (tags.length) lines.push(`Tags: ${tags.join(", ")}`);
+  lines.push("");
+  lines.push("Provider options:");
+  appendNamespace(lines, description.providerOptions.gateway);
+  if (description.providerOptions.selectedProvider) {
+    appendNamespace(lines, description.providerOptions.selectedProvider);
+  }
+  lines.push("");
+  lines.push("Example input:");
+  lines.push(JSON.stringify(description.exampleInput, null, 2));
+  if (description.caveats.length) {
+    lines.push("");
+    lines.push("Caveats:");
+    for (const caveat of description.caveats) {
+      lines.push(`- ${caveat}`);
+    }
+  }
+  return `${lines.join("\n")}
+`;
+}
+function appendNamespace(lines, namespace) {
+  lines.push(`- ${namespace.provider} (${namespace.sourceSymbol})`);
+  for (const field of namespace.fields) {
+    const values = field.enumValues?.length ? ` (${field.enumValues.map((value) => JSON.stringify(value)).join(" | ")})` : "";
+    lines.push(
+      `  - ${field.name}: ${field.type}${values} - ${field.description}`
+    );
+  }
+}
+function stringField(value, key) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const candidate = value[key];
+  return typeof candidate === "string" && candidate.trim() ? candidate.trim() : null;
+}
+function numberField(value, key) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const candidate = value[key];
+  return typeof candidate === "number" ? candidate : null;
+}
+function arrayField(value, key) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return [];
+  const candidate = value[key];
+  return Array.isArray(candidate) ? candidate : [];
+}
+
 // src/cli/commands/tools.ts
 var TOOL_COMMAND_TEMPLATES = {
   describe: "deepline tools describe <toolId>",
@@ -19699,7 +19793,7 @@ function isPlayLikeTool(tool) {
 }
 function playReferenceForTool(tool) {
   const record = tool;
-  const declared = stringField(record, "playReference", "play_reference");
+  const declared = stringField2(record, "playReference", "play_reference");
   if (declared.startsWith("prebuilt/")) {
     return declared;
   }
@@ -19842,9 +19936,13 @@ Examples:
   deepline tools describe hunter_email_verifier --schema-only
   deepline tools describe hunter_email_verifier --examples-only
   deepline tools describe hunter_email_verifier --json
+  deepline tools describe deeplineagent --model openai/gpt-5.5 --json
   deepline tools execute hunter_email_verifier --input '{"email":"a@b.com"}'
 `
-  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").option("--pricing-only", "Only print pricing and billing semantics").option("--schema-only", "Only print input schema fields").option(
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").option(
+    "--model <model>",
+    "For deeplineagent, include AI Gateway model/provider option metadata"
+  ).option("--pricing-only", "Only print pricing and billing semantics").option("--schema-only", "Only print input schema fields").option(
     "--examples-only",
     "Only print runnable examples and sample payloads"
   ).option("--getters-only", "Only print extracted list/value getters").addOption(
@@ -19865,7 +19963,8 @@ Examples:
       pricingOnly: Boolean(options.pricingOnly),
       schemaOnly: Boolean(options.schemaOnly),
       examplesOnly: Boolean(options.examplesOnly),
-      gettersOnly: Boolean(options.gettersOnly)
+      gettersOnly: Boolean(options.gettersOnly),
+      model: typeof options.model === "string" ? options.model : void 0
     });
   });
   addToolMetadataCommand(tools.command("describe <toolId>").alias("get"));
@@ -19937,9 +20036,19 @@ async function getTool(toolId, options = {}) {
     }
     throw error;
   }
+  const modelDescription = options.model && (toolId === "deeplineagent" || toolId === "ai_inference") ? await client2.describeModel(options.model) : null;
+  if (options.model && !modelDescription) {
+    console.error(
+      "--model is only supported for deeplineagent and ai_inference."
+    );
+    return 2;
+  }
   if (options.contractJson) {
     process.stdout.write(
-      `${JSON.stringify(toolContractJsonForDescribe(tool, toolId))}
+      `${JSON.stringify({
+        ...toolContractJsonForDescribe(tool, toolId),
+        ...modelDescription ? { modelOptions: modelDescription } : {}
+      })}
 `
     );
     return 0;
@@ -19947,7 +20056,10 @@ async function getTool(toolId, options = {}) {
   const emitJson = options.json === true;
   if (emitJson) {
     process.stdout.write(
-      `${JSON.stringify(toolMetadataJsonForDescribe(tool, toolId))}
+      `${JSON.stringify({
+        ...toolMetadataJsonForDescribe(tool, toolId),
+        ...modelDescription ? { modelOptions: modelDescription } : {}
+      })}
 `
     );
     return 0;
@@ -19982,16 +20094,27 @@ async function getTool(toolId, options = {}) {
   }
   if (options.compact) {
     printCompactToolContract(tool, toolId);
+    if (modelDescription) {
+      process.stdout.write(`
+${formatModelDescription(modelDescription)}`);
+    }
     return 0;
   }
   if (shouldEmitJson()) {
     process.stdout.write(
-      `${JSON.stringify(toolContractJsonForDescribe(tool, toolId))}
+      `${JSON.stringify({
+        ...toolContractJsonForDescribe(tool, toolId),
+        ...modelDescription ? { modelOptions: modelDescription } : {}
+      })}
 `
     );
     return 0;
   }
   printCompactToolContract(tool, toolId);
+  if (modelDescription) {
+    process.stdout.write(`
+${formatModelDescription(modelDescription)}`);
+  }
   return 0;
 }
 function toolContractJsonForDescribe(tool, requestedToolId) {
@@ -20006,18 +20129,18 @@ function toolContractJsonForDescribe(tool, requestedToolId) {
     "tool_execution_result"
   );
   const extractedLists = extractionContractEntries(
-    arrayField(toolExecutionResult, "extractedLists", "extracted_lists")
+    arrayField2(toolExecutionResult, "extractedLists", "extracted_lists")
   );
   const extractedValues = extractionContractEntries(
-    arrayField(toolExecutionResult, "extractedValues", "extracted_values")
+    arrayField2(toolExecutionResult, "extractedValues", "extracted_values")
   );
   const cost = recordField2(tool, "cost");
-  const deeplineCredits = numberField(
+  const deeplineCredits = numberField2(
     tool,
     "deeplineCreditsPerPricingUnit",
     "deepline_credits_per_pricing_unit"
   );
-  const deeplineUsdPerPricingUnit = numberField(
+  const deeplineUsdPerPricingUnit = numberField2(
     tool,
     "deeplineUsdPerPricingUnit",
     "deepline_usd_per_pricing_unit"
@@ -20045,8 +20168,8 @@ function toolContractJsonForDescribe(tool, requestedToolId) {
       ...Object.prototype.hasOwnProperty.call(field, "default") ? { default: field.default } : {}
     })),
     cost: {
-      pricingModel: stringField(cost, "pricingModel", "pricing_model") || null,
-      billingMode: stringField(cost, "billingMode", "billing_mode") || null,
+      pricingModel: stringField2(cost, "pricingModel", "pricing_model") || null,
+      billingMode: stringField2(cost, "billingMode", "billing_mode") || null,
       deeplineCreditsPerPricingUnit: deeplineCredits,
       deeplineUsdPerPricingUnit
     },
@@ -20061,8 +20184,8 @@ function toolContractJsonForDescribe(tool, requestedToolId) {
 function extractionContractEntries(entries) {
   return entries.flatMap((entry) => {
     if (!isRecord8(entry)) return [];
-    const name = stringField(entry, "name");
-    const expression = stringField(entry, "expression");
+    const name = stringField2(entry, "name");
+    const expression = stringField2(entry, "expression");
     return name && expression ? [{ name, expression }] : [];
   });
 }
@@ -20087,11 +20210,11 @@ function printCompactToolContract(tool, requestedToolId) {
     console.log("Inputs:");
     for (const field of inputFields) {
       if (!isRecord8(field)) continue;
-      const name = stringField(field, "name");
+      const name = stringField2(field, "name");
       if (!name) continue;
       const required = field.required ? "*" : "";
-      const type = stringField(field, "type") || "unknown";
-      const description = stringField(field, "description");
+      const type = stringField2(field, "type") || "unknown";
+      const description = stringField2(field, "description");
       console.log(
         `- ${name}${required}: ${type}${description ? ` - ${description}` : ""}`
       );
@@ -20100,7 +20223,7 @@ function printCompactToolContract(tool, requestedToolId) {
   console.log("");
   printToolExamplesOnly(tool, requestedToolId, { includeSamples: false });
   const starterScript = isRecord8(contract.starterScript) ? contract.starterScript : {};
-  const starterPath = stringField(starterScript, "path");
+  const starterPath = stringField2(starterScript, "path");
   if (starterPath) {
     console.log("");
     console.log(`Starter script: ${starterPath}`);
@@ -20115,14 +20238,14 @@ function printCompactToolContract(tool, requestedToolId) {
     for (const entry of listGetters) {
       if (isRecord8(entry))
         console.log(
-          `- ${stringField(entry, "name")}: ${playResultExpression(entry)}`
+          `- ${stringField2(entry, "name")}: ${playResultExpression(entry)}`
         );
     }
     if (valueGetters.length) console.log("Values:");
     for (const entry of valueGetters) {
       if (isRecord8(entry))
         console.log(
-          `- ${stringField(entry, "name")}: ${playResultExpression(entry)}`
+          `- ${stringField2(entry, "name")}: ${playResultExpression(entry)}`
         );
     }
   }
@@ -20134,11 +20257,11 @@ function printCompactToolContract(tool, requestedToolId) {
 function printToolPricingOnly(tool, requestedToolId, options = {}) {
   const contract = toolContractJsonForDescribe(tool, requestedToolId);
   const cost = isRecord8(contract.cost) ? contract.cost : {};
-  const pricingModel = stringField(cost, "pricingModel") || "unknown";
-  const billingMode = stringField(cost, "billingMode") || "unknown";
+  const pricingModel = stringField2(cost, "pricingModel") || "unknown";
+  const billingMode = stringField2(cost, "billingMode") || "unknown";
   const unit = pricingModel === "per_page" ? "page" : pricingModel === "per_result" ? "result" : pricingModel === "fixed" ? "call" : pricingModel.replace(/^per_/, "") || "unit";
-  const credits = numberField(cost, "deeplineCreditsPerPricingUnit");
-  const usd = numberField(cost, "deeplineUsdPerPricingUnit");
+  const credits = numberField2(cost, "deeplineCreditsPerPricingUnit");
+  const usd = numberField2(cost, "deeplineUsdPerPricingUnit");
   const price = credits !== null ? `${formatDecimal(credits)} Deepline credits${usd !== null ? ` / ${formatUsd(usd)}` : ""} per ${unit}` : "pricing unavailable";
   console.log(`${options.heading ?? `Pricing: ${contract.toolId}`}: ${price}`);
   console.log(`Billing: ${billingMode}`);
@@ -20154,11 +20277,11 @@ function printToolSchemaOnly(tool, requestedToolId) {
   console.log("Inputs:");
   for (const field of inputFields) {
     if (!isRecord8(field)) continue;
-    const name = stringField(field, "name");
+    const name = stringField2(field, "name");
     if (!name) continue;
     const required = field.required ? "*" : "";
-    const type = stringField(field, "type") || "unknown";
-    const description = stringField(field, "description");
+    const type = stringField2(field, "type") || "unknown";
+    const description = stringField2(field, "description");
     const defaultSuffix = Object.prototype.hasOwnProperty.call(field, "default") ? ` default=${JSON.stringify(field.default)}` : "";
     console.log(
       `- ${name}${required}: ${type}${defaultSuffix}${description ? ` - ${description}` : ""}`
@@ -20188,8 +20311,8 @@ function printToolExamplesOnly(tool, requestedToolId, options = {}) {
   const listGetters = Array.isArray(getters.extractedLists) ? getters.extractedLists : [];
   const firstGetter = [...valueGetters, ...listGetters].find(isRecord8);
   if (firstGetter) {
-    const name = stringField(firstGetter, "name") || "value";
-    const expression = stringField(firstGetter, "expression");
+    const name = stringField2(firstGetter, "name") || "value";
+    const expression = stringField2(firstGetter, "expression");
     if (expression)
       console.log(
         `const ${safeIdentifier2(name)} = ${expression.replace(/^toolExecutionResult\./, "result.")};`
@@ -20237,7 +20360,7 @@ function printToolGettersOnly(tool, requestedToolId) {
     for (const entry of listGetters) {
       if (isRecord8(entry))
         console.log(
-          `- ${stringField(entry, "name")}: ${playResultExpression(entry)}`
+          `- ${stringField2(entry, "name")}: ${playResultExpression(entry)}`
         );
     }
   }
@@ -20246,14 +20369,14 @@ function printToolGettersOnly(tool, requestedToolId) {
     for (const entry of valueGetters) {
       if (isRecord8(entry))
         console.log(
-          `- ${stringField(entry, "name")}: ${playResultExpression(entry)}`
+          `- ${stringField2(entry, "name")}: ${playResultExpression(entry)}`
         );
     }
   }
 }
 function sampleValueForField(field) {
-  const name = stringField(field, "name").toLowerCase();
-  const type = stringField(field, "type").toLowerCase();
+  const name = stringField2(field, "name").toLowerCase();
+  const type = stringField2(field, "type").toLowerCase();
   if (Object.prototype.hasOwnProperty.call(field, "default"))
     return field.default;
   if (name.includes("email")) return "ada@example.com";
@@ -20271,7 +20394,7 @@ function samplePayloadForInputFields(fields) {
   return Object.fromEntries(
     fields.slice(0, 4).flatMap((field) => {
       if (!isRecord8(field)) return [];
-      const name = stringField(field, "name");
+      const name = stringField2(field, "name");
       if (!name) return [];
       return [[name, sampleValueForField(field)]];
     })
@@ -20285,7 +20408,7 @@ function safeIdentifier2(name) {
   return cleaned || "value";
 }
 function playResultExpression(entry) {
-  return stringField(entry, "expression").replace(
+  return stringField2(entry, "expression").replace(
     /^toolExecutionResult\./,
     "result."
   );
@@ -20304,7 +20427,7 @@ function toolMetadataJsonForDescribe(tool, requestedToolId) {
     "tool_execution_result"
   );
   const extractedLists = extractionContractEntries(
-    arrayField(toolExecutionResult, "extractedLists", "extracted_lists")
+    arrayField2(toolExecutionResult, "extractedLists", "extracted_lists")
   );
   const starterScript = !isPlayLikeTool(tool) && extractedLists.length > 0 ? starterScriptJson(
     seedToolListScript({
@@ -20383,7 +20506,7 @@ function listedToolDescription(tool) {
 function formatListedToolCost(tool) {
   const record = tool;
   const pricing = recordField2(record, "pricing");
-  const displayText = stringField(pricing, "displayText", "display_text");
+  const displayText = stringField2(pricing, "displayText", "display_text");
   return displayText ? `Cost: ${displayText}` : "";
 }
 function toolInputFieldsForDisplay(inputSchema) {
@@ -20449,21 +20572,21 @@ function formatUsd(value) {
 function isRecord8(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
-function stringField(source, ...keys) {
+function stringField2(source, ...keys) {
   for (const key of keys) {
     const value = source[key];
     if (typeof value === "string" && value.trim()) return value.trim();
   }
   return "";
 }
-function numberField(source, ...keys) {
+function numberField2(source, ...keys) {
   for (const key of keys) {
     const value = source[key];
     if (typeof value === "number" && Number.isFinite(value)) return value;
   }
   return null;
 }
-function arrayField(source, ...keys) {
+function arrayField2(source, ...keys) {
   for (const key of keys) {
     const value = source[key];
     if (Array.isArray(value)) return value;