deepline 0.3.140 → 0.3.142

package/dist/cli/index.js

@@ -3068,7 +3068,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.140",
+  version: "0.3.142",
   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
@@ -9630,6 +9630,7 @@ var DeeplineClient = class _DeeplineClient {
       "/api/v2/billing/plan-transitions",
       {
         action: options.action,
+        ...options.action === "start_or_change" && options.billingEmail ? { billing_email: options.billingEmail } : {},
         ...options.targetPlanSku ? { target_plan_sku: options.targetPlanSku } : {}
       },
       { "Idempotency-Key": idempotencyKey },
@@ -11090,6 +11091,10 @@ function errorToJsonPayload(error) {
   if (maybeRecord?.details && typeof maybeRecord.details === "object" && !Array.isArray(maybeRecord.details)) {
     details.details = maybeRecord.details;
   }
+  const providerConcurrency = providerConcurrencyDiagnostic(maybeRecord);
+  if (providerConcurrency) {
+    details.providerConcurrency = providerConcurrency;
+  }
   if (typeof maybeRecord?.cause === "string") {
     details.cause = maybeRecord.cause;
   }
@@ -11103,6 +11108,33 @@ function errorToJsonPayload(error) {
     }
   };
 }
+function formatProviderConcurrencyDiagnostic(error) {
+  const value = error && typeof error === "object" ? error : null;
+  const diagnostic = providerConcurrencyDiagnostic(value);
+  if (!diagnostic) return null;
+  const count = diagnostic.inFlightProviderRequestsAt429;
+  const concurrency = count > 1 ? `${count - 1} other same-provider request${count === 2 ? "" : "s"} overlapped the failed request` : "no other same-provider request was active";
+  return `Provider concurrency at the 429: ${count} active request${count === 1 ? "" : "s"} in this Play execution, including the failed request; ${concurrency}. Other Play executions and direct CLI/API calls are not included.`;
+}
+function providerConcurrencyDiagnostic(value) {
+  if (!value || value.origin !== "provider" || value.statusCode !== 429 && value.status !== 429) {
+    return null;
+  }
+  const publicDetails = value.publicDetails;
+  if (!publicDetails || typeof publicDetails !== "object" || Array.isArray(publicDetails)) {
+    return null;
+  }
+  const details = publicDetails;
+  const count = details.inFlightProviderRequestsAt429;
+  if (details.providerConcurrencyScope !== "same_provider_in_play_execution" || details.includesFailedRequest !== true || typeof count !== "number" || !Number.isInteger(count) || count < 1) {
+    return null;
+  }
+  return {
+    scope: "same_provider_in_play_execution",
+    inFlightProviderRequestsAt429: count,
+    includesFailedRequest: true
+  };
+}
 function printJsonError(error) {
   printJson(errorToJsonPayload(error));
 }
