deepline 0.3.235 → 0.3.237

package/dist/cli/index.mjs

@@ -3449,7 +3449,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.235",
+  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
@@ -4128,6 +4128,15 @@ function describeRequestTarget(path) {
   }
   return "Deepline";
 }
+function networkDiagnosticUrl(value) {
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "https:" && url.protocol !== "http:") return void 0;
+    return `${url.origin}${url.pathname}`;
+  } catch {
+    return void 0;
+  }
+}
 function providerLabelFromToolId(toolId) {
   const normalized = toolId.trim().toLowerCase();
   const provider = normalized.split(/[_:./-]+/)[0];
@@ -4228,6 +4237,10 @@ var HttpClient = class {
     const baseUrl = this.config.baseUrl;
     const url = `${baseUrl}${path}`;
     const method = options?.method ?? "GET";
+    const requestStartedAt = Date.now();
+    let fetchAttempts = 0;
+    let lastRequestUrl = url;
+    let networkFailedAt;
     const headers = this.authHeaders(options?.headers);
     if (options?.body !== void 0) {
       headers["Content-Type"] = "application/json";
@@ -4239,6 +4252,7 @@ var HttpClient = class {
     requestAttempts: for (let attempt = 0; attempt <= maxRetries; attempt++) {
       if (options?.signal?.aborted) {
         lastError = requestCancelledError(options.signal);
+        networkFailedAt = Date.now();
         break;
       }
       if (attempt > 0) {
@@ -4249,12 +4263,14 @@ var HttpClient = class {
           await sleep(delayMs, options?.signal);
         } catch (error) {
           lastError = error instanceof Error ? error : new Error(String(error));
+          networkFailedAt = Date.now();
           break;
         }
       }
       for (const candidateUrl of candidateUrls) {
         if (options?.signal?.aborted) {
           lastError = requestCancelledError(options.signal);
+          networkFailedAt = Date.now();
           break requestAttempts;
         }
         const controller = new AbortController();
@@ -4269,10 +4285,13 @@ var HttpClient = class {
           once: true
         });
         try {
+          const requestBody = options?.formData !== void 0 ? typeof options.formData === "function" ? options.formData() : options.formData : options?.body !== void 0 ? JSON.stringify(options.body) : void 0;
+          fetchAttempts += 1;
+          lastRequestUrl = candidateUrl;
           const response = await fetch(candidateUrl, {
             method,
             headers,
-            body: options?.formData !== void 0 ? typeof options.formData === "function" ? options.formData() : options.formData : options?.body !== void 0 ? JSON.stringify(options.body) : void 0,
+            body: requestBody,
             signal: controller.signal
           });
           options?.onResponse?.(response);
@@ -4376,6 +4395,7 @@ var HttpClient = class {
           return parsed;
         } catch (error) {
           clearTimeout(timeoutId);
+          networkFailedAt = Date.now();
           if (options?.signal?.aborted) {
             lastError = requestCancelledError(options.signal);
             break requestAttempts;
@@ -4406,6 +4426,19 @@ var HttpClient = class {
       lastError,
       describeRequestTarget(path)
     );
+    const failedAt = networkFailedAt ?? Date.now();
+    const diagnosticUrl = networkDiagnosticUrl(lastRequestUrl);
+    const networkDetails = {
+      ...mappedNetworkError.details,
+      request: {
+        method,
+        ...diagnosticUrl === void 0 ? {} : { url: diagnosticUrl },
+        failedAtUtc: new Date(failedAt).toISOString(),
+        // Elapsed time covers the entire logical request, including retries.
+        elapsedMs: Math.max(0, failedAt - requestStartedAt),
+        attempts: fetchAttempts
+      }
+    };
     if (options?.toolId) {
       const code = mappedNetworkError.code;
       throw withErrorCause(
@@ -4426,7 +4459,7 @@ var HttpClient = class {
             retryAfterMs: null,
             networkKind: code === "NETWORK_TIMEOUT" ? "timeout" : code === "NETWORK_ABORTED" ? "unknown" : "unavailable",
             networkScope: "client_to_deepline",
-            details: mappedNetworkError.details,
+            details: networkDetails,
             publicDetails: options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : null
           }
         ),
@@ -4438,7 +4471,7 @@ var HttpClient = class {
         withCoworkNetworkHint(mappedNetworkError.message),
         void 0,
         mappedNetworkError.code,
-        mappedNetworkError.details
+        networkDetails
       ),
       lastError
     );
@@ -12873,9 +12906,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,
@@ -13072,6 +13109,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)"}`,
@@ -13080,8 +13118,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."
@@ -13161,7 +13201,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)
@@ -13188,7 +13234,11 @@ async function exportLedger(http, outputPath, options) {
     const rows = entries.map(ledgerApiEntryToRow);
     await 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) {
@@ -13988,6 +14038,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:
@@ -13997,6 +14049,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
@@ -14018,6 +14074,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
@@ -14030,6 +14088,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
@@ -29981,7 +30042,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) {
@@ -32414,11 +32491,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
 `
@@ -49976,11 +50057,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
@@ -49999,12 +50086,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
     };
   }
 };
@@ -50017,6 +50100,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) {
@@ -50610,11 +50700,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(
@@ -50740,6 +50834,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
@@ -50789,10 +50884,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
@@ -50896,6 +50996,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),
@@ -50913,23 +51045,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);
@@ -50970,11 +51085,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);
@@ -51033,6 +51153,7 @@ function toolContractJsonForDescribe(tool, requestedToolId) {
     toolId,
     provider: tool.provider,
     displayName: tool.displayName,
+    cost: pricing,
     description: tool.description,
     categories: tool.categories,
     ...deprecated ? {
@@ -51052,7 +51173,6 @@ function toolContractJsonForDescribe(tool, requestedToolId) {
     } : {},
     ...executionMetadata ? { executionMetadata } : {},
     ...batchCapability ? { batchCapability } : {},
-    cost: pricing,
     getters: {
       extractedLists,
       extractedValues
@@ -51128,7 +51248,7 @@ function printMonitorTypeStreams(tool) {
     console.log(`- ${name}: ${cols.join(", ")}`);
   }
 }
-function printMonitorTypePricing(tool) {
+function monitorTypePricingLines(tool) {
   const pricing = recordField2(tool, "pricing");
   const byType = recordField2(
     pricing,
@@ -51137,17 +51257,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");
@@ -51285,13 +51408,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");
@@ -51301,8 +51423,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)) {
@@ -51515,6 +51643,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,
@@ -51526,7 +51655,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.",

package/dist/index.d.mts

@@ -4738,6 +4738,8 @@ type BillingRecentUsageEntry = {
     outcome: string | null;
     billing_note: string | null;
     charge_state: 'posted' | 'temporary_hold' | 'hold_release' | 'pending' | 'free' | 'failed';
+    /** Final billing truth may be unknown even after execution completes. */
+    charge_finality?: 'final' | 'pending' | 'unknown';
     rough_usd_cost: number | null;
     created_at: string;
 };
@@ -4767,6 +4769,10 @@ type BillingUsageResult = {
         run_id: string | null;
         request_id?: string;
         total: number;
+        /** Only true when total covers the complete matching history. */
+        total_is_exact?: boolean;
+        /** Proven matching entries, without assuming unscanned rows match. */
+        total_lower_bound?: number;
         offset: number;
         limit: number;
         next_offset: number;

package/dist/index.d.ts

@@ -4738,6 +4738,8 @@ type BillingRecentUsageEntry = {
     outcome: string | null;
     billing_note: string | null;
     charge_state: 'posted' | 'temporary_hold' | 'hold_release' | 'pending' | 'free' | 'failed';
+    /** Final billing truth may be unknown even after execution completes. */
+    charge_finality?: 'final' | 'pending' | 'unknown';
     rough_usd_cost: number | null;
     created_at: string;
 };
@@ -4767,6 +4769,10 @@ type BillingUsageResult = {
         run_id: string | null;
         request_id?: string;
         total: number;
+        /** Only true when total covers the complete matching history. */
+        total_is_exact?: boolean;
+        /** Proven matching entries, without assuming unscanned rows match. */
+        total_lower_bound?: number;
         offset: number;
         limit: number;
         next_offset: number;