deepline 0.3.140 → 0.3.142

package/dist/cli/index.mjs

@@ -3063,7 +3063,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
@@ -9625,6 +9625,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 },
@@ -11097,6 +11098,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;
   }
@@ -11110,6 +11115,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));
 }
@@ -13148,6 +13180,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(
@@ -13432,6 +13465,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);
@@ -25449,6 +25485,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;
@@ -48231,6 +48275,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,
@@ -48244,6 +48290,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,
@@ -48277,14 +48335,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,
@@ -48436,6 +48494,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");
@@ -48472,12 +48532,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}` : ""}`
       );
     }
   }
@@ -48557,15 +48618,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")
   );
@@ -48741,11 +48804,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: {
@@ -48804,8 +48875,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();
@@ -48816,10 +48906,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;
 }
@@ -48909,6 +49025,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 } : {}
       });
     }
@@ -48940,6 +49058,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");
@@ -50926,6 +51159,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)}`);
     }

package/dist/index.d.mts

@@ -1162,9 +1162,9 @@ interface ProviderDefinition {
  *
  * Returned by {@link DeeplineClient.listTools} and ranked tool search. Use
  * `getTool(toolId)` or the matching HTTP describe route for provider-specific
- * schema, examples, pricing, and extraction guidance before executing.
+ * schema, examples, pricing, extraction guidance, and execution metadata.
  */
-interface ToolDefinition {
+interface ToolDefinition extends ToolExecutionMetadataFields {
     /** Unique tool identifier used in API calls (e.g. `"dropleads_search_people"`). */
     toolId: string;
     /** Provider that backs this tool (e.g. `"hunter"`, `"dropleads"`, `"test"`). */
@@ -1299,6 +1299,42 @@ interface ToolDefinition {
     /** Actionable message shown when a connection is required. */
     connectionMessage?: string;
 }
+type ToolBatchCapability = {
+    status: 'compiled' | 'exposed_uncompiled' | 'upstream_only';
+    surface: 'registry' | 'local' | 'docs';
+    batchKind: 'identifier_batch' | 'query_share' | 'async_dataset_job';
+    batchOperation: string | null;
+    maxBatchSize: number | null;
+    notes: string;
+};
+/** Optional batching, pacing, and configured rate metadata for tool catalog entries. */
+interface ToolExecutionMetadataFields {
+    batchCapability?: ToolBatchCapability;
+    batch_capability?: ToolBatchCapability;
+    executionMetadata?: ToolExecutionMetadata;
+    execution_metadata?: ToolExecutionMetadata;
+}
+type ToolExecutionMetadata = {
+    provider: string;
+    sourceOperation: string;
+    effectiveOperation: string;
+    batch: {
+        batchOperation: string | null;
+        maxBatchSize: number;
+    };
+    configuredRateLimits: Array<{
+        source: 'deepline_configuration';
+        scope: string;
+        requestsPerWindow: number;
+        windowMs: number;
+        usage: 'queue_hint' | 'enforced' | 'queue_hint_and_enforced' | 'disabled';
+        explicitMaxConcurrency: number | null;
+    }>;
+    queueHint: {
+        requestsPerSecondHint: number;
+        derivedConcurrency: number;
+    };
+};
 interface ModelProviderOptionField {
     name: string;
     type: 'string' | 'number' | 'boolean' | 'object' | 'array';
@@ -1655,6 +1691,11 @@ interface PlayRunPackage {
         startedAt?: number | null;
         finishedAt?: number | null;
         durationMs?: number | null;
+        outcome?: PlayRunOutcome;
+        recovery?: {
+            mode: 'replayed' | 'forced' | 'recovered' | 'joined';
+            sourceRunId?: string;
+        };
         error?: string;
         /** Canonical explanation of what this run is doing or waiting on. */
         activity?: PlayRunActivityProjection | null;
@@ -1699,6 +1740,11 @@ interface PlayRunPackage {
         logs?: PlayRunActionPackage;
     };
 }
+/**
+ * Stable classification of whether this run executed work or reused/recovered
+ * an existing durable run outcome.
+ */
+type PlayRunOutcome = 'executed' | 'reused' | 'joined' | 'recovered' | 'forced' | 'waiting' | 'failed';
 /**
  * Current status of a play execution, returned by {@link DeeplineClient.getPlayStatus}.
  *
@@ -1730,6 +1776,12 @@ interface PlayStatus {
     dashboardUrl?: string;
     /** Product-level play-run state. */
     status: 'queued' | 'running' | 'waiting' | 'completed' | 'failed' | 'cancelled';
+    /** How this run was admitted or recovered, when the server can prove it. */
+    outcome?: PlayRunOutcome;
+    recovery?: {
+        mode: 'replayed' | 'forced' | 'recovered' | 'joined';
+        sourceRunId?: string;
+    };
     /** Execution progress with logs and error details. */
     progress?: PlayProgressStatus;
     /** Partial or final result. Available once the play returns. */
@@ -4102,6 +4154,20 @@ type TargetBillingStatusResult = {
     legacy_changes_allowed?: boolean;
     payment_state: string;
     recharge_state: string;
+    billing_email?: string | null;
+    collection_method?: 'charge_automatically' | 'send_invoice';
+    payment_access_policy?: 'payment_required' | 'net_30' | 'net_60';
+    plan_invoice?: {
+        url: string | null;
+        amount_usd: number;
+        due_at: string | null;
+        status: string | null;
+    } | null;
+    outstanding_invoice?: {
+        amount_usd: number;
+        due_at: string;
+        state: 'open' | 'cancelling';
+    } | null;
     next_action: string | null;
     pending_plan_sku: string | null;
     /** Saved transition boundary; optional for older servers. */
@@ -4144,6 +4210,7 @@ type TargetBillingMutationResult = {
 type TargetBillingPlanTransitionOptions = {
     action: 'start_or_change';
     targetPlanSku: 'payg-v1' | 'builder-v1' | 'growth-v1' | 'growth-canary-v1' | 'team-v1';
+    billingEmail?: string;
     idempotencyKey: string;
 } | {
     action: 'cancel' | 'undo_cancel';

package/dist/index.d.ts

@@ -1162,9 +1162,9 @@ interface ProviderDefinition {
  *
  * Returned by {@link DeeplineClient.listTools} and ranked tool search. Use
  * `getTool(toolId)` or the matching HTTP describe route for provider-specific
- * schema, examples, pricing, and extraction guidance before executing.
+ * schema, examples, pricing, extraction guidance, and execution metadata.
  */
-interface ToolDefinition {
+interface ToolDefinition extends ToolExecutionMetadataFields {
     /** Unique tool identifier used in API calls (e.g. `"dropleads_search_people"`). */
     toolId: string;
     /** Provider that backs this tool (e.g. `"hunter"`, `"dropleads"`, `"test"`). */
@@ -1299,6 +1299,42 @@ interface ToolDefinition {
     /** Actionable message shown when a connection is required. */
     connectionMessage?: string;
 }
+type ToolBatchCapability = {
+    status: 'compiled' | 'exposed_uncompiled' | 'upstream_only';
+    surface: 'registry' | 'local' | 'docs';
+    batchKind: 'identifier_batch' | 'query_share' | 'async_dataset_job';
+    batchOperation: string | null;
+    maxBatchSize: number | null;
+    notes: string;
+};
+/** Optional batching, pacing, and configured rate metadata for tool catalog entries. */
+interface ToolExecutionMetadataFields {
+    batchCapability?: ToolBatchCapability;
+    batch_capability?: ToolBatchCapability;
+    executionMetadata?: ToolExecutionMetadata;
+    execution_metadata?: ToolExecutionMetadata;
+}
+type ToolExecutionMetadata = {
+    provider: string;
+    sourceOperation: string;
+    effectiveOperation: string;
+    batch: {
+        batchOperation: string | null;
+        maxBatchSize: number;
+    };
+    configuredRateLimits: Array<{
+        source: 'deepline_configuration';
+        scope: string;
+        requestsPerWindow: number;
+        windowMs: number;
+        usage: 'queue_hint' | 'enforced' | 'queue_hint_and_enforced' | 'disabled';
+        explicitMaxConcurrency: number | null;
+    }>;
+    queueHint: {
+        requestsPerSecondHint: number;
+        derivedConcurrency: number;
+    };
+};
 interface ModelProviderOptionField {
     name: string;
     type: 'string' | 'number' | 'boolean' | 'object' | 'array';
@@ -1655,6 +1691,11 @@ interface PlayRunPackage {
         startedAt?: number | null;
         finishedAt?: number | null;
         durationMs?: number | null;
+        outcome?: PlayRunOutcome;
+        recovery?: {
+            mode: 'replayed' | 'forced' | 'recovered' | 'joined';
+            sourceRunId?: string;
+        };
         error?: string;
         /** Canonical explanation of what this run is doing or waiting on. */
         activity?: PlayRunActivityProjection | null;
@@ -1699,6 +1740,11 @@ interface PlayRunPackage {
         logs?: PlayRunActionPackage;
     };
 }
+/**
+ * Stable classification of whether this run executed work or reused/recovered
+ * an existing durable run outcome.
+ */
+type PlayRunOutcome = 'executed' | 'reused' | 'joined' | 'recovered' | 'forced' | 'waiting' | 'failed';
 /**
  * Current status of a play execution, returned by {@link DeeplineClient.getPlayStatus}.
  *
@@ -1730,6 +1776,12 @@ interface PlayStatus {
     dashboardUrl?: string;
     /** Product-level play-run state. */
     status: 'queued' | 'running' | 'waiting' | 'completed' | 'failed' | 'cancelled';
+    /** How this run was admitted or recovered, when the server can prove it. */
+    outcome?: PlayRunOutcome;
+    recovery?: {
+        mode: 'replayed' | 'forced' | 'recovered' | 'joined';
+        sourceRunId?: string;
+    };
     /** Execution progress with logs and error details. */
     progress?: PlayProgressStatus;
     /** Partial or final result. Available once the play returns. */
@@ -4102,6 +4154,20 @@ type TargetBillingStatusResult = {
     legacy_changes_allowed?: boolean;
     payment_state: string;
     recharge_state: string;
+    billing_email?: string | null;
+    collection_method?: 'charge_automatically' | 'send_invoice';
+    payment_access_policy?: 'payment_required' | 'net_30' | 'net_60';
+    plan_invoice?: {
+        url: string | null;
+        amount_usd: number;
+        due_at: string | null;
+        status: string | null;
+    } | null;
+    outstanding_invoice?: {
+        amount_usd: number;
+        due_at: string;
+        state: 'open' | 'cancelling';
+    } | null;
     next_action: string | null;
     pending_plan_sku: string | null;
     /** Saved transition boundary; optional for older servers. */
@@ -4144,6 +4210,7 @@ type TargetBillingMutationResult = {
 type TargetBillingPlanTransitionOptions = {
     action: 'start_or_change';
     targetPlanSku: 'payg-v1' | 'builder-v1' | 'growth-v1' | 'growth-canary-v1' | 'team-v1';
+    billingEmail?: string;
     idempotencyKey: string;
 } | {
     action: 'cancel' | 'undo_cancel';

package/dist/index.js

@@ -864,7 +864,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
@@ -7304,6 +7304,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 },