deepline 0.3.236 → 0.3.237

package/dist/cli/index.js

@@ -3454,7 +3454,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.236",
+  version: "0.3.237",
   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
@@ -12899,9 +12899,13 @@ function recentUsageLines(entries) {
   for (const entry of entries) {
     const op = `${humanize(entry.provider)} ${humanize(entry.operation)}`.trim();
     const roughUsd = Number(entry.rough_usd_cost);
-    const usdText = entry.charge_state !== "pending" && entry.rough_usd_cost !== null && entry.rough_usd_cost !== void 0 && Number.isFinite(roughUsd) ? ` (\u2248$${roughUsd.toFixed(2)})` : "";
-    const charge = entry.billing_mode === "no_bill" ? "free" : entry.charge_state === "temporary_hold" ? `${entry.credits ?? 0} cr held${usdText}, not final` : entry.charge_state === "pending" ? "final Deepline charge pending" : `${entry.credits ?? 0} cr${usdText}`;
-    const state = entry.charge_state === "temporary_hold" ? "temporary hold, final charge pending" : entry.charge_state === "pending" ? "no final charge recorded yet" : entry.status || "completed";
+    const credits = entry.credits !== null && entry.credits !== void 0 && String(entry.credits).trim().length > 0 && Number.isFinite(Number(entry.credits)) ? Number(entry.credits) : null;
+    const temporaryHold = entry.charge_state === "temporary_hold";
+    const pending = entry.charge_state === "pending" || entry.charge_finality === "pending";
+    const unknown = entry.charge_finality === "unknown" || credits === null;
+    const usdText = !pending && !unknown && entry.rough_usd_cost !== null && entry.rough_usd_cost !== void 0 && Number.isFinite(roughUsd) ? ` (\u2248$${roughUsd.toFixed(2)})` : "";
+    const charge = temporaryHold ? `${credits === null ? "unknown amount" : `${credits} cr`} held${usdText}, not final` : pending ? "final Deepline charge pending" : unknown ? "charge unknown" : entry.billing_mode === "no_bill" ? "free" : credits === 0 && (entry.charge_finality === "final" || entry.charge_state === "hold_release") ? "0 cr, final" : `${credits} cr${usdText}`;
+    const state = temporaryHold ? "temporary hold, final charge pending" : pending ? "no final charge recorded yet" : entry.status || "unknown";
     const auditBits = [
       entry.outcome ? `outcome=${entry.outcome}` : null,
       entry.pricing_basis ? `priced_by=${entry.pricing_basis}` : null,
@@ -13098,6 +13102,7 @@ async function handleUsage(options) {
   const recentLines = recentUsageLines(
     Array.isArray(recent.entries) ? recent.entries : []
   );
+  const matchingActivity = typeof recent.total === "number" && Number.isFinite(recent.total) && recent.total >= 0 && typeof recent.total_is_exact === "boolean" ? recent.total_is_exact ? `Matching activity: ${recent.total}` : typeof recent.total_lower_bound === "number" && Number.isFinite(recent.total_lower_bound) && recent.total_lower_bound >= 0 ? `Matching activity: at least ${recent.total_lower_bound}` : `Matching activity: count not exact (reported ${recent.total})` : null;
   const lines = options.requestId ? [`Charge lookup: ${options.requestId}`, ...recentLines] : [
     `Balance: ${payload.balance ?? "(unknown)"}`,
     `Last 30 days usage: ${last30Usage ?? "(unknown)"}`,
@@ -13106,8 +13111,10 @@ async function handleUsage(options) {
     ...options.runId && recent.run_id ? [
       `Run spend: ${(payload.run ?? {}).spent_credits ?? "(unknown)"} Deepline Credits`
     ] : [],
+    ...matchingActivity ? [matchingActivity] : [],
     ...recentLines,
-    ...recent.has_more === true || recent.incomplete === true ? ["List truncated \u2014 more recent calls match this query."] : [],
+    ...recent.has_more === true ? ["More activity pages are available."] : [],
+    ...recent.incomplete === true ? ["Recent activity is incomplete; the matching count may be higher."] : [],
     ...nextPage ? [`Next page: ${nextPage}`] : [],
     ...!nextPage && (recent.has_more === true || recent.incomplete === true) ? [
       "No continuation is available for this view. Use deepline billing ledger export all --json for the full ledger."
@@ -13187,7 +13194,13 @@ async function handleLimitOff(options) {
 async function exportLedger(http, outputPath, options) {
   let summary = { row_count: 0, net_delta_credits: 0 };
   let initialized = false;
+  let pageNumber = 0;
+  console.error(`Exporting billing ledger to ${outputPath}`);
   for await (const entries of iterateCursorPages(async (cursor) => {
+    pageNumber += 1;
+    console.error(
+      `Fetching page ${pageNumber}; ${summary.row_count} rows written.`
+    );
     const params = new URLSearchParams({ limit: "5000" });
     if (cursor) params.set("cursor", cursor);
     if (options.sinceAt !== null)
@@ -13214,7 +13227,11 @@ async function exportLedger(http, outputPath, options) {
     const rows = entries.map(ledgerApiEntryToRow);
     await (0, import_promises2.appendFile)(outputPath, ledgerRowsToCsv(rows, false), "utf-8");
     summary = summarizeLedgerRows(summary, rows);
+    console.error(
+      `Wrote page ${pageNumber}; ${summary.row_count} rows written.`
+    );
   }
+  console.error(`Export complete: ${summary.row_count} rows written.`);
   return summary;
 }
 async function handleHistory(options) {
@@ -14014,6 +14031,8 @@ function registerBillingCommands(program) {
     `
 Concepts:
   Billing commands show Deepline credits, not raw provider spend.
+  Balance is shared by the workspace; concurrent work changes it. Use a job_id
+  charge lookup to attribute one tool command instead of comparing balances.
   checkout/subscribe/redeem-code can open a browser unless --no-open is set.
 
 Examples:
@@ -14023,6 +14042,10 @@ Examples:
   deepline billing plans --json
   deepline billing subscription status --json
 
+  # Price a tool before execution; look up its exact charge afterward
+  deepline tools describe <tool-id> --pricing-only
+  deepline billing usage --request-id <job_id> --json
+
   # Buy credits or a plan
   deepline billing top-up 1000 --json
   deepline billing checkout --credits 1000 --no-open --json
@@ -14044,6 +14067,8 @@ Examples:
     `
 Notes:
   Read-only. Shows the current Deepline credit balance for the active workspace.
+  The balance includes concurrent workspace activity, so a before/after difference
+  cannot isolate one command. Use billing usage --request-id <job_id> --json.
 
 Examples:
   deepline billing balance
@@ -14056,6 +14081,9 @@ Examples:
 Notes:
   Read-only. Shows last-30-day Deepline credit usage plus a bounded recent-call
   page. Use --limit/--cursor to paginate the recent-call section.
+  For one tool command, use the job_id returned by tools execute, or its next.billing
+  command. Pending charges and temporary holds are not final spend; unknown means
+  final charge evidence is unavailable. Workspace balance changes include other work.
 
 Examples:
   deepline billing usage
@@ -29941,7 +29969,23 @@ async function handleRunsList(args) {
     }
   }
   if (!playName && !statusFilter) {
-    console.error(usage);
+    const message = "runs list requires --play or --status.";
+    const next = {
+      discover: "deepline plays list --json",
+      running: "deepline runs list --status running --json"
+    };
+    console.error(
+      `${message}
+${usage}
+Discover Plays: ${next.discover}
+Active runs: ${next.running}`
+    );
+    if (argsWantJson(args)) {
+      printCommandEnvelope(
+        { ok: false, exitCode: 1, code: "RUN_FILTER_REQUIRED", message, next },
+        { json: true }
+      );
+    }
     return 1;
   }
   if ((offset ?? 0) > 0 && !playName) {
@@ -32374,11 +32418,15 @@ Examples:
     "after",
     `
 Notes:
+  Requires --play or --status. Discover Play references with deepline plays list --json.
   Bounded inventory for a play's recent runs. Use --compact for agent loops.
+  Use the exact qualified Play reference, such as workspace/my-play or prebuilt/my-play.
+  --offset requires --play; narrow status-only lists with a Play reference to paginate.
   Common statuses include running, completed, failed, and stopped.
 
 Examples:
   deepline runs list --play my-play
+  deepline runs list --play workspace/my-play --json
   deepline runs list --play my-play --status failed --compact --json
   deepline runs list --status running --compact --json
 `
@@ -49856,11 +49904,17 @@ var CapabilityDescription = class _CapabilityDescription {
       legacyCost.pricingModel ?? legacyCost.pricing_model
     );
     const pricingModel = unit === "call" ? "fixed" : unit === "result" || unit === "page" ? `per_${unit}` : unit === "usage" ? "provider_usage" : legacyPricingModel;
-    const canonicalCredits = numberValue(
-      pricing.creditsPerUnit ?? pricing.credits_per_unit
-    );
-    const canonicalUsd = numberValue(
-      pricing.usdPerUnit ?? pricing.usd_per_unit
+    const canonicalCredits = pricingNumber(
+      pricing,
+      "creditsPerUnit",
+      "credits_per_unit",
+      this.#catalogEntry.deeplineCreditsPerPricingUnit ?? this.#catalogEntry.deepline_credits_per_pricing_unit
+    );
+    const canonicalUsd = pricingNumber(
+      pricing,
+      "usdPerUnit",
+      "usd_per_unit",
+      this.#catalogEntry.deeplineUsdPerPricingUnit ?? this.#catalogEntry.deepline_usd_per_pricing_unit
     );
     const billingSource = stringValue4(
       this.#catalogEntry.billingSource ?? this.#catalogEntry.billing_source
@@ -49879,12 +49933,8 @@ var CapabilityDescription = class _CapabilityDescription {
       ),
       billingSource,
       billingSourceLabel,
-      deeplineCreditsPerPricingUnit: isFree ? 0 : canonicalCredits ?? numberValue(
-        this.#catalogEntry.deeplineCreditsPerPricingUnit ?? this.#catalogEntry.deepline_credits_per_pricing_unit
-      ),
-      deeplineUsdPerPricingUnit: isFree ? 0 : canonicalUsd ?? numberValue(
-        this.#catalogEntry.deeplineUsdPerPricingUnit ?? this.#catalogEntry.deepline_usd_per_pricing_unit
-      )
+      deeplineCreditsPerPricingUnit: isFree ? 0 : canonicalCredits,
+      deeplineUsdPerPricingUnit: isFree ? 0 : canonicalUsd
     };
   }
 };
@@ -49897,6 +49947,13 @@ function stringValue4(value) {
 function numberValue(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
+function pricingNumber(pricing, canonicalKey, aliasKey, legacyValue) {
+  for (const key of [canonicalKey, aliasKey]) {
+    if (Object.prototype.hasOwnProperty.call(pricing, key))
+      return numberValue(pricing[key]);
+  }
+  return numberValue(legacyValue);
+}
 
 // src/cli/tool-connection-status.ts
 function toolConnectionStatusMessage(input2) {
@@ -50490,11 +50547,15 @@ Concepts:
 Common commands:
   deepline tools search email --json
   deepline tools describe hunter_email_verifier --json
+  deepline tools describe hunter_email_verifier --pricing-only --json
   deepline tools execute hunter_email_verifier --input '{"email":"a@b.com"}'
+  deepline billing usage --request-id <job_id> --json
 
 Output:
   Use describe for tool contracts.
   Use execute to run a tool.
+  Read pricing before execution; use the returned next.billing command for its
+  exact charge. Workspace balance changes also include other callers' activity.
 `
   );
   tools.command("list [category]").description("Browse tool categories, or list every tool in a category.").addHelpText(
@@ -50620,6 +50681,7 @@ Notes:
 Examples:
   deepline tools describe hunter_email_verifier
   deepline tools describe hunter_email_verifier --pricing-only
+  deepline tools describe hunter_email_verifier --pricing-only --json
   deepline tools describe hunter_email_verifier --schema-only
   deepline tools describe hunter_email_verifier --examples-only
   deepline tools describe hunter_email_verifier --json
@@ -50669,10 +50731,15 @@ Notes:
   waterfalls, row maps, checkpoints, and retries.
   Calling a provider-backed tool can spend Deepline credits. Use --json for the
   stable result payload plus output preview and debugging helpers.
+  Read pricing first with tools describe <toolId> --pricing-only --json.
+  Use the returned next.billing command to look up this execution's exact charge;
+  workspace balance changes also include other callers' activity.
   --timeout sets this CLI request's HTTP deadline; it does not cancel provider work.
 
 Examples:
   deepline tools execute hunter_email_verifier --input '{"email":"a@b.com"}'
+  deepline tools describe hunter_email_verifier --pricing-only --json
+  deepline billing usage --request-id <job_id> --json
   deepline tools execute bounceban_verify_bulk --input @batch.json --timeout 10m --json
   deepline tools execute hunter_email_verifier -p email=a@b.com
   deepline tools execute test_rate_limit --input '{"key":"smoke"}' --timeout 90s --json
@@ -50776,6 +50843,38 @@ async function getTool(toolId, options = {}) {
     );
     return 2;
   }
+  const onlyModes = [
+    options.pricingOnly,
+    options.schemaOnly,
+    options.examplesOnly,
+    options.gettersOnly
+  ].filter(Boolean).length;
+  if (onlyModes > 1) {
+    console.error(
+      "Use only one of --pricing-only, --schema-only, --examples-only, or --getters-only."
+    );
+    return 2;
+  }
+  if (options.pricingOnly) {
+    const lines = toolPricingOnlyLines(tool, toolId);
+    if (inferenceQuote)
+      lines.push(...inferenceQuoteSummaryLines(inferenceQuote));
+    printCommandEnvelope(
+      {
+        toolId: String(tool.toolId || toolId),
+        cost: Capability.fromCatalogEntry(tool).describe().customerCost(),
+        ...modelDescription ? { modelOptions: modelDescription } : {},
+        ...isMonitorTypeTool(tool) ? { pricing: recordField2(tool, "pricing") } : {},
+        ...inferenceQuote ? { inferenceQuote } : {}
+      },
+      {
+        json: Boolean(options.json || options.contractJson),
+        text: `${lines.join("\n")}
+`
+      }
+    );
+    return 0;
+  }
   if (options.contractJson) {
     printCompactJson({
       ...toolContractJsonForDescribe(tool, toolId),
@@ -50793,23 +50892,6 @@ async function getTool(toolId, options = {}) {
     });
     return 0;
   }
-  const onlyModes = [
-    options.pricingOnly,
-    options.schemaOnly,
-    options.examplesOnly,
-    options.gettersOnly
-  ].filter(Boolean).length;
-  if (onlyModes > 1) {
-    console.error(
-      "Use only one of --pricing-only, --schema-only, --examples-only, or --getters-only."
-    );
-    return 2;
-  }
-  if (options.pricingOnly) {
-    printToolPricingOnly(tool, toolId);
-    if (inferenceQuote) printInferenceQuoteSummary(inferenceQuote);
-    return 0;
-  }
   if (options.schemaOnly) {
     printToolSchemaOnly(tool, toolId);
     if (inferenceQuote) printInferenceQuoteSummary(inferenceQuote);
@@ -50850,11 +50932,16 @@ ${formatModelDescription(modelDescription)}`);
   if (inferenceQuote) printInferenceQuoteSummary(inferenceQuote);
   return 0;
 }
-function printInferenceQuoteSummary(_quote) {
-  console.log("");
-  console.log("Inference quote:");
-  console.log("- Temporary hold: priced estimate (minimum 0.02 credits)");
-  console.log("- Final charge: actual usage");
+function inferenceQuoteSummaryLines(_quote) {
+  return [
+    "",
+    "Inference quote:",
+    "- Temporary hold: priced estimate (minimum 0.02 credits)",
+    "- Final charge: actual usage"
+  ];
+}
+function printInferenceQuoteSummary(quote) {
+  for (const line of inferenceQuoteSummaryLines(quote)) console.log(line);
 }
 function toolContractJsonForDescribe(tool, requestedToolId) {
   const toolId = String(tool.toolId || requestedToolId);
@@ -50913,6 +51000,7 @@ function toolContractJsonForDescribe(tool, requestedToolId) {
     toolId,
     provider: tool.provider,
     displayName: tool.displayName,
+    cost: pricing,
     description: tool.description,
     categories: tool.categories,
     ...deprecated ? {
@@ -50932,7 +51020,6 @@ function toolContractJsonForDescribe(tool, requestedToolId) {
     } : {},
     ...executionMetadata ? { executionMetadata } : {},
     ...batchCapability ? { batchCapability } : {},
-    cost: pricing,
     getters: {
       extractedLists,
       extractedValues
@@ -51008,7 +51095,7 @@ function printMonitorTypeStreams(tool) {
     console.log(`- ${name}: ${cols.join(", ")}`);
   }
 }
-function printMonitorTypePricing(tool) {
+function monitorTypePricingLines(tool) {
   const pricing = recordField2(tool, "pricing");
   const byType = recordField2(
     pricing,
@@ -51017,17 +51104,20 @@ function printMonitorTypePricing(tool) {
   );
   const keys = Object.keys(byType);
   if (!keys.length) {
-    console.log("Pricing: Deepline credits per accepted event (see --json)");
-    return;
+    return ["Pricing: Deepline credits per accepted event (see --json)"];
   }
-  console.log("Pricing (Deepline credits per accepted event):");
+  const lines = ["Pricing (Deepline credits per accepted event):"];
   for (const key of keys) {
     const entry = isRecord13(byType[key]) ? byType[key] : {};
     const credits = numberField2(entry, "deepline_credits", "deeplineCredits");
     const display = stringField2(entry, "display");
     const shown = display || (credits !== null ? `${formatDecimal(credits)} credits/event` : "see --json");
-    console.log(`- ${key}: ${shown}`);
+    lines.push(`- ${key}: ${shown}`);
   }
+  return lines;
+}
+function printMonitorTypePricing(tool) {
+  for (const line of monitorTypePricingLines(tool)) console.log(line);
 }
 function printMonitorTypeDeploy(tool) {
   const deploy = recordField2(tool, "deploy");
@@ -51165,13 +51255,12 @@ function printCompactToolContract(tool, requestedToolId) {
     `More: deepline tools describe ${contract.toolId} --pricing-only | --schema-only | --examples-only | --getters-only | --json`
   );
 }
-function printToolPricingOnly(tool, requestedToolId, options = {}) {
+function toolPricingOnlyLines(tool, requestedToolId, options = {}) {
   if (isMonitorTypeTool(tool)) {
-    printMonitorTypePricing(tool);
-    return;
+    return monitorTypePricingLines(tool);
   }
-  const contract = toolContractJsonForDescribe(tool, requestedToolId);
-  const cost = isRecord13(contract.cost) ? contract.cost : {};
+  const toolId = String(tool.toolId || requestedToolId);
+  const cost = Capability.fromCatalogEntry(tool).describe().customerCost();
   const pricingModel = stringField2(cost, "pricingModel") || "unknown";
   const billing = stringField2(cost, "billingSourceLabel") || stringField2(cost, "billingSource") || stringField2(cost, "billingMode") || "unknown";
   const explicitUnit = stringField2(cost, "unit");
@@ -51181,8 +51270,14 @@ function printToolPricingOnly(tool, requestedToolId, options = {}) {
   const displayText = stringField2(cost, "displayText");
   const summary = stringField2(cost, "summary");
   const price = displayText || summary || (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: ${billing}`);
+  return [
+    `${options.heading ?? `Pricing: ${toolId}`}: ${price}`,
+    `Billing: ${billing}`
+  ];
+}
+function printToolPricingOnly(tool, requestedToolId, options = {}) {
+  for (const line of toolPricingOnlyLines(tool, requestedToolId, options))
+    console.log(line);
 }
 function printToolSchemaOnly(tool, requestedToolId) {
   if (isMonitorTypeTool(tool)) {
@@ -51395,6 +51490,7 @@ function toolMetadataJsonForDescribe(tool, requestedToolId) {
   } = tool;
   const outputSchemaRecord = recordField2(tool, "outputSchema", "output_schema");
   return {
+    cost: Capability.fromCatalogEntry(tool).describe().customerCost(),
     ...publicTool,
     toolId,
     provider: tool.provider,
@@ -51406,7 +51502,6 @@ function toolMetadataJsonForDescribe(tool, requestedToolId) {
       )
     } : {},
     inputFields: inputFields.map(inputFieldJsonForDescribe),
-    cost: Capability.fromCatalogEntry(tool).describe().customerCost(),
     usageGuidance,
     runtimeOutputHelp: {
       contract: "tools describe shows declared schema and Deepline getters; it is not an observed provider response.",