deepline 0.3.162 → 0.3.164

package/dist/bundling-sources/sdk/src/client.ts

@@ -2117,9 +2117,79 @@ export type BillingUsageEvent = {
   created_at: string;
 };
 
+/** One customer-facing recent billing operation from `/api/v2/billing/usage`. */
+export type BillingRecentUsageEntry = {
+  id: string;
+  provider: string;
+  operation: string;
+  status: string;
+  request_id: string;
+  run_id: string | null;
+  /** Play execution run for this charge, when the call ran inside a Play. */
+  play_run_id?: string | null;
+  workflow_id?: string | null;
+  billing_run_id?: string | null;
+  execution_run_id?: string | null;
+  included_in_run_id?: string | null;
+  billing_scope?: string | null;
+  step_block_id?: string | null;
+  step_alias?: string | null;
+  credits: number;
+  billing_mode: string | null;
+  pricing_model: string | null;
+  outcome: string | null;
+  billing_note: string | null;
+  charge_state:
+    | 'posted'
+    | 'temporary_hold'
+    | 'hold_release'
+    | 'pending'
+    | 'free'
+    | 'failed';
+  rough_usd_cost: number | null;
+  created_at: string;
+};
+
+export type BillingUsageOptions = {
+  /** Return the one exact call identified by `executeTool().job_id`. */
+  requestId?: string;
+  /** Bound the recent-call page. Ignored for an exact requestId lookup. */
+  limit?: number;
+  offset?: number;
+  cursor?: string;
+  runId?: string;
+};
+
+export type BillingUsageResult = {
+  org_id: string;
+  balance?: number;
+  rough_usd_balance?: number;
+  plan?: { usd_per_credit: number };
+  usage?: {
+    last_30_days_usage_credits: number;
+    rough_usd_last_30_days_usage: number;
+    temporary_hold_credits: number;
+    rough_usd_temporary_holds: number;
+  };
+  recent: {
+    run_id: string | null;
+    request_id?: string;
+    total: number;
+    offset: number;
+    limit: number;
+    next_offset: number;
+    next_cursor: string | null;
+    has_more: boolean;
+    incomplete: boolean;
+    entries: BillingRecentUsageEntry[];
+  };
+  [key: string]: unknown;
+};
+
 /**
  * Public `client.billing` namespace for CLI commands and programmatic callers.
- * Covers plans, subscription state, cancellation, and invoice/receipt history.
+ * Covers usage, plans, subscription state, cancellation, and invoice/receipt
+ * history.
  *
  * @sdkReference client 030 client.billing
  */
@@ -2148,6 +2218,8 @@ export type BillingNamespace = {
   };
   /** Read one exact execution outcome using the request_id returned by executeTool. */
   usageEvent: (requestId: string) => Promise<BillingUsageEvent>;
+  /** Read current billing usage, or look up one exact execution charge by request ID. */
+  usage: (options?: BillingUsageOptions) => Promise<BillingUsageResult>;
   /** Metronome-authored target catalog and current Contract projection. */
   targetPlans: () => Promise<TargetBillingPlansResult>;
   /** Normalized target billing state. */
@@ -2760,6 +2832,7 @@ export class DeeplineClient {
         list: (options) => this.listBillingInvoices(options),
       },
       usageEvent: (requestId) => this.getBillingUsageEvent(requestId),