@@ -13141,6 +13173,7 @@ async function handleTargetPlan(planSku, options) {
   const payload = await new DeeplineClient().billing.transitionPlan({
     action: "start_or_change",
     targetPlanSku: planSku,
+    ...options.billingEmail ? { billingEmail: options.billingEmail } : {},
     idempotencyKey
   });
   printCommandEnvelope(
@@ -13425,6 +13458,9 @@ Examples:
   billing.command("change-plan").description("Start or change the target billing plan.").argument(
     "<plan_sku>",
     "payg-v1, builder-v1, growth-v1, growth-canary-v1, or team-v1"
+  ).option(
+    "--billing-email <email>",
+    "Invoice recipient when the account has no billing email"
   ).option("--idempotency-key <key>", "Stable retry key").option("--json", "Emit JSON output").action(handleTargetPlan);
   billing.command("cancel-plan").description("Cancel a target subscription at period end, or undo it.").option("--undo", "Undo a pending period-end cancellation").option("--idempotency-key <key>", "Stable retry key").option("--json", "Emit JSON output").action(handleTargetPlanCancellation);
   billing.command("portal").description("Open the Stripe-hosted billing recovery portal.").option("--no-open", "Print the URL without opening a browser").option("--json", "Emit JSON output").action(handleTargetPortal);
@@ -25377,6 +25413,14 @@ function buildRunPackageTextLines(packaged) {
   const lines = isRuntimeLimitCheckpoint ? runtimeLimitCheckpointLines(packaged, runId, checkpointFailure) : [
     `${status === "completed" ? "\u2713" : status === "failed" ? "\u2717" : "\u2022"} ${status}  ${runId}`
   ];
+  const outcome = typeof run.outcome === "string" ? run.outcome : null;
+  if (outcome) lines.push(`  outcome: ${outcome}`);
+  const recovery = readRecord(run.recovery);
+  if (recovery) {
+    const mode = typeof recovery.mode === "string" ? recovery.mode : "recovered";
+    const sourceRunId = typeof recovery.sourceRunId === "string" ? ` from ${recovery.sourceRunId}` : "";
+    lines.push(`  recovery: ${mode}${sourceRunId}`);
+  }
   const runError = typeof run.error === "string" && run.error.trim() ? run.error.trim() : null;
   const structuredRuntimeLimitMessage = typeof runtimeLimitFailure?.message === "string" && runtimeLimitFailure.message.trim() ? `${typeof runtimeLimitFailure.code === "string" ? runtimeLimitFailure.code : "RUNTIME_LIMIT_EXCEEDED"}: ${runtimeLimitFailure.message.trim()}` : null;
   const displayRunError = structuredRuntimeLimitMessage ?? runError;
@@ -48089,6 +48133,8 @@ function toolContractJsonForDescribe(tool, requestedToolId) {
   const inputSchema = publicToolInputSchemaForDescribe(
     recordField2(tool, "inputSchema", "input_schema")
   );
+  const outputSchemaRecord = recordField2(tool, "outputSchema", "output_schema");
+  const outputFields = toolOutputFieldsForDisplay(outputSchemaRecord);
   const usageGuidance = recordField2(tool, "usageGuidance", "usage_guidance");
   const toolExecutionResult = recordField2(
     usageGuidance,
@@ -48102,6 +48148,18 @@ function toolContractJsonForDescribe(tool, requestedToolId) {
     arrayField2(toolExecutionResult, "extractedValues", "extracted_values")
   );
   const pricing = Capability.fromCatalogEntry(tool).describe().customerCost();
+  const executionMetadataRecord = recordField2(
+    tool,
+    "executionMetadata",
+    "execution_metadata"
+  );
+  const executionMetadata = Object.keys(executionMetadataRecord).length > 0 ? executionMetadataRecord : null;
+  const batchCapabilityRecord = recordField2(
+    tool,
+    "batchCapability",
+    "batch_capability"
+  );
+  const batchCapability = Object.keys(batchCapabilityRecord).length > 0 ? batchCapabilityRecord : null;
   const deprecation = recordField2(tool, "deprecation");
   const replacementToolId = stringField2(
     deprecation,
@@ -48135,14 +48193,14 @@ function toolContractJsonForDescribe(tool, requestedToolId) {
         ...deprecationExecution ? { execution: deprecationExecution } : {}
       }
     } : {},
-    inputFields: inputFields.map((field) => ({
-      name: field.name,
-      type: field.type ?? "unknown",
-      required: Boolean(field.required),
-      ...field.description ? { description: field.description } : {},
-      ...Object.prototype.hasOwnProperty.call(field, "default") ? { default: field.default } : {}
-    })),
+    inputFields: inputFields.map(inputFieldJsonForDescribe),
     inputSchema,
+    ...Object.keys(outputSchemaRecord).length > 0 ? {
+      outputSchema: publicToolInputSchemaForDescribe(outputSchemaRecord),
+      outputFields: outputFields.map(inputFieldJsonForDescribe)
+    } : {},
+    ...executionMetadata ? { executionMetadata } : {},
+    ...batchCapability ? { batchCapability } : {},
     cost: pricing,
     getters: {
       extractedLists,
@@ -48294,6 +48352,8 @@ function printCompactToolContract(tool, requestedToolId) {
   if (Array.isArray(contract.categories) && contract.categories.length) {
     console.log(`Tags: ${contract.categories.join(", ")}`);
   }
+  printToolOutputArrayShape(contract);
+  printToolExecutionHints(contract);
   if (contract.deprecated === true) {
     const deprecation = isRecord12(contract.deprecation) ? contract.deprecation : {};
     const message = stringField2(deprecation, "message");
@@ -48330,12 +48390,13 @@ function printCompactToolContract(tool, requestedToolId) {
       const description = stringField2(field, "description");
       const enumValues = Array.isArray(field.enum) ? field.enum : [];
       const enumSuffix = enumValues.length ? ` enum=${enumValues.map(String).join("|")}` : "";
+      const itemBoundsSuffix = arrayItemBoundsSuffix(field);
       const defaultSuffix = Object.prototype.hasOwnProperty.call(
         field,
         "default"
       ) ? ` default=${JSON.stringify(field.default)}` : "";
       console.log(
-        `- ${name}${required}: ${type}${enumSuffix}${defaultSuffix}${description ? ` - ${description}` : ""}`
+        `- ${name}${required}: ${type}${enumSuffix}${itemBoundsSuffix}${defaultSuffix}${description ? ` - ${description}` : ""}`
       );
     }
   }
@@ -48415,15 +48476,17 @@ function printToolSchemaOnly(tool, requestedToolId) {
       const description = typeof field.description === "string" ? field.description : "";
       const enumValues = Array.isArray(field.enum) ? field.enum : [];
       const enumSuffix = enumValues.length ? ` enum=${enumValues.map(String).join("|")}` : "";
+      const itemBoundsSuffix = arrayItemBoundsSuffix(field);
       const defaultSuffix = Object.prototype.hasOwnProperty.call(
         field,
         "default"
       ) ? ` default=${JSON.stringify(field.default)}` : "";
       console.log(
-        `- ${name}${required}: ${type}${enumSuffix}${defaultSuffix}${description ? ` - ${description}` : ""}`
+        `- ${name}${required}: ${type}${enumSuffix}${itemBoundsSuffix}${defaultSuffix}${description ? ` - ${description}` : ""}`
       );
     }
   }
+  printToolOutputArrayShape(contract);
   const declaredSchema = declaredToolJsonSchema(
     recordField2(contract, "inputSchema")
   );
@@ -48599,11 +48662,19 @@ function toolMetadataJsonForDescribe(tool, requestedToolId) {
     deepline_pricing_details: _snakeDeeplinePricingDetails,
     ...publicTool
   } = tool;
+  const outputSchemaRecord = recordField2(tool, "outputSchema", "output_schema");
   return {
     ...publicTool,
     toolId,
     provider: tool.provider,
     displayName: tool.displayName,
+    ...Object.keys(outputSchemaRecord).length > 0 ? {
+      outputSchema: publicToolInputSchemaForDescribe(outputSchemaRecord),
+      outputFields: toolOutputFieldsForDisplay(outputSchemaRecord).map(
+        inputFieldJsonForDescribe
+      )
+    } : {},
+    inputFields: inputFields.map(inputFieldJsonForDescribe),
     cost: Capability.fromCatalogEntry(tool).describe().customerCost(),
     usageGuidance,
     runtimeOutputHelp: {
@@ -48662,8 +48733,27 @@ function formatListedToolCost(tool) {
   return displayText ? `Cost: ${displayText}` : "";
 }
 function toolInputFieldsForDisplay(inputSchema) {
-  if (Array.isArray(inputSchema.fields))
-    return inputSchema.fields.filter(isRecord12);
+  if (Array.isArray(inputSchema.fields)) {
+    const fields = inputSchema.fields.filter(isRecord12);
+    if (!isRecord12(inputSchema.jsonSchema)) return fields;
+    const jsonSchemaFields = new Map(
+      recursiveToolInputFieldsForDisplay({
+        jsonSchema: inputSchema.jsonSchema
+      }).flatMap(
+        (field) => typeof field.name === "string" ? [[field.name, field]] : []
+      )
+    );
+    return fields.map((field) => {
+      const jsonSchemaField = typeof field.name === "string" ? jsonSchemaFields.get(field.name) : void 0;
+      const minItems = typeof field.minItems === "number" ? field.minItems : jsonSchemaField?.minItems;
+      const maxItems = typeof field.maxItems === "number" ? field.maxItems : jsonSchemaField?.maxItems;
+      return {
+        ...field,
+        ...typeof minItems === "number" ? { minItems } : {},
+        ...typeof maxItems === "number" ? { maxItems } : {}
+      };
+    });
+  }
   const jsonSchema = isRecord12(inputSchema.jsonSchema) ? inputSchema.jsonSchema : inputSchema;
   const properties = isRecord12(jsonSchema.properties) ? jsonSchema.properties : {};
   const required = Array.isArray(jsonSchema.required) ? new Set(jsonSchema.required.map(String)) : /* @__PURE__ */ new Set();
@@ -48674,10 +48764,36 @@ function toolInputFieldsForDisplay(inputSchema) {
       type: typeof property.type === "string" ? property.type : "unknown",
       required: required.has(name),
       description: property.description,
+      ...typeof property.minItems === "number" ? { minItems: property.minItems } : {},
+      ...typeof property.maxItems === "number" ? { maxItems: property.maxItems } : {},
       ...Object.prototype.hasOwnProperty.call(property, "default") ? { default: property.default } : {}
     };
   });
 }
+function toolOutputFieldsForDisplay(outputSchema) {
+  if (Object.keys(outputSchema).length === 0) return [];
+  return recursiveToolInputFieldsForDisplay({
+    jsonSchema: outputSchema
+  }).filter(
+    (field) => typeof field.name === "string" && field.name.includes("[]")
+  );
+}
+function printToolOutputArrayShape(tool) {
+  const outputFields = toolOutputFieldsForDisplay(
+    recordField2(isRecord12(tool) ? tool : {}, "outputSchema", "output_schema")
+  );
+  if (outputFields.length === 0) return;
+  console.log("  Output array shape (declared schema):");
+  for (const field of outputFields.slice(0, 60)) {
+    const name = String(field.name);
+    const type = stringField2(field, "type") || "unknown";
+    const itemBounds = arrayItemBoundsSuffix(field);
+    console.log(`    - ${name}: ${type}${itemBounds}`);
+  }
+  if (outputFields.length > 60) {
+    console.log(`    - \u2026 ${outputFields.length - 60} more schema fields`);
+  }
+}
 function canonicalToolJsonSchema(inputSchema) {
   return isRecord12(inputSchema.jsonSchema) ? inputSchema.jsonSchema : inputSchema;
 }
@@ -48767,6 +48883,8 @@ function recursiveToolInputFieldsForDisplay(inputSchema) {
         required,
         description: schema.description,
         ...Array.isArray(schema.enum) ? { enum: schema.enum } : {},
+        ...typeof schema.minItems === "number" ? { minItems: schema.minItems } : {},
+        ...typeof schema.maxItems === "number" ? { maxItems: schema.maxItems } : {},
         ...Object.prototype.hasOwnProperty.call(schema, "default") ? { default: schema.default } : {}
       });
     }
@@ -48798,6 +48916,121 @@ function recursiveToolInputFieldsForDisplay(inputSchema) {
   visit(root, "", false);
   return fields.size ? [...fields.values()] : toolInputFieldsForDisplay(inputSchema);
 }
+function inputFieldJsonForDescribe(field) {
+  return {
+    name: field.name,
+    type: field.type ?? "unknown",
+    required: Boolean(field.required),
+    ...field.description ? { description: field.description } : {},
+    ...typeof field.minItems === "number" ? { minItems: field.minItems } : {},
+    ...typeof field.maxItems === "number" ? { maxItems: field.maxItems } : {},
+    ...Object.prototype.hasOwnProperty.call(field, "default") ? { default: field.default } : {}
+  };
+}
+function arrayItemBoundsSuffix(field) {
+  const minItems = typeof field.minItems === "number" && Number.isFinite(field.minItems) ? field.minItems : null;
+  const maxItems = typeof field.maxItems === "number" && Number.isFinite(field.maxItems) ? field.maxItems : null;
+  if (minItems !== null && maxItems !== null) {
+    return ` items=${minItems}..${maxItems}`;
+  }
+  if (minItems !== null) return ` minItems=${minItems}`;
+  if (maxItems !== null) return ` maxItems=${maxItems}`;
+  return "";
+}
+function printToolExecutionHints(value) {
+  const batchCapabilityRecord = recordField2(
+    isRecord12(value) ? value : {},
+    "batchCapability",
+    "batch_capability"
+  );
+  const batchCapability = Object.keys(batchCapabilityRecord).length > 0 ? batchCapabilityRecord : null;
+  const executionMetadata = recordField2(
+    isRecord12(value) ? value : {},
+    "executionMetadata",
+    "execution_metadata"
+  );
+  if (batchCapability) {
+    const status = stringField2(batchCapability, "status") || "unknown";
+    const surface = stringField2(batchCapability, "surface");
+    const operation = stringField2(
+      batchCapability,
+      "batchOperation",
+      "batch_operation"
+    );
+    const maxBatchSize = numberField2(
+      batchCapability,
+      "maxBatchSize",
+      "max_batch_size"
+    );
+    const notes = stringField2(batchCapability, "notes");
+    console.log("");
+    console.log("Batching:");
+    console.log(`- Catalog status: ${status}${surface ? ` (${surface})` : ""}`);
+    if (operation) console.log(`- Batch operation: ${operation}`);
+    if (maxBatchSize !== null) {
+      console.log(`- Maximum batch size: ${maxBatchSize} items`);
+    }
+    if (status === "compiled") {
+      console.log(
+        "- Compatible per-row Play calls can coalesce; separate tools execute requests do not coalesce."
+      );
+    } else if (surface !== "docs") {
+      console.log(
+        "- Play does not automatically coalesce per-row calls for this operation; send a native batch as one request when its input schema supports one."
+      );
+    }
+    if (notes) console.log(`- Details: ${notes}`);
+  }
+  const configuredRateLimits = arrayField2(
+    executionMetadata,
+    "configuredRateLimits",
+    "configured_rate_limits"
+  ).filter(isRecord12);
+  if (configuredRateLimits.length > 0) {
+    console.log("");
+    console.log(
+      "Configured Deepline pacing (guidance, not a guaranteed provider quota):"
+    );
+    for (const limit of configuredRateLimits) {
+      const requests = numberField2(limit, "requestsPerWindow");
+      const windowMs = numberField2(limit, "windowMs");
+      if (requests === null || windowMs === null) continue;
+      const usage = stringField2(limit, "usage") || "unknown";
+      const usageText = usage === "queue_hint" ? "queue hint" : usage === "enforced" ? "Deepline enforced" : usage === "queue_hint_and_enforced" ? "queue hint and Deepline enforced" : usage === "disabled" ? "disabled" : usage;
+      const explicitMaxConcurrency = numberField2(
+        limit,
+        "explicitMaxConcurrency",
+        "explicit_max_concurrency"
+      );
+      const concurrencyText = explicitMaxConcurrency === null ? "no explicit concurrency limit" : `explicit concurrency limit ${explicitMaxConcurrency}`;
+      console.log(
+        `- ${requests} requests per ${formatRateWindow(windowMs)} (${usageText}; ${concurrencyText})`
+      );
+    }
+  }
+  const queueHint = recordField2(executionMetadata, "queueHint", "queue_hint");
+  const requestsPerSecondHint = numberField2(
+    queueHint,
+    "requestsPerSecondHint",
+    "requests_per_second_hint"
+  );
+  const derivedConcurrency = numberField2(
+    queueHint,
+    "derivedConcurrency",
+    "derived_concurrency"
+  );
+  if (requestsPerSecondHint !== null && requestsPerSecondHint > 0 && derivedConcurrency !== null) {
+    console.log(
+      `Derived runtime queue hint: ${requestsPerSecondHint} requests/second; ${derivedConcurrency} derived concurrency. This is not an observed provider concurrency limit.`
+    );
+  }
+}
+function formatRateWindow(windowMs) {
+  if (windowMs === 1e3) return "second";
+  if (windowMs === 6e4) return "minute";
+  if (windowMs === 36e5) return "hour";
+  return `${windowMs}ms`;
+}
 function printSamples(samples) {
   const requestPayload = samplePayload(samples, "request");
   const responsePayload = samplePayload(samples, "response");
@@ -50784,6 +51017,8 @@ Examples:
       printJsonError(error);
     } else if (error instanceof Error) {
       console.error(`Error: ${error.message}`);
+      const providerConcurrency = formatProviderConcurrencyDiagnostic(error);
+      if (providerConcurrency) console.error(providerConcurrency);
     } else {
       console.error(`Error: ${String(error)}`);
     }