+      usage: (options) => this.getBillingUsage(options),
       targetPlans: () => this.getTargetBillingPlans(),
       targetStatus: () => this.getTargetBillingStatus(),
       autoRecharge: {
@@ -6194,6 +6267,60 @@ export class DeeplineClient {
     return event;
   }
 
+  /**
+   * Read workspace usage and recent customer-facing Deepline charges. Pass
+   * the `job_id` from `executeTool` as `requestId` to retrieve one exact call,
+   * including whether its charge is final or still a temporary hold. Exact
+   * request lookups return only the `org_id` and `recent` result fields.
+   */
+  async getBillingUsage(
+    options: BillingUsageOptions = {},
+  ): Promise<BillingUsageResult> {
+    const params = new URLSearchParams();
+    if (options.requestId !== undefined) {
+      const requestId = options.requestId.trim();
+      if (
+        requestId.length === 0 ||
+        requestId.length > 200 ||
+        requestId !== options.requestId
+      ) {
+        throw new DeeplineError(
+          'Usage request_id must contain 1–200 characters with no leading or trailing whitespace.',
+          undefined,
+          'INVALID_USAGE_REQUEST_ID',
+        );
+      }
+      if (
+        options.runId !== undefined ||
+        options.cursor !== undefined ||
+        options.offset !== undefined
+      ) {
+        throw new DeeplineError(
+          'requestId cannot be combined with runId, cursor, or offset.',
+          undefined,
+          'INVALID_USAGE_FILTERS',
+        );
+      }
+      params.set('request_id', requestId);
+    } else {
+      if (options.limit !== undefined) {
+        params.set('recent_limit', String(options.limit));
+      }
+      if (options.offset !== undefined) {
+        params.set('recent_offset', String(options.offset));
+      }
+      if (options.cursor !== undefined) {
+        params.set('recent_cursor', options.cursor);
+      }
+      if (options.runId !== undefined) {
+        params.set('run_id', options.runId);
+      }
+    }
+    const serializedParams = params.toString();
+    const query = serializedParams ? `?${serializedParams}` : '';
+    return this.http.get<BillingUsageResult>(`/api/v2/billing/usage${query}`);
+  }
+
   /**
    * Charge the saved payment method and add Deepline credits to the active
    * workspace. Prefer `client.billing.topUp(...)`.

package/dist/bundling-sources/sdk/src/index.ts

@@ -68,12 +68,15 @@ export type {
   BillingInvoiceEntry,
   BillingInvoicesResult,
   BillingNamespace,
+  BillingRecentUsageEntry,
   DbNamespace,
   BillingPaymentMethodSummary,
   BillingSubscriptionCancelResult,
   BillingSubscriptionStatus,
   BillingTopUpResult,
   BillingUsageEvent,
+  BillingUsageOptions,
+  BillingUsageResult,
   WorkspaceCreateResult,
   WorkspacesNamespace,
   MonitorsNamespace,

package/dist/bundling-sources/sdk/src/play.ts

@@ -110,6 +110,7 @@ import type {
   ToolMetadata,
 } from './types.js';
 import type {
+  BillingNamespace,
   ExecutionByKeyResult,
   ExecutionRecovery,
   ToolExecution,
@@ -1064,6 +1065,7 @@ function createNamedPlayHandle<
  * // Tools
  * const tools = await deepline.tools.list();
  * const result = await deepline.tools.execute('test_company_search', { domain: 'stripe.com' });
+ * const charge = await deepline.billing.usage({ requestId: result.job_id });
  *
  * // Plays
  * const job = await deepline.play('email-waterfall').run({ domain: 'stripe.com' });
@@ -1075,6 +1077,11 @@ function createNamedPlayHandle<
 export class DeeplineContext {
   private readonly client: DeeplineClient;
 
+  /** Read current billing usage and exact per-request Deepline charges. */
+  get billing(): BillingNamespace {
+    return this.client.billing;
+  }
+
   /**
    * Create a high-level SDK context.
    *

package/dist/bundling-sources/sdk/src/release.ts

@@ -200,7 +200,7 @@ export const 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.162',
+  version: '0.3.164',
   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: {

package/dist/bundling-sources/shared_libs/observability/dlq.ts

@@ -585,6 +585,7 @@ export function normalizeQueueItemState(nativeState: string): QueueItemState {
     state === 'open' ||
     state === 'pending' ||
     state === 'queued' ||
+    state === 'continuation_pending' ||
     state === 'active' ||
     state === 'received' ||
     state === 'partial'

package/dist/bundling-sources/shared_libs/observability/scheduled-work-control.ts

@@ -0,0 +1,156 @@
+/**
+ * Owner-neutral control port for cataloged scheduled work.
+ *
+ * The shared operations surface routes by stable job id. Scheduler adapters
+ * own authorization details and durable execution; callers never invoke a
+ * GitHub workflow, Vercel route, Inngest function, or Convex root directly.
+ */
+export const SCHEDULED_WORK_CONTROL_CONTRACT_VERSION = 1 as const;
+
+export type ScheduledWorkControlAction = 'run';
+
+export type ScheduledWorkControlContext = {
+  readonly jobId: string;
+  readonly environment: string;
+  readonly requestedByUserId: string;
+  readonly requestedByEmail: string;
+  readonly reason: string;
+  readonly idempotencyKey: string;
+};
+
+export type ScheduledWorkRunResult = {
+  readonly operationId: string;
+  readonly status: 'queued' | 'running' | 'succeeded' | 'failed';
+  readonly replayed: boolean;
+};
+
+export type ScheduledWorkControlConnector = {
+  readonly id: string;
+  /** Stable implementation identity, such as `convex_cron` or `github_actions`. */
+  readonly scheduler: string;
+  readonly jobIds: readonly string[];
+  readonly actions: readonly ScheduledWorkControlAction[];
+  /** Registered owners may expose an honest read-only adapter before a safe
+   * mutation exists. These reasons are returned by the same capability API. */
+  readonly unavailableActions?: Partial<
+    Record<ScheduledWorkControlAction, string>
+  >;
+  run?: (
+    context: ScheduledWorkControlContext,
+  ) => Promise<ScheduledWorkRunResult>;
+};
+
+export type ScheduledWorkControlRegisterOptions = {
+  /** Permit replacing an explicitly read-only startup adapter with its owner. */
+  readonly replaceUnavailable?: boolean;
+};
+
+export type ScheduledWorkControlCapability =
+  | {
+      readonly available: true;
+      readonly action: ScheduledWorkControlAction;
+      readonly connectorId: string;
+      readonly scheduler: string;
+    }
+  | {
+      readonly available: false;
+      readonly action: ScheduledWorkControlAction;
+      readonly reason: string;
+    };
+
+/**
+ * Dispatch boundary shared by all scheduled-work implementations. Duplicate
+ * job ownership is a startup error so one scheduler cannot shadow another.
+ */
+export class ScheduledWorkControlRegistry {
+  private readonly connectorsByJobId = new Map<
+    string,
+    ScheduledWorkControlConnector
+  >();
+
+  register(
+    connector: ScheduledWorkControlConnector,
+    options: ScheduledWorkControlRegisterOptions = {},
+  ): this {
+    if (!connector.id.trim())
+      throw new Error('Scheduled-work connector id is required.');
+    if (!connector.scheduler.trim())
+      throw new Error('Scheduled-work connector scheduler is required.');
+    if (connector.jobIds.length === 0)
+      throw new Error(
+        `Scheduled-work connector ${connector.id} must own at least one job.`,
+      );
+    if (
+      connector.actions.includes('run') &&
+      typeof connector.run !== 'function'
+    ) {
+      throw new Error(
+        `Scheduled-work connector ${connector.id} declares run without an implementation.`,
+      );
+    }
+    if (
+      connector.actions.length === 0 &&
+      Object.keys(connector.unavailableActions ?? {}).length === 0
+    ) {
+      throw new Error(
+        `Scheduled-work connector ${connector.id} must declare a supported action or an explicit unavailable reason.`,
+      );
+    }
+    const jobIds = new Set<string>();
+    for (const jobId of connector.jobIds) {
+      if (!jobId.trim())
+        throw new Error(
+          `Scheduled-work connector ${connector.id} has an empty job id.`,
+        );
+      if (jobIds.has(jobId))
+        throw new Error(
+          `Scheduled-work connector ${connector.id} repeats job ${jobId}.`,
+        );
+      jobIds.add(jobId);
+      const existing = this.connectorsByJobId.get(jobId);
+      if (existing && !options.replaceUnavailable) {
+        throw new Error(
+          `Scheduled-work job ${jobId} is already owned by ${existing.id}.`,
+        );
+      }
+      if (
+        existing &&
+        options.replaceUnavailable &&
+        existing.actions.length > 0
+      ) {
+        throw new Error(
+          `Scheduled-work job ${jobId} is already owned by ${existing.id}; replacement is not allowed.`,
+        );
+      }
+    }
+    for (const jobId of jobIds) this.connectorsByJobId.set(jobId, connector);
+    return this;
+  }
+
+  get(jobId: string): ScheduledWorkControlConnector | undefined {
+    return this.connectorsByJobId.get(jobId);
+  }
+
+  capability(
+    jobId: string,
+    action: ScheduledWorkControlAction = 'run',
+  ): ScheduledWorkControlCapability {
+    const connector = this.get(jobId);
+    if (connector?.actions.includes(action)) {
+      return {
+        available: true,
+        action,
+        connectorId: connector.id,
+        scheduler: connector.scheduler,
+      };
+    }
+    return {
+      available: false,
+      action,
+      reason: connector
+        ? (connector.unavailableActions?.[action] ??
+          `Scheduler connector ${connector.id} does not support ${action}.`)
+        : `No shared control connector is registered for scheduler work ${jobId}.`,
+    };
+  }
+}

package/dist/cli/index.js

@@ -3051,7 +3051,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.162",
+  version: "0.3.164",
   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
@@ -7156,6 +7156,7 @@ var DeeplineClient = class _DeeplineClient {
         list: (options2) => this.listBillingInvoices(options2)
       },
       usageEvent: (requestId) => this.getBillingUsageEvent(requestId),
+      usage: (options2) => this.getBillingUsage(options2),
       targetPlans: () => this.getTargetBillingPlans(),
       targetStatus: () => this.getTargetBillingStatus(),
       autoRecharge: {
@@ -9710,6 +9711,49 @@ var DeeplineClient = class _DeeplineClient {
     }
     return event;
   }
+  /**
+   * Read workspace usage and recent customer-facing Deepline charges. Pass
+   * the `job_id` from `executeTool` as `requestId` to retrieve one exact call,
+   * including whether its charge is final or still a temporary hold. Exact
+   * request lookups return only the `org_id` and `recent` result fields.
+   */
+  async getBillingUsage(options = {}) {
+    const params = new URLSearchParams();
+    if (options.requestId !== void 0) {
+      const requestId = options.requestId.trim();
+      if (requestId.length === 0 || requestId.length > 200 || requestId !== options.requestId) {
+        throw new DeeplineError(
+          "Usage request_id must contain 1\u2013200 characters with no leading or trailing whitespace.",
+          void 0,
+          "INVALID_USAGE_REQUEST_ID"
+        );
+      }
+      if (options.runId !== void 0 || options.cursor !== void 0 || options.offset !== void 0) {
+        throw new DeeplineError(
+          "requestId cannot be combined with runId, cursor, or offset.",
+          void 0,
+          "INVALID_USAGE_FILTERS"
+        );
+      }
+      params.set("request_id", requestId);
+    } else {
+      if (options.limit !== void 0) {
+        params.set("recent_limit", String(options.limit));
+      }
+      if (options.offset !== void 0) {
+        params.set("recent_offset", String(options.offset));
+      }
+      if (options.cursor !== void 0) {
+        params.set("recent_cursor", options.cursor);
+      }
+      if (options.runId !== void 0) {
+        params.set("run_id", options.runId);
+      }
+    }
+    const serializedParams = params.toString();
+    const query = serializedParams ? `?${serializedParams}` : "";
+    return this.http.get(`/api/v2/billing/usage${query}`);
+  }
   /**
    * Charge the saved payment method and add Deepline credits to the active
    * workspace. Prefer `client.billing.topUp(...)`.
@@ -12454,12 +12498,18 @@ function recentUsageLines(entries) {
   const lines = ["Recent activity:"];
   for (const entry of entries) {
     const op = `${humanize(entry.provider)} ${humanize(entry.operation)}`.trim();
-    const charge = entry.billing_mode === "no_bill" ? "free" : `${entry.credits ?? 0} cr`;
-    const state = entry.charge_state === "temporary_hold" ? "temporary hold, awaiting actual usage" : entry.status || "completed";
+    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 auditBits = [
       entry.outcome ? `outcome=${entry.outcome}` : null,
       entry.pricing_basis ? `priced_by=${entry.pricing_basis}` : null,
       entry.run_id ? `run=${entry.run_id}` : null,
+      entry.play_run_id || entry.execution_run_id ? `play_run=${entry.play_run_id ?? entry.execution_run_id}` : null,
+      entry.billing_run_id ? `billing_run=${entry.billing_run_id}` : null,
+      entry.workflow_id ? `workflow=${entry.workflow_id}` : null,
+      entry.step_alias ? `step=${entry.step_alias}` : null,
       entry.request_id ? `request=${entry.request_id}` : null
     ].filter(Boolean);
     lines.push(
@@ -12587,21 +12637,68 @@ function quoteShellArgument(value) {
 async function handleUsage(options) {
   const { http } = getAuthedHttpClient();
   const params = new URLSearchParams();
-  if (options.limit) params.set("recent_limit", options.limit);
-  if (options.offset) params.set("recent_offset", options.offset);
-  if (options.cursor) params.set("recent_cursor", options.cursor);
-  if (options.runId) params.set("run_id", options.runId);
+  if (options.requestId !== void 0) {
+    const requestId = options.requestId.trim();
+    if (requestId.length === 0 || requestId.length > 200 || requestId !== options.requestId) {
+      reportBillingFailure(
+        {
+          exitCode: 2,
+          code: "INVALID_REQUEST_ID",
+          message: "--request-id must contain 1\u2013200 characters with no leading or trailing whitespace."
+        },
+        options
+      );
+      return;
+    }
+    if (options.offset || options.cursor || options.runId) {
+      reportBillingFailure(
+        {
+          exitCode: 2,
+          code: "CONFLICTING_USAGE_FILTERS",
+          message: "--request-id cannot be combined with --offset, --cursor, or --run-id."
+        },
+        options
+      );
+      return;
+    }
+    params.set("request_id", requestId);
+  } else {
+    if (options.limit) params.set("recent_limit", options.limit);
+    if (options.offset) params.set("recent_offset", options.offset);
+    if (options.cursor) params.set("recent_cursor", options.cursor);
+    if (options.runId) params.set("run_id", options.runId);
+  }
   const suffix = Array.from(params).length > 0 ? `?${params.toString()}` : "";
-  const payload = await http.get(
-    `/api/v2/billing/usage${suffix}`
-  );
+  let payload;
+  try {
+    payload = await http.get(
+      `/api/v2/billing/usage${suffix}`
+    );
+  } catch (error) {
+    if (options.requestId && error instanceof DeeplineError && error.statusCode === 404) {
+      reportBillingFailure(
+        {
+          exitCode: 4,
+          code: "USAGE_REQUEST_NOT_FOUND",
+          message: `No billing record for request_id ${options.requestId} in the active workspace.`,
+          next: "deepline billing usage --json"
+        },
+        options
+      );
+      return;
+    }
+    throw error;
+  }
   const usage = payload.usage ?? {};
   const quota = payload.quota ?? {};
   const recent = payload.recent ?? {};
   const last30Usage = usage.last_30_days_usage_credits ?? usage.month_spent_credits;
   const temporaryHolds = Number(usage.temporary_hold_credits ?? 0);
   const nextPage = typeof recent.next_cursor === "string" && recent.next_cursor.length > 0 ? `deepline billing usage --cursor ${quoteShellArgument(recent.next_cursor)}${options.limit ? ` --limit ${options.limit}` : ""}${options.runId ? ` --run-id ${quoteShellArgument(options.runId)}` : ""} --json` : null;
-  const lines = [
+  const recentLines = recentUsageLines(
+    Array.isArray(recent.entries) ? recent.entries : []
+  );
+  const lines = options.requestId ? [`Charge lookup: ${options.requestId}`, ...recentLines] : [
     `Balance: ${payload.balance ?? "(unknown)"}`,
     `Last 30 days usage: ${last30Usage ?? "(unknown)"}`,
     ...Number.isFinite(temporaryHolds) && temporaryHolds > 0 ? [`Temporary holds: ${temporaryHolds}`] : [],
@@ -12609,9 +12706,7 @@ async function handleUsage(options) {
     ...options.runId && recent.run_id ? [
       `Run spend: ${(payload.run ?? {}).spent_credits ?? "(unknown)"} Deepline Credits`
     ] : [],
-    ...recentUsageLines(
-      Array.isArray(recent.entries) ? recent.entries : []
-    ),
+    ...recentLines,
     ...recent.has_more === true || recent.incomplete === true ? ["List truncated \u2014 more recent calls match this query."] : [],
     ...nextPage ? [`Next page: ${nextPage}`] : [],
     ...!nextPage && (recent.has_more === true || recent.incomplete === true) ? [
@@ -13518,11 +13613,15 @@ Examples:
   deepline billing usage
   deepline billing usage --limit 50 --cursor <next_cursor> --json
   deepline billing usage --run-id play/example/run/20260630t120000-000-abcdef --json
+  deepline billing usage --request-id <job_id> --json
 `
   ).option("--limit <n>", "Recent-call page size").option("--offset <n>", "Recent-call offset").option(
     "--cursor <cursor>",
     "Recent-call cursor from the previous response"
-  ).option("--run-id <run_id>", "Show recent usage for one play run").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleUsage);
+  ).option("--run-id <run_id>", "Show recent usage for one play run").option(
+    "--request-id <job_id>",
+    "Show the exact Deepline charge for one execution job_id"
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleUsage);
   billing.command("limit").description("Show configured monthly usage cap.").addHelpText(
     "after",
     `

package/dist/cli/index.mjs

@@ -3046,7 +3046,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.162",
+  version: "0.3.164",
   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
@@ -7151,6 +7151,7 @@ var DeeplineClient = class _DeeplineClient {
         list: (options2) => this.listBillingInvoices(options2)
       },
       usageEvent: (requestId) => this.getBillingUsageEvent(requestId),
+      usage: (options2) => this.getBillingUsage(options2),
       targetPlans: () => this.getTargetBillingPlans(),
       targetStatus: () => this.getTargetBillingStatus(),
       autoRecharge: {
@@ -9705,6 +9706,49 @@ var DeeplineClient = class _DeeplineClient {
     }
     return event;
   }
+  /**
+   * Read workspace usage and recent customer-facing Deepline charges. Pass
+   * the `job_id` from `executeTool` as `requestId` to retrieve one exact call,
+   * including whether its charge is final or still a temporary hold. Exact
+   * request lookups return only the `org_id` and `recent` result fields.
+   */
+  async getBillingUsage(options = {}) {
+    const params = new URLSearchParams();
+    if (options.requestId !== void 0) {
+      const requestId = options.requestId.trim();
+      if (requestId.length === 0 || requestId.length > 200 || requestId !== options.requestId) {
+        throw new DeeplineError(
+          "Usage request_id must contain 1\u2013200 characters with no leading or trailing whitespace.",
+          void 0,
+          "INVALID_USAGE_REQUEST_ID"
+        );
+      }
+      if (options.runId !== void 0 || options.cursor !== void 0 || options.offset !== void 0) {
+        throw new DeeplineError(
+          "requestId cannot be combined with runId, cursor, or offset.",
+          void 0,
+          "INVALID_USAGE_FILTERS"
+        );
+      }
+      params.set("request_id", requestId);
+    } else {
+      if (options.limit !== void 0) {
+        params.set("recent_limit", String(options.limit));
+      }
+      if (options.offset !== void 0) {
+        params.set("recent_offset", String(options.offset));
+      }
+      if (options.cursor !== void 0) {
+        params.set("recent_cursor", options.cursor);
+      }
+      if (options.runId !== void 0) {
+        params.set("run_id", options.runId);
+      }
+    }
+    const serializedParams = params.toString();
+    const query = serializedParams ? `?${serializedParams}` : "";
+    return this.http.get(`/api/v2/billing/usage${query}`);
+  }
   /**
    * Charge the saved payment method and add Deepline credits to the active
    * workspace. Prefer `client.billing.topUp(...)`.
@@ -12461,12 +12505,18 @@ function recentUsageLines(entries) {
   const lines = ["Recent activity:"];
   for (const entry of entries) {
     const op = `${humanize(entry.provider)} ${humanize(entry.operation)}`.trim();
-    const charge = entry.billing_mode === "no_bill" ? "free" : `${entry.credits ?? 0} cr`;
-    const state = entry.charge_state === "temporary_hold" ? "temporary hold, awaiting actual usage" : entry.status || "completed";
+    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 auditBits = [
       entry.outcome ? `outcome=${entry.outcome}` : null,
       entry.pricing_basis ? `priced_by=${entry.pricing_basis}` : null,
       entry.run_id ? `run=${entry.run_id}` : null,
+      entry.play_run_id || entry.execution_run_id ? `play_run=${entry.play_run_id ?? entry.execution_run_id}` : null,
+      entry.billing_run_id ? `billing_run=${entry.billing_run_id}` : null,
+      entry.workflow_id ? `workflow=${entry.workflow_id}` : null,
+      entry.step_alias ? `step=${entry.step_alias}` : null,
       entry.request_id ? `request=${entry.request_id}` : null
     ].filter(Boolean);
     lines.push(
@@ -12594,21 +12644,68 @@ function quoteShellArgument(value) {
 async function handleUsage(options) {
   const { http } = getAuthedHttpClient();
   const params = new URLSearchParams();
-  if (options.limit) params.set("recent_limit", options.limit);
-  if (options.offset) params.set("recent_offset", options.offset);
-  if (options.cursor) params.set("recent_cursor", options.cursor);
-  if (options.runId) params.set("run_id", options.runId);
+  if (options.requestId !== void 0) {
+    const requestId = options.requestId.trim();
+    if (requestId.length === 0 || requestId.length > 200 || requestId !== options.requestId) {
+      reportBillingFailure(
+        {
+          exitCode: 2,
+          code: "INVALID_REQUEST_ID",
+          message: "--request-id must contain 1\u2013200 characters with no leading or trailing whitespace."
+        },
+        options
+      );
+      return;
+    }
+    if (options.offset || options.cursor || options.runId) {
+      reportBillingFailure(
+        {
+          exitCode: 2,
+          code: "CONFLICTING_USAGE_FILTERS",
+          message: "--request-id cannot be combined with --offset, --cursor, or --run-id."
+        },
+        options
+      );
+      return;
+    }
+    params.set("request_id", requestId);
+  } else {
+    if (options.limit) params.set("recent_limit", options.limit);
+    if (options.offset) params.set("recent_offset", options.offset);
+    if (options.cursor) params.set("recent_cursor", options.cursor);
+    if (options.runId) params.set("run_id", options.runId);
+  }
   const suffix = Array.from(params).length > 0 ? `?${params.toString()}` : "";
-  const payload = await http.get(
-    `/api/v2/billing/usage${suffix}`
-  );
+  let payload;
+  try {
+    payload = await http.get(
+      `/api/v2/billing/usage${suffix}`
+    );
+  } catch (error) {
+    if (options.requestId && error instanceof DeeplineError && error.statusCode === 404) {
+      reportBillingFailure(
+        {
+          exitCode: 4,
+          code: "USAGE_REQUEST_NOT_FOUND",
+          message: `No billing record for request_id ${options.requestId} in the active workspace.`,
+          next: "deepline billing usage --json"
+        },
+        options
+      );
+      return;
+    }
+    throw error;
+  }
   const usage = payload.usage ?? {};
   const quota = payload.quota ?? {};
   const recent = payload.recent ?? {};
   const last30Usage = usage.last_30_days_usage_credits ?? usage.month_spent_credits;
   const temporaryHolds = Number(usage.temporary_hold_credits ?? 0);
   const nextPage = typeof recent.next_cursor === "string" && recent.next_cursor.length > 0 ? `deepline billing usage --cursor ${quoteShellArgument(recent.next_cursor)}${options.limit ? ` --limit ${options.limit}` : ""}${options.runId ? ` --run-id ${quoteShellArgument(options.runId)}` : ""} --json` : null;
-  const lines = [
+  const recentLines = recentUsageLines(
+    Array.isArray(recent.entries) ? recent.entries : []
+  );
+  const lines = options.requestId ? [`Charge lookup: ${options.requestId}`, ...recentLines] : [
     `Balance: ${payload.balance ?? "(unknown)"}`,
     `Last 30 days usage: ${last30Usage ?? "(unknown)"}`,
     ...Number.isFinite(temporaryHolds) && temporaryHolds > 0 ? [`Temporary holds: ${temporaryHolds}`] : [],
@@ -12616,9 +12713,7 @@ async function handleUsage(options) {
     ...options.runId && recent.run_id ? [
       `Run spend: ${(payload.run ?? {}).spent_credits ?? "(unknown)"} Deepline Credits`
     ] : [],
-    ...recentUsageLines(
-      Array.isArray(recent.entries) ? recent.entries : []
-    ),
+    ...recentLines,
     ...recent.has_more === true || recent.incomplete === true ? ["List truncated \u2014 more recent calls match this query."] : [],
     ...nextPage ? [`Next page: ${nextPage}`] : [],
     ...!nextPage && (recent.has_more === true || recent.incomplete === true) ? [
@@ -13525,11 +13620,15 @@ Examples:
   deepline billing usage
   deepline billing usage --limit 50 --cursor <next_cursor> --json
   deepline billing usage --run-id play/example/run/20260630t120000-000-abcdef --json
+  deepline billing usage --request-id <job_id> --json
 `
   ).option("--limit <n>", "Recent-call page size").option("--offset <n>", "Recent-call offset").option(
     "--cursor <cursor>",
     "Recent-call cursor from the previous response"
-  ).option("--run-id <run_id>", "Show recent usage for one play run").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleUsage);
+  ).option("--run-id <run_id>", "Show recent usage for one play run").option(
+    "--request-id <job_id>",
+    "Show the exact Deepline charge for one execution job_id"
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(handleUsage);
   billing.command("limit").description("Show configured monthly usage cap.").addHelpText(
     "after",
     `

package/dist/index.d.mts

@@ -4323,9 +4323,72 @@ type BillingUsageEvent = {
     policy_id: string | null;
     created_at: string;
 };
+/** One customer-facing recent billing operation from `/api/v2/billing/usage`. */
+type BillingRecentUsageEntry = {
+    id: string;
+    provider: string;
+    operation: string;
+    status: string;
+    request_id: string;
+    run_id: string | null;
+    /** Play execution run for this charge, when the call ran inside a Play. */
+    play_run_id?: string | null;
+    workflow_id?: string | null;
+    billing_run_id?: string | null;
+    execution_run_id?: string | null;
+    included_in_run_id?: string | null;
+    billing_scope?: string | null;
+    step_block_id?: string | null;
+    step_alias?: string | null;
+    credits: number;
+    billing_mode: string | null;
+    pricing_model: string | null;
+    outcome: string | null;
+    billing_note: string | null;
+    charge_state: 'posted' | 'temporary_hold' | 'hold_release' | 'pending' | 'free' | 'failed';
+    rough_usd_cost: number | null;
+    created_at: string;
+};
+type BillingUsageOptions = {
+    /** Return the one exact call identified by `executeTool().job_id`. */
+    requestId?: string;
+    /** Bound the recent-call page. Ignored for an exact requestId lookup. */
+    limit?: number;
+    offset?: number;
+    cursor?: string;
+    runId?: string;
+};
+type BillingUsageResult = {
+    org_id: string;
+    balance?: number;
+    rough_usd_balance?: number;
+    plan?: {
+        usd_per_credit: number;
+    };
+    usage?: {
+        last_30_days_usage_credits: number;
+        rough_usd_last_30_days_usage: number;
+        temporary_hold_credits: number;
+        rough_usd_temporary_holds: number;
+    };
+    recent: {
+        run_id: string | null;
+        request_id?: string;
+        total: number;
+        offset: number;
+        limit: number;
+        next_offset: number;
+        next_cursor: string | null;
+        has_more: boolean;
+        incomplete: boolean;
+        entries: BillingRecentUsageEntry[];
+    };
+    [key: string]: unknown;
+};
 /**
  * Public `client.billing` namespace for CLI commands and programmatic callers.
- * Covers plans, subscription state, cancellation, and invoice/receipt history.
+ * Covers usage, plans, subscription state, cancellation, and invoice/receipt
+ * history.
  *
  * @sdkReference client 030 client.billing
  */
@@ -4356,6 +4419,8 @@ type BillingNamespace = {
     };
     /** Read one exact execution outcome using the request_id returned by executeTool. */
     usageEvent: (requestId: string) => Promise<BillingUsageEvent>;
+    /** Read current billing usage, or look up one exact execution charge by request ID. */
+    usage: (options?: BillingUsageOptions) => Promise<BillingUsageResult>;
     /** Metronome-authored target catalog and current Contract projection. */
     targetPlans: () => Promise<TargetBillingPlansResult>;
     /** Normalized target billing state. */
@@ -5433,6 +5498,13 @@ declare class DeeplineClient {
      * retry or idempotency token.
      */
     getBillingUsageEvent(requestId: string): Promise<BillingUsageEvent>;
+    /**
+     * Read workspace usage and recent customer-facing Deepline charges. Pass
+     * the `job_id` from `executeTool` as `requestId` to retrieve one exact call,
+     * including whether its charge is final or still a temporary hold. Exact
+     * request lookups return only the `org_id` and `recent` result fields.
+     */
+    getBillingUsage(options?: BillingUsageOptions): Promise<BillingUsageResult>;
     /**
      * Charge the saved payment method and add Deepline credits to the active
      * workspace. Prefer `client.billing.topUp(...)`.
@@ -6129,6 +6201,7 @@ type PlayMetadata<TInput = Record<string, unknown>> = {
  * // Tools
  * const tools = await deepline.tools.list();
  * const result = await deepline.tools.execute('test_company_search', { domain: 'stripe.com' });
+ * const charge = await deepline.billing.usage({ requestId: result.job_id });
  *
  * // Plays
  * const job = await deepline.play('email-waterfall').run({ domain: 'stripe.com' });
@@ -6139,6 +6212,8 @@ type PlayMetadata<TInput = Record<string, unknown>> = {
  */
 declare class DeeplineContext {
     private readonly client;
+    /** Read current billing usage and exact per-request Deepline charges. */
+    get billing(): BillingNamespace;
     /**
      * Create a high-level SDK context.
      *
@@ -6655,4 +6730,4 @@ declare function writeCsvOutputFile(rows: Array<Record<string, unknown>>, stem:
  */
 declare function extractSummaryFields(payload: unknown): Record<string, Scalar>;
 
-export { type AsyncPlayRunRef, AuthError, type BillingCreditPool, type BillingInvoiceEntry, type BillingInvoicesResult, type BillingNamespace, type BillingPaymentMethodSummary, type BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type BillingTopUpResult, type BillingUsageEvent, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CreateNotificationGroupInput, type CreateNotificationGroupResult, type CsvInput, type CsvOptions, type CustomerDbQueryResult, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, type DatasetColumnDefinition, type DatasetColumnRunInput, type DbNamespace, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, DeeplineError, type DeeplineExecutionsNamespace, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolExecuteResult, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, type ExecutionByKeyResult, type ExecutionRecovery, type FetchOptions, type FileInput, type IngestionStorageRepairResult, type LegacyMonitorStatusFilter, type LiveEventEnvelope, MONITOR_JOB_PHASES, MONITOR_JOB_RECONCILIATION_STATES, MONITOR_JOB_STATES, type MonitorBatchNamespace, type MonitorCheckResult, type MonitorDefinition, type MonitorDeleteResult, type MonitorDependents, type MonitorDeployResult, type MonitorDetail, type MonitorFleetDeactivateOptions, MonitorFleetDefinition, type MonitorFleetGetOptions, type MonitorFleetReactivateOptions, type MonitorFleetResult, type MonitorFleetStatus, type MonitorFleetSyncOptions, type MonitorFleetWaitOptions, type MonitorFleetsNamespace, type MonitorJobDeployOptions, type MonitorJobLogsOptions, type MonitorJobPhase, type MonitorJobReconciliationState, type MonitorJobResult, type MonitorJobState, type MonitorJobWaitOptions, type MonitorJobsNamespace, type MonitorListEntry, type MonitorPayload, type MonitorReactivateResult, type MonitorSpec, type MonitorState, type MonitorStateFilter, type MonitorUpdateChangeSummary, type MonitorUpdateResult, type MonitorsAccessStatus, type MonitorsAvailableOptions, type MonitorsAvailableResult, type MonitorsListOptions, type MonitorsListResult, type MonitorsNamespace, PLAY_BOOTSTRAP_COMPANY_FIELDS, PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_CONTACT_FIELDS, PLAY_BOOTSTRAP_FINDER_KINDS, PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER, PLAY_BOOTSTRAP_PEOPLE_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_PROVIDER_CATEGORY_BY_FINDER, PLAY_BOOTSTRAP_SOURCE_KINDS, PLAY_BOOTSTRAP_STAGE_KINDS, PLAY_BOOTSTRAP_TEMPLATES, PROD_URL, type PlayActivityObservation, type PlayActivityState, type PlayActivityTarget, type PlayAsyncCallOptions, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayCallExecution, type PlayCallOptions, type PlayCostEstimate, type PlayFetchResponse, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayReferenceLike, type PlayRevisionSummary, type PlayRunActionPackage, type PlayRunActivityProjection, type PlayRunDatasetActions, type PlayRunId, type PlayRunPackage, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PlaysListOptions, type PlaysListPage, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type RerunOptions, type RerunPlayRunResult, type ResolvedConfig, RunObserveTransportUnavailableError, type RunsListOptions, type RunsListPage, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, type RuntimeStepOptions, SDK_API_CONTRACT, SDK_VERSION, type SqlListenerDeclaration, type SqlListenerEvent, type SqlListenerOperation, type SqlQuery, type StartPlayRunRequest, type StepOptions, type StepProgram, type StepProgramResolver, type StepResolver, type StopAllCandidate, type StopAllPlayRunsDryRunResult, type StopAllPlayRunsResult, type StopAllPlayRunsStopResult, type StopAllRunsOptions, type StopPlayRunResult, type ToolDefinition, ToolExecuteResult, type ToolExecution, ToolExecutionError, ToolExecutionErrorOptions, type ToolExecutionRequest, type ToolMetadata, ToolRateLimitError, ToolResultBilling, type ToolSearchOptions, type ToolSearchResult, type WorkspaceCreateResult, type WorkspacesNamespace, defineInput, defineMonitor, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, isStopAllPlayRunsDryRunResult, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };
+export { type AsyncPlayRunRef, AuthError, type BillingCreditPool, type BillingInvoiceEntry, type BillingInvoicesResult, type BillingNamespace, type BillingPaymentMethodSummary, type BillingRecentUsageEntry, type BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type BillingTopUpResult, type BillingUsageEvent, type BillingUsageOptions, type BillingUsageResult, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CreateNotificationGroupInput, type CreateNotificationGroupResult, type CsvInput, type CsvOptions, type CustomerDbQueryResult, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, type DatasetColumnDefinition, type DatasetColumnRunInput, type DbNamespace, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, DeeplineError, type DeeplineExecutionsNamespace, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolExecuteResult, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, type ExecutionByKeyResult, type ExecutionRecovery, type FetchOptions, type FileInput, type IngestionStorageRepairResult, type LegacyMonitorStatusFilter, type LiveEventEnvelope, MONITOR_JOB_PHASES, MONITOR_JOB_RECONCILIATION_STATES, MONITOR_JOB_STATES, type MonitorBatchNamespace, type MonitorCheckResult, type MonitorDefinition, type MonitorDeleteResult, type MonitorDependents, type MonitorDeployResult, type MonitorDetail, type MonitorFleetDeactivateOptions, MonitorFleetDefinition, type MonitorFleetGetOptions, type MonitorFleetReactivateOptions, type MonitorFleetResult, type MonitorFleetStatus, type MonitorFleetSyncOptions, type MonitorFleetWaitOptions, type MonitorFleetsNamespace, type MonitorJobDeployOptions, type MonitorJobLogsOptions, type MonitorJobPhase, type MonitorJobReconciliationState, type MonitorJobResult, type MonitorJobState, type MonitorJobWaitOptions, type MonitorJobsNamespace, type MonitorListEntry, type MonitorPayload, type MonitorReactivateResult, type MonitorSpec, type MonitorState, type MonitorStateFilter, type MonitorUpdateChangeSummary, type MonitorUpdateResult, type MonitorsAccessStatus, type MonitorsAvailableOptions, type MonitorsAvailableResult, type MonitorsListOptions, type MonitorsListResult, type MonitorsNamespace, PLAY_BOOTSTRAP_COMPANY_FIELDS, PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_CONTACT_FIELDS, PLAY_BOOTSTRAP_FINDER_KINDS, PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER, PLAY_BOOTSTRAP_PEOPLE_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_PROVIDER_CATEGORY_BY_FINDER, PLAY_BOOTSTRAP_SOURCE_KINDS, PLAY_BOOTSTRAP_STAGE_KINDS, PLAY_BOOTSTRAP_TEMPLATES, PROD_URL, type PlayActivityObservation, type PlayActivityState, type PlayActivityTarget, type PlayAsyncCallOptions, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayCallExecution, type PlayCallOptions, type PlayCostEstimate, type PlayFetchResponse, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayReferenceLike, type PlayRevisionSummary, type PlayRunActionPackage, type PlayRunActivityProjection, type PlayRunDatasetActions, type PlayRunId, type PlayRunPackage, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PlaysListOptions, type PlaysListPage, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type RerunOptions, type RerunPlayRunResult, type ResolvedConfig, RunObserveTransportUnavailableError, type RunsListOptions, type RunsListPage, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, type RuntimeStepOptions, SDK_API_CONTRACT, SDK_VERSION, type SqlListenerDeclaration, type SqlListenerEvent, type SqlListenerOperation, type SqlQuery, type StartPlayRunRequest, type StepOptions, type StepProgram, type StepProgramResolver, type StepResolver, type StopAllCandidate, type StopAllPlayRunsDryRunResult, type StopAllPlayRunsResult, type StopAllPlayRunsStopResult, type StopAllRunsOptions, type StopPlayRunResult, type ToolDefinition, ToolExecuteResult, type ToolExecution, ToolExecutionError, ToolExecutionErrorOptions, type ToolExecutionRequest, type ToolMetadata, ToolRateLimitError, ToolResultBilling, type ToolSearchOptions, type ToolSearchResult, type WorkspaceCreateResult, type WorkspacesNamespace, defineInput, defineMonitor, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, isStopAllPlayRunsDryRunResult, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };

package/dist/index.d.ts

@@ -4323,9 +4323,72 @@ type BillingUsageEvent = {
     policy_id: string | null;
     created_at: string;
 };
+/** One customer-facing recent billing operation from `/api/v2/billing/usage`. */
+type BillingRecentUsageEntry = {
+    id: string;
+    provider: string;
+    operation: string;
+    status: string;
+    request_id: string;
+    run_id: string | null;
+    /** Play execution run for this charge, when the call ran inside a Play. */
+    play_run_id?: string | null;
+    workflow_id?: string | null;
+    billing_run_id?: string | null;
+    execution_run_id?: string | null;
+    included_in_run_id?: string | null;
+    billing_scope?: string | null;
+    step_block_id?: string | null;
+    step_alias?: string | null;
+    credits: number;
+    billing_mode: string | null;
+    pricing_model: string | null;
+    outcome: string | null;
+    billing_note: string | null;
+    charge_state: 'posted' | 'temporary_hold' | 'hold_release' | 'pending' | 'free' | 'failed';
+    rough_usd_cost: number | null;
+    created_at: string;
+};
+type BillingUsageOptions = {
+    /** Return the one exact call identified by `executeTool().job_id`. */
+    requestId?: string;
+    /** Bound the recent-call page. Ignored for an exact requestId lookup. */
+    limit?: number;
+    offset?: number;
+    cursor?: string;
+    runId?: string;
+};
+type BillingUsageResult = {
+    org_id: string;
+    balance?: number;
+    rough_usd_balance?: number;
+    plan?: {
+        usd_per_credit: number;
+    };
+    usage?: {
+        last_30_days_usage_credits: number;
+        rough_usd_last_30_days_usage: number;
+        temporary_hold_credits: number;
+        rough_usd_temporary_holds: number;
+    };
+    recent: {
+        run_id: string | null;
+        request_id?: string;
+        total: number;
+        offset: number;
+        limit: number;
+        next_offset: number;
+        next_cursor: string | null;
+        has_more: boolean;
+        incomplete: boolean;
+        entries: BillingRecentUsageEntry[];
+    };
+    [key: string]: unknown;
+};
 /**
  * Public `client.billing` namespace for CLI commands and programmatic callers.
- * Covers plans, subscription state, cancellation, and invoice/receipt history.
+ * Covers usage, plans, subscription state, cancellation, and invoice/receipt
+ * history.
  *
  * @sdkReference client 030 client.billing
  */
@@ -4356,6 +4419,8 @@ type BillingNamespace = {
     };
     /** Read one exact execution outcome using the request_id returned by executeTool. */
     usageEvent: (requestId: string) => Promise<BillingUsageEvent>;
+    /** Read current billing usage, or look up one exact execution charge by request ID. */
+    usage: (options?: BillingUsageOptions) => Promise<BillingUsageResult>;
     /** Metronome-authored target catalog and current Contract projection. */
     targetPlans: () => Promise<TargetBillingPlansResult>;
     /** Normalized target billing state. */
@@ -5433,6 +5498,13 @@ declare class DeeplineClient {
      * retry or idempotency token.
      */
     getBillingUsageEvent(requestId: string): Promise<BillingUsageEvent>;
+    /**
+     * Read workspace usage and recent customer-facing Deepline charges. Pass
+     * the `job_id` from `executeTool` as `requestId` to retrieve one exact call,
+     * including whether its charge is final or still a temporary hold. Exact
+     * request lookups return only the `org_id` and `recent` result fields.
+     */
+    getBillingUsage(options?: BillingUsageOptions): Promise<BillingUsageResult>;
     /**
      * Charge the saved payment method and add Deepline credits to the active
      * workspace. Prefer `client.billing.topUp(...)`.
@@ -6129,6 +6201,7 @@ type PlayMetadata<TInput = Record<string, unknown>> = {
  * // Tools
  * const tools = await deepline.tools.list();
  * const result = await deepline.tools.execute('test_company_search', { domain: 'stripe.com' });
+ * const charge = await deepline.billing.usage({ requestId: result.job_id });
  *
  * // Plays
  * const job = await deepline.play('email-waterfall').run({ domain: 'stripe.com' });
@@ -6139,6 +6212,8 @@ type PlayMetadata<TInput = Record<string, unknown>> = {
  */
 declare class DeeplineContext {
     private readonly client;
+    /** Read current billing usage and exact per-request Deepline charges. */
+    get billing(): BillingNamespace;
     /**
      * Create a high-level SDK context.
      *
@@ -6655,4 +6730,4 @@ declare function writeCsvOutputFile(rows: Array<Record<string, unknown>>, stem:
  */
 declare function extractSummaryFields(payload: unknown): Record<string, Scalar>;
 
-export { type AsyncPlayRunRef, AuthError, type BillingCreditPool, type BillingInvoiceEntry, type BillingInvoicesResult, type BillingNamespace, type BillingPaymentMethodSummary, type BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type BillingTopUpResult, type BillingUsageEvent, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CreateNotificationGroupInput, type CreateNotificationGroupResult, type CsvInput, type CsvOptions, type CustomerDbQueryResult, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, type DatasetColumnDefinition, type DatasetColumnRunInput, type DbNamespace, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, DeeplineError, type DeeplineExecutionsNamespace, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolExecuteResult, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, type ExecutionByKeyResult, type ExecutionRecovery, type FetchOptions, type FileInput, type IngestionStorageRepairResult, type LegacyMonitorStatusFilter, type LiveEventEnvelope, MONITOR_JOB_PHASES, MONITOR_JOB_RECONCILIATION_STATES, MONITOR_JOB_STATES, type MonitorBatchNamespace, type MonitorCheckResult, type MonitorDefinition, type MonitorDeleteResult, type MonitorDependents, type MonitorDeployResult, type MonitorDetail, type MonitorFleetDeactivateOptions, MonitorFleetDefinition, type MonitorFleetGetOptions, type MonitorFleetReactivateOptions, type MonitorFleetResult, type MonitorFleetStatus, type MonitorFleetSyncOptions, type MonitorFleetWaitOptions, type MonitorFleetsNamespace, type MonitorJobDeployOptions, type MonitorJobLogsOptions, type MonitorJobPhase, type MonitorJobReconciliationState, type MonitorJobResult, type MonitorJobState, type MonitorJobWaitOptions, type MonitorJobsNamespace, type MonitorListEntry, type MonitorPayload, type MonitorReactivateResult, type MonitorSpec, type MonitorState, type MonitorStateFilter, type MonitorUpdateChangeSummary, type MonitorUpdateResult, type MonitorsAccessStatus, type MonitorsAvailableOptions, type MonitorsAvailableResult, type MonitorsListOptions, type MonitorsListResult, type MonitorsNamespace, PLAY_BOOTSTRAP_COMPANY_FIELDS, PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_CONTACT_FIELDS, PLAY_BOOTSTRAP_FINDER_KINDS, PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER, PLAY_BOOTSTRAP_PEOPLE_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_PROVIDER_CATEGORY_BY_FINDER, PLAY_BOOTSTRAP_SOURCE_KINDS, PLAY_BOOTSTRAP_STAGE_KINDS, PLAY_BOOTSTRAP_TEMPLATES, PROD_URL, type PlayActivityObservation, type PlayActivityState, type PlayActivityTarget, type PlayAsyncCallOptions, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayCallExecution, type PlayCallOptions, type PlayCostEstimate, type PlayFetchResponse, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayReferenceLike, type PlayRevisionSummary, type PlayRunActionPackage, type PlayRunActivityProjection, type PlayRunDatasetActions, type PlayRunId, type PlayRunPackage, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PlaysListOptions, type PlaysListPage, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type RerunOptions, type RerunPlayRunResult, type ResolvedConfig, RunObserveTransportUnavailableError, type RunsListOptions, type RunsListPage, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, type RuntimeStepOptions, SDK_API_CONTRACT, SDK_VERSION, type SqlListenerDeclaration, type SqlListenerEvent, type SqlListenerOperation, type SqlQuery, type StartPlayRunRequest, type StepOptions, type StepProgram, type StepProgramResolver, type StepResolver, type StopAllCandidate, type StopAllPlayRunsDryRunResult, type StopAllPlayRunsResult, type StopAllPlayRunsStopResult, type StopAllRunsOptions, type StopPlayRunResult, type ToolDefinition, ToolExecuteResult, type ToolExecution, ToolExecutionError, ToolExecutionErrorOptions, type ToolExecutionRequest, type ToolMetadata, ToolRateLimitError, ToolResultBilling, type ToolSearchOptions, type ToolSearchResult, type WorkspaceCreateResult, type WorkspacesNamespace, defineInput, defineMonitor, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, isStopAllPlayRunsDryRunResult, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };
+export { type AsyncPlayRunRef, AuthError, type BillingCreditPool, type BillingInvoiceEntry, type BillingInvoicesResult, type BillingNamespace, type BillingPaymentMethodSummary, type BillingRecentUsageEntry, type BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type BillingTopUpResult, type BillingUsageEvent, type BillingUsageOptions, type BillingUsageResult, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CreateNotificationGroupInput, type CreateNotificationGroupResult, type CsvInput, type CsvOptions, type CustomerDbQueryResult, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, type DatasetColumnDefinition, type DatasetColumnRunInput, type DbNamespace, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, DeeplineError, type DeeplineExecutionsNamespace, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolExecuteResult, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, type ExecutionByKeyResult, type ExecutionRecovery, type FetchOptions, type FileInput, type IngestionStorageRepairResult, type LegacyMonitorStatusFilter, type LiveEventEnvelope, MONITOR_JOB_PHASES, MONITOR_JOB_RECONCILIATION_STATES, MONITOR_JOB_STATES, type MonitorBatchNamespace, type MonitorCheckResult, type MonitorDefinition, type MonitorDeleteResult, type MonitorDependents, type MonitorDeployResult, type MonitorDetail, type MonitorFleetDeactivateOptions, MonitorFleetDefinition, type MonitorFleetGetOptions, type MonitorFleetReactivateOptions, type MonitorFleetResult, type MonitorFleetStatus, type MonitorFleetSyncOptions, type MonitorFleetWaitOptions, type MonitorFleetsNamespace, type MonitorJobDeployOptions, type MonitorJobLogsOptions, type MonitorJobPhase, type MonitorJobReconciliationState, type MonitorJobResult, type MonitorJobState, type MonitorJobWaitOptions, type MonitorJobsNamespace, type MonitorListEntry, type MonitorPayload, type MonitorReactivateResult, type MonitorSpec, type MonitorState, type MonitorStateFilter, type MonitorUpdateChangeSummary, type MonitorUpdateResult, type MonitorsAccessStatus, type MonitorsAvailableOptions, type MonitorsAvailableResult, type MonitorsListOptions, type MonitorsListResult, type MonitorsNamespace, PLAY_BOOTSTRAP_COMPANY_FIELDS, PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_CONTACT_FIELDS, PLAY_BOOTSTRAP_FINDER_KINDS, PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER, PLAY_BOOTSTRAP_PEOPLE_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_PROVIDER_CATEGORY_BY_FINDER, PLAY_BOOTSTRAP_SOURCE_KINDS, PLAY_BOOTSTRAP_STAGE_KINDS, PLAY_BOOTSTRAP_TEMPLATES, PROD_URL, type PlayActivityObservation, type PlayActivityState, type PlayActivityTarget, type PlayAsyncCallOptions, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayCallExecution, type PlayCallOptions, type PlayCostEstimate, type PlayFetchResponse, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayReferenceLike, type PlayRevisionSummary, type PlayRunActionPackage, type PlayRunActivityProjection, type PlayRunDatasetActions, type PlayRunId, type PlayRunPackage, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PlaysListOptions, type PlaysListPage, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type RerunOptions, type RerunPlayRunResult, type ResolvedConfig, RunObserveTransportUnavailableError, type RunsListOptions, type RunsListPage, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, type RuntimeStepOptions, SDK_API_CONTRACT, SDK_VERSION, type SqlListenerDeclaration, type SqlListenerEvent, type SqlListenerOperation, type SqlQuery, type StartPlayRunRequest, type StepOptions, type StepProgram, type StepProgramResolver, type StepResolver, type StopAllCandidate, type StopAllPlayRunsDryRunResult, type StopAllPlayRunsResult, type StopAllPlayRunsStopResult, type StopAllRunsOptions, type StopPlayRunResult, type ToolDefinition, ToolExecuteResult, type ToolExecution, ToolExecutionError, ToolExecutionErrorOptions, type ToolExecutionRequest, type ToolMetadata, ToolRateLimitError, ToolResultBilling, type ToolSearchOptions, type ToolSearchResult, type WorkspaceCreateResult, type WorkspacesNamespace, defineInput, defineMonitor, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, isStopAllPlayRunsDryRunResult, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };

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.162",
+  version: "0.3.164",
   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
@@ -4847,6 +4847,7 @@ var DeeplineClient = class _DeeplineClient {
         list: (options2) => this.listBillingInvoices(options2)
       },
       usageEvent: (requestId) => this.getBillingUsageEvent(requestId),
+      usage: (options2) => this.getBillingUsage(options2),
       targetPlans: () => this.getTargetBillingPlans(),
       targetStatus: () => this.getTargetBillingStatus(),
       autoRecharge: {
@@ -7401,6 +7402,49 @@ var DeeplineClient = class _DeeplineClient {
     }
     return event;
   }
+  /**
+   * Read workspace usage and recent customer-facing Deepline charges. Pass
+   * the `job_id` from `executeTool` as `requestId` to retrieve one exact call,
+   * including whether its charge is final or still a temporary hold. Exact
+   * request lookups return only the `org_id` and `recent` result fields.
+   */
+  async getBillingUsage(options = {}) {
+    const params = new URLSearchParams();
+    if (options.requestId !== void 0) {
+      const requestId = options.requestId.trim();
+      if (requestId.length === 0 || requestId.length > 200 || requestId !== options.requestId) {
+        throw new DeeplineError(
+          "Usage request_id must contain 1\u2013200 characters with no leading or trailing whitespace.",
+          void 0,
+          "INVALID_USAGE_REQUEST_ID"
+        );
+      }
+      if (options.runId !== void 0 || options.cursor !== void 0 || options.offset !== void 0) {
+        throw new DeeplineError(
+          "requestId cannot be combined with runId, cursor, or offset.",
+          void 0,
+          "INVALID_USAGE_FILTERS"
+        );
+      }
+      params.set("request_id", requestId);
+    } else {
+      if (options.limit !== void 0) {
+        params.set("recent_limit", String(options.limit));
+      }
+      if (options.offset !== void 0) {
+        params.set("recent_offset", String(options.offset));
+      }
+      if (options.cursor !== void 0) {
+        params.set("recent_cursor", options.cursor);
+      }
+      if (options.runId !== void 0) {
+        params.set("run_id", options.runId);
+      }
+    }
+    const serializedParams = params.toString();
+    const query = serializedParams ? `?${serializedParams}` : "";
+    return this.http.get(`/api/v2/billing/usage${query}`);
+  }
   /**
    * Charge the saved payment method and add Deepline credits to the active
    * workspace. Prefer `client.billing.topUp(...)`.
@@ -11465,6 +11509,10 @@ function createNamedPlayHandle(clientFactory, name) {
 }
 var DeeplineContext = class {
   client;
+  /** Read current billing usage and exact per-request Deepline charges. */
+  get billing() {
+    return this.client.billing;
+  }
   /**
    * Create a high-level SDK context.
    *

package/dist/index.mjs

@@ -768,7 +768,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.162",
+  version: "0.3.164",
   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
@@ -4751,6 +4751,7 @@ var DeeplineClient = class _DeeplineClient {
         list: (options2) => this.listBillingInvoices(options2)
       },
       usageEvent: (requestId) => this.getBillingUsageEvent(requestId),
+      usage: (options2) => this.getBillingUsage(options2),
       targetPlans: () => this.getTargetBillingPlans(),
       targetStatus: () => this.getTargetBillingStatus(),
       autoRecharge: {
@@ -7305,6 +7306,49 @@ var DeeplineClient = class _DeeplineClient {
     }
     return event;
   }
+  /**
+   * Read workspace usage and recent customer-facing Deepline charges. Pass
+   * the `job_id` from `executeTool` as `requestId` to retrieve one exact call,
+   * including whether its charge is final or still a temporary hold. Exact
+   * request lookups return only the `org_id` and `recent` result fields.
+   */
+  async getBillingUsage(options = {}) {
+    const params = new URLSearchParams();
+    if (options.requestId !== void 0) {
+      const requestId = options.requestId.trim();
+      if (requestId.length === 0 || requestId.length > 200 || requestId !== options.requestId) {
+        throw new DeeplineError(
+          "Usage request_id must contain 1\u2013200 characters with no leading or trailing whitespace.",
+          void 0,
+          "INVALID_USAGE_REQUEST_ID"
+        );
+      }
+      if (options.runId !== void 0 || options.cursor !== void 0 || options.offset !== void 0) {
+        throw new DeeplineError(
+          "requestId cannot be combined with runId, cursor, or offset.",
+          void 0,
+          "INVALID_USAGE_FILTERS"
+        );
+      }
+      params.set("request_id", requestId);
+    } else {
+      if (options.limit !== void 0) {
+        params.set("recent_limit", String(options.limit));
+      }
+      if (options.offset !== void 0) {
+        params.set("recent_offset", String(options.offset));
+      }
+      if (options.cursor !== void 0) {
+        params.set("recent_cursor", options.cursor);
+      }
+      if (options.runId !== void 0) {
+        params.set("run_id", options.runId);
+      }
+    }
+    const serializedParams = params.toString();
+    const query = serializedParams ? `?${serializedParams}` : "";
+    return this.http.get(`/api/v2/billing/usage${query}`);
+  }
   /**
    * Charge the saved payment method and add Deepline credits to the active
    * workspace. Prefer `client.billing.topUp(...)`.
@@ -11369,6 +11413,10 @@ function createNamedPlayHandle(clientFactory, name) {
 }
 var DeeplineContext = class {
   client;
+  /** Read current billing usage and exact per-request Deepline charges. */
+  get billing() {
+    return this.client.billing;
+  }
   /**
    * Create a high-level SDK context.
    *

package/dist/install-integrity.json

@@ -101,6 +101,7 @@
     "dist/bundling-sources/shared_libs/observability/runtime-console.ts",
     "dist/bundling-sources/shared_libs/observability/scheduled-job-errors.ts",
     "dist/bundling-sources/shared_libs/observability/scheduled-jobs.json",
+    "dist/bundling-sources/shared_libs/observability/scheduled-work-control.ts",
     "dist/bundling-sources/shared_libs/observability/scheduled-work-manual.ts",
     "dist/bundling-sources/shared_libs/observability/scheduled-work-v2.ts",
     "dist/bundling-sources/shared_libs/observability/scheduled-work.ts",

package/dist/release.d.mts

@@ -149,7 +149,7 @@ type SdkRelease = {
     supportPolicy: SdkSupportPolicy;
 };
 declare const SDK_RELEASE: {
-    readonly version: "0.3.162";
+    readonly version: "0.3.164";
     readonly 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.";
     readonly packageCapabilities: {
         readonly updatePreferences: 1;

package/dist/release.d.ts

@@ -149,7 +149,7 @@ type SdkRelease = {
     supportPolicy: SdkSupportPolicy;
 };
 declare const SDK_RELEASE: {
-    readonly version: "0.3.162";
+    readonly version: "0.3.164";
     readonly 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.";
     readonly packageCapabilities: {
         readonly updatePreferences: 1;

package/dist/release.js

@@ -74,7 +74,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.162",
+  version: "0.3.164",
   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

package/dist/release.mjs

@@ -48,7 +48,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.162",
+  version: "0.3.164",
   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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepline",
-  "version": "0.3.162",
+  "version": "0.3.164",
   "description": "GTM data CLI and TypeScript SDK for coding agents",
   "license": "MIT",
   "homepage": "https://code.deepline.com",