deepline 0.3.236 → 0.3.238

package/dist/index.d.mts

@@ -3454,27 +3454,33 @@ type RunGetStatus = {
         };
     } | null;
 };
-/** Streaming options for `client.runs.tail(...)`. */
-type RunsTailOptions = {
+/** Options for `client.runs.watch(...)`. */
+type RunsWatchOptions = {
     signal?: AbortSignal;
-    /** Observe each canonical live event while `tail` waits for terminal state. */
+    /** Observe each canonical event while `watch` waits for terminal state. */
     onEvent?: (event: PlayLiveEvent) => void;
     /**
-     * Called before each stream reconnect. Server stream windows are finite, so
-     * long runs reconnect with backoff until a terminal status is observed.
+     * Called once when a transient REST polling outage begins. Polling retries
+     * on its normal fixed interval.
      */
+    onRetry?: (info: {
+        attempt: number;
+        delayMs: number;
+        reason: string;
+    }) => void;
+    /** @deprecated Use `onRetry`. */
     onReconnect?: (info: {
         attempt: number;
         delayMs: number;
         reason: string;
     }) => void;
     /**
-     * Display-only transport notices: subscription-transport reconnects,
-     * staleness warnings, and the one-time fallback notice when the server
-     * cannot serve the Convex subscription transport (ADR-0008).
+     * Display-only notices for a transient snapshot polling outage or recovery.
      */
     onNotice?: (message: string) => void;
 };
+/** @deprecated Use `RunsWatchOptions`. */
+type RunsTailOptions = RunsWatchOptions;
 /** Log fetch options for `client.runs.logs(...)`. */
 type RunsLogsOptions = {
     /** Return the LAST `limit` stored log lines (default 200). */
@@ -3562,7 +3568,7 @@ type PlaySecretCheck = {
     secret: PlaySecretMetadata | null;
 };
 /**
- * Use `client.runs` (`/api/v2/runs`) to poll, stream, stop, read logs, and export durable dataset rows.
+ * Use `client.runs` (`/api/v2/runs`) to watch, stop, read logs, and export durable dataset rows.
  *
  * @sdkReference client 020 client.runs
  */
@@ -3588,7 +3594,9 @@ type RunsNamespace = {
     list: (options: RunsListOptions) => Promise<PlayRunListItem[]>;
     /** Read one run page with total, offset, limit and completeness metadata. */
     listPage: (options: RunsListOptions) => Promise<RunsListPage>;
-    /** Stream run events and return the latest/terminal run status. */
+    /** Poll run snapshots every two seconds until terminal status. */
+    watch: (runId: string, options?: RunsWatchOptions) => Promise<PlayStatus>;
+    /** @deprecated Use `watch`; retained as a source-compatible alias. */
     tail: (runId: string, options?: RunsTailOptions) => Promise<PlayStatus>;
     /** Fetch persisted log lines for a run. */
     logs: (runId: string, options?: RunsLogsOptions) => Promise<RunsLogsResult>;
@@ -4738,6 +4746,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 +4777,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;
@@ -5089,15 +5103,17 @@ declare class DeeplineClient {
      */
     startPlayRun(request: StartPlayRunRequest): Promise<PlayRunStart>;
     /**
-     * Start a play run and stream live runtime events from the same request.
+     * Submit a play run through the legacy event response.
+     *
+     * This reports admission from the start request; it does not watch an
+     * existing run. Use `startPlayRun()` and `watchRunEvents(runId)` separately.
      *
-     * Use this when a caller wants low-level event handling instead of submitting
-     * first and then connecting to `streamPlayRunEvents(runId)`.
+     * @deprecated Use the separate start and watch methods.
      *
      * @param request - Play run configuration.
-     * @param options - Optional streaming options.
-     * @param options.signal - Optional abort signal for the streaming request.
-     * @returns Async stream of play-scoped live events.
+     * @param options - Optional compatibility response options.
+     * @param options.signal - Abort the start response.
+     * @returns Async generator of play-scoped live events.
      */
     startPlayRunStream(request: StartPlayRunRequest, options?: {
         signal?: AbortSignal;
@@ -5358,17 +5374,50 @@ declare class DeeplineClient {
         billing?: boolean;
         full?: boolean;
     }): Promise<PlayStatus>;
+    /** Poll authenticated run snapshots every two seconds and emit changed events. */
+    watchRunEvents(workflowId: string, options?: {
+        signal?: AbortSignal;
+        onNotice?: (message: string) => void;
+        onRetry?: RunsWatchOptions['onRetry'];
+    }): AsyncGenerator<PlayLiveEvent>;
     /**
-     * Stream semantic play-run events using the same SSE feed as the dashboard.
+     * Read raw legacy SSE events for callers that explicitly require that
+     * compatibility endpoint. Ordinary run watching uses REST snapshot polling.
      *
-     * The server emits a canonical `play.run.snapshot` event first for every
-     * connection, then incremental live events until terminal state or reconnect.
+     * @deprecated Use `watchRunEvents` for ordinary run watching.
      */
     streamPlayRunEvents(workflowId: string, options?: {
         signal?: AbortSignal;
         lastEventId?: string;
         mode?: 'cli' | 'ui';
     }): AsyncGenerator<PlayLiveEvent>;
+    /**
+     * Compatibility alias for polling canonical run snapshots and emitting
+     * their changed events.
+     *
+     * @deprecated Use `watchRunEvents`; kept as a source-compatible alias.
+     * The `fallback` option is ignored because watching uses REST polling.
+     */
+    observeRunEvents(runId: string, options?: {
+        signal?: AbortSignal;
+        onNotice?: (message: string) => void;
+        /** @deprecated Ignored; watching always uses REST snapshot polling. */
+        fallback?: 'sse' | 'none';
+    }): AsyncGenerator<PlayLiveEvent>;
+    /** Poll snapshots to terminal status and return the durable package. */
+    private watchRunToTerminal;
+    /**
+     * Wait for a run and return its terminal status.
+     *
+     * This source-compatible alias uses the same authenticated two-second REST
+     * snapshot polling as `client.runs.watch`.
+     *
+     * @deprecated Use `client.runs.watch`; retained for SDK compatibility.
+     * @param runId - Public Deepline play-run id.
+     * @param options - Optional callbacks and cancellation signal.
+     * @returns The final durable run status.
+     */
+    tailRun(runId: string, options?: RunsTailOptions): Promise<PlayStatus>;
     /**
      * Cancel a running play execution.
      *
@@ -5486,39 +5535,6 @@ declare class DeeplineClient {
     listRuns(options: RunsListOptions): Promise<PlayRunListItem[]>;
     /** Read one run page without discarding server pagination metadata. */
     listRunsPage(options: RunsListOptions): Promise<RunsListPage>;
-    /**
-     * Observe one run's live events. Uses the Convex Run Snapshot subscription
-     * transport first (ADR-0008), then falls back to the canonical SSE stream
-     * when the subscription transport or its optional client modules are not
-     * available. Pass `fallback: 'none'` to receive
-     * {@link RunObserveTransportUnavailableError} instead.
-     */
-    observeRunEvents(runId: string, options?: {
-        signal?: AbortSignal;
-        onNotice?: (message: string) => void;
-        fallback?: 'sse' | 'none';
-    }): AsyncGenerator<PlayLiveEvent>;
-    private streamPlayRunEventsUntilTerminal;
-    /**
-     * Tail one run through the subscription transport until terminal, then
-     * return one durable REST status read (the final Run Response Package).
-     */
-    private tailRunViaObserveTransport;
-    /**
-     * Read the canonical run stream until a terminal run status is observed.
-     *
-     * Tries the Convex Run Snapshot subscription transport first (ADR-0008);
-     * when the server cannot serve it (grant endpoint missing/unconfigured or
-     * Convex unreachable) it falls back — with one `onNotice` message — to the
-     * support-window SSE stream below.
-     *
-     * Server stream windows are finite: they end cleanly at the function
-     * ceiling even while the run keeps executing. A window that ends (cleanly
-     * or via transient network error) without a terminal event triggers one
-     * durable-status re-check followed by a backed-off reconnect, so long runs
-     * tail to completion. Abort via `options.signal` to stop waiting.
-     */
-    tailRun(runId: string, options?: RunsTailOptions): Promise<PlayStatus>;
     /** Get the exact original input retained for a run. This is intentionally separate from status. */
     getRunInput(runId: string): Promise<{
         runId: string;
@@ -5848,10 +5864,10 @@ declare class DeeplineClient {
         revisionId?: string;
     }): Promise<SharePageStatus>;
     /**
-     * Run a play end-to-end: submit, stream until terminal, return result.
+     * Run a play end-to-end: submit, poll progress until terminal, return result.
      *
      * This is the highest-level play execution method. It submits the play,
-     * reads the canonical run stream for status updates, and returns a structured
+     * reads the canonical run snapshot for status updates, and returns a structured
      * result with logs and timing. Supports cancellation via `AbortSignal`.
      *
      * @param code - Source string fallback; pass the bundled artifact in `options.artifact`
@@ -6873,8 +6889,12 @@ declare const defineWorkflow: typeof definePlay;
 declare function getDefinedPlayMetadata(value: unknown): PlayMetadata | null;
 
 /**
- * Bootstrap failure: this server/deployment cannot serve the subscription
- * transport. Callers fall back to the support-window SSE stream (ADR-0008).
+ * Compatibility export retained for SDK callers that imported the old error.
+ * Run watching now uses authenticated REST snapshot polling and does not throw
+ * this error.
+ *
+ * @deprecated The subscription transport has been removed. Use
+ * `client.watchRunEvents()` or `client.runs.watch()`.
  */
 declare class RunObserveTransportUnavailableError extends Error {
     readonly reason: string;
@@ -7160,4 +7180,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 BillingRecentUsageEntry, type BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type BillingTopUpReceipt, 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 PlayPath, type PlayReferenceLike, type PlayRevisionSummary, type PlayRunActionPackage, type PlayRunActivityProjection, type PlayRunDatasetActions, type PlayRunId, type PlayRunPackage, type PlayRunResult, type PlayRunStart, type PlaySettings, type PlaySettingsPatch, type PlaySettingsPathsPage, type PlaySettingsResult, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PlaysActivityResponse, type PlaysListOptions, type PlaysListPage, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type RerunOptions, type RerunPlayRunResult, type ResolvedConfig, type RunLifecycleStatus, 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 BillingTopUpReceipt, 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 PlayPath, type PlayReferenceLike, type PlayRevisionSummary, type PlayRunActionPackage, type PlayRunActivityProjection, type PlayRunDatasetActions, type PlayRunId, type PlayRunPackage, type PlayRunResult, type PlayRunStart, type PlaySettings, type PlaySettingsPatch, type PlaySettingsPathsPage, type PlaySettingsResult, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PlaysActivityResponse, type PlaysListOptions, type PlaysListPage, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type RerunOptions, type RerunPlayRunResult, type ResolvedConfig, type RunLifecycleStatus, RunObserveTransportUnavailableError, type RunsListOptions, type RunsListPage, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, type RunsWatchOptions, 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

@@ -3454,27 +3454,33 @@ type RunGetStatus = {
         };
     } | null;
 };
-/** Streaming options for `client.runs.tail(...)`. */
-type RunsTailOptions = {
+/** Options for `client.runs.watch(...)`. */
+type RunsWatchOptions = {
     signal?: AbortSignal;
-    /** Observe each canonical live event while `tail` waits for terminal state. */
+    /** Observe each canonical event while `watch` waits for terminal state. */
     onEvent?: (event: PlayLiveEvent) => void;
     /**
-     * Called before each stream reconnect. Server stream windows are finite, so
-     * long runs reconnect with backoff until a terminal status is observed.
+     * Called once when a transient REST polling outage begins. Polling retries
+     * on its normal fixed interval.
      */
+    onRetry?: (info: {
+        attempt: number;
+        delayMs: number;
+        reason: string;
+    }) => void;
+    /** @deprecated Use `onRetry`. */
     onReconnect?: (info: {
         attempt: number;
         delayMs: number;
         reason: string;
     }) => void;
     /**
-     * Display-only transport notices: subscription-transport reconnects,
-     * staleness warnings, and the one-time fallback notice when the server
-     * cannot serve the Convex subscription transport (ADR-0008).
+     * Display-only notices for a transient snapshot polling outage or recovery.
      */
     onNotice?: (message: string) => void;
 };
+/** @deprecated Use `RunsWatchOptions`. */
+type RunsTailOptions = RunsWatchOptions;
 /** Log fetch options for `client.runs.logs(...)`. */
 type RunsLogsOptions = {
     /** Return the LAST `limit` stored log lines (default 200). */
@@ -3562,7 +3568,7 @@ type PlaySecretCheck = {
     secret: PlaySecretMetadata | null;
 };
 /**
- * Use `client.runs` (`/api/v2/runs`) to poll, stream, stop, read logs, and export durable dataset rows.
+ * Use `client.runs` (`/api/v2/runs`) to watch, stop, read logs, and export durable dataset rows.
  *
  * @sdkReference client 020 client.runs
  */
@@ -3588,7 +3594,9 @@ type RunsNamespace = {
     list: (options: RunsListOptions) => Promise<PlayRunListItem[]>;
     /** Read one run page with total, offset, limit and completeness metadata. */
     listPage: (options: RunsListOptions) => Promise<RunsListPage>;
-    /** Stream run events and return the latest/terminal run status. */
+    /** Poll run snapshots every two seconds until terminal status. */
+    watch: (runId: string, options?: RunsWatchOptions) => Promise<PlayStatus>;
+    /** @deprecated Use `watch`; retained as a source-compatible alias. */
     tail: (runId: string, options?: RunsTailOptions) => Promise<PlayStatus>;
     /** Fetch persisted log lines for a run. */
     logs: (runId: string, options?: RunsLogsOptions) => Promise<RunsLogsResult>;
@@ -4738,6 +4746,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 +4777,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;
@@ -5089,15 +5103,17 @@ declare class DeeplineClient {
      */
     startPlayRun(request: StartPlayRunRequest): Promise<PlayRunStart>;
     /**
-     * Start a play run and stream live runtime events from the same request.
+     * Submit a play run through the legacy event response.
+     *
+     * This reports admission from the start request; it does not watch an
+     * existing run. Use `startPlayRun()` and `watchRunEvents(runId)` separately.
      *
-     * Use this when a caller wants low-level event handling instead of submitting
-     * first and then connecting to `streamPlayRunEvents(runId)`.
+     * @deprecated Use the separate start and watch methods.
      *
      * @param request - Play run configuration.
-     * @param options - Optional streaming options.
-     * @param options.signal - Optional abort signal for the streaming request.
-     * @returns Async stream of play-scoped live events.
+     * @param options - Optional compatibility response options.
+     * @param options.signal - Abort the start response.
+     * @returns Async generator of play-scoped live events.
      */
     startPlayRunStream(request: StartPlayRunRequest, options?: {
         signal?: AbortSignal;
@@ -5358,17 +5374,50 @@ declare class DeeplineClient {
         billing?: boolean;
         full?: boolean;
     }): Promise<PlayStatus>;
+    /** Poll authenticated run snapshots every two seconds and emit changed events. */
+    watchRunEvents(workflowId: string, options?: {
+        signal?: AbortSignal;
+        onNotice?: (message: string) => void;
+        onRetry?: RunsWatchOptions['onRetry'];
+    }): AsyncGenerator<PlayLiveEvent>;
     /**
-     * Stream semantic play-run events using the same SSE feed as the dashboard.
+     * Read raw legacy SSE events for callers that explicitly require that
+     * compatibility endpoint. Ordinary run watching uses REST snapshot polling.
      *
-     * The server emits a canonical `play.run.snapshot` event first for every
-     * connection, then incremental live events until terminal state or reconnect.
+     * @deprecated Use `watchRunEvents` for ordinary run watching.
      */
     streamPlayRunEvents(workflowId: string, options?: {
         signal?: AbortSignal;
         lastEventId?: string;
         mode?: 'cli' | 'ui';
     }): AsyncGenerator<PlayLiveEvent>;
+    /**
+     * Compatibility alias for polling canonical run snapshots and emitting
+     * their changed events.
+     *
+     * @deprecated Use `watchRunEvents`; kept as a source-compatible alias.
+     * The `fallback` option is ignored because watching uses REST polling.
+     */
+    observeRunEvents(runId: string, options?: {
+        signal?: AbortSignal;
+        onNotice?: (message: string) => void;
+        /** @deprecated Ignored; watching always uses REST snapshot polling. */
+        fallback?: 'sse' | 'none';
+    }): AsyncGenerator<PlayLiveEvent>;
+    /** Poll snapshots to terminal status and return the durable package. */
+    private watchRunToTerminal;
+    /**
+     * Wait for a run and return its terminal status.
+     *
+     * This source-compatible alias uses the same authenticated two-second REST
+     * snapshot polling as `client.runs.watch`.
+     *
+     * @deprecated Use `client.runs.watch`; retained for SDK compatibility.
+     * @param runId - Public Deepline play-run id.
+     * @param options - Optional callbacks and cancellation signal.
+     * @returns The final durable run status.
+     */
+    tailRun(runId: string, options?: RunsTailOptions): Promise<PlayStatus>;
     /**
      * Cancel a running play execution.
      *
@@ -5486,39 +5535,6 @@ declare class DeeplineClient {
     listRuns(options: RunsListOptions): Promise<PlayRunListItem[]>;
     /** Read one run page without discarding server pagination metadata. */
     listRunsPage(options: RunsListOptions): Promise<RunsListPage>;
-    /**
-     * Observe one run's live events. Uses the Convex Run Snapshot subscription
-     * transport first (ADR-0008), then falls back to the canonical SSE stream
-     * when the subscription transport or its optional client modules are not
-     * available. Pass `fallback: 'none'` to receive
-     * {@link RunObserveTransportUnavailableError} instead.
-     */
-    observeRunEvents(runId: string, options?: {
-        signal?: AbortSignal;
-        onNotice?: (message: string) => void;
-        fallback?: 'sse' | 'none';
-    }): AsyncGenerator<PlayLiveEvent>;
-    private streamPlayRunEventsUntilTerminal;
-    /**
-     * Tail one run through the subscription transport until terminal, then
-     * return one durable REST status read (the final Run Response Package).
-     */
-    private tailRunViaObserveTransport;
-    /**
-     * Read the canonical run stream until a terminal run status is observed.
-     *
-     * Tries the Convex Run Snapshot subscription transport first (ADR-0008);
-     * when the server cannot serve it (grant endpoint missing/unconfigured or
-     * Convex unreachable) it falls back — with one `onNotice` message — to the
-     * support-window SSE stream below.
-     *
-     * Server stream windows are finite: they end cleanly at the function
-     * ceiling even while the run keeps executing. A window that ends (cleanly
-     * or via transient network error) without a terminal event triggers one
-     * durable-status re-check followed by a backed-off reconnect, so long runs
-     * tail to completion. Abort via `options.signal` to stop waiting.
-     */
-    tailRun(runId: string, options?: RunsTailOptions): Promise<PlayStatus>;
     /** Get the exact original input retained for a run. This is intentionally separate from status. */
     getRunInput(runId: string): Promise<{
         runId: string;
@@ -5848,10 +5864,10 @@ declare class DeeplineClient {
         revisionId?: string;
     }): Promise<SharePageStatus>;
     /**
-     * Run a play end-to-end: submit, stream until terminal, return result.
+     * Run a play end-to-end: submit, poll progress until terminal, return result.
      *
      * This is the highest-level play execution method. It submits the play,
-     * reads the canonical run stream for status updates, and returns a structured
+     * reads the canonical run snapshot for status updates, and returns a structured
      * result with logs and timing. Supports cancellation via `AbortSignal`.
      *
      * @param code - Source string fallback; pass the bundled artifact in `options.artifact`
@@ -6873,8 +6889,12 @@ declare const defineWorkflow: typeof definePlay;
 declare function getDefinedPlayMetadata(value: unknown): PlayMetadata | null;
 
 /**
- * Bootstrap failure: this server/deployment cannot serve the subscription
- * transport. Callers fall back to the support-window SSE stream (ADR-0008).
+ * Compatibility export retained for SDK callers that imported the old error.
+ * Run watching now uses authenticated REST snapshot polling and does not throw
+ * this error.
+ *
+ * @deprecated The subscription transport has been removed. Use
+ * `client.watchRunEvents()` or `client.runs.watch()`.
  */
 declare class RunObserveTransportUnavailableError extends Error {
     readonly reason: string;
@@ -7160,4 +7180,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 BillingRecentUsageEntry, type BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type BillingTopUpReceipt, 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 PlayPath, type PlayReferenceLike, type PlayRevisionSummary, type PlayRunActionPackage, type PlayRunActivityProjection, type PlayRunDatasetActions, type PlayRunId, type PlayRunPackage, type PlayRunResult, type PlayRunStart, type PlaySettings, type PlaySettingsPatch, type PlaySettingsPathsPage, type PlaySettingsResult, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PlaysActivityResponse, type PlaysListOptions, type PlaysListPage, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type RerunOptions, type RerunPlayRunResult, type ResolvedConfig, type RunLifecycleStatus, 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 BillingTopUpReceipt, 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 PlayPath, type PlayReferenceLike, type PlayRevisionSummary, type PlayRunActionPackage, type PlayRunActivityProjection, type PlayRunDatasetActions, type PlayRunId, type PlayRunPackage, type PlayRunResult, type PlayRunStart, type PlaySettings, type PlaySettingsPatch, type PlaySettingsPathsPage, type PlaySettingsResult, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PlaysActivityResponse, type PlaysListOptions, type PlaysListPage, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type RerunOptions, type RerunPlayRunResult, type ResolvedConfig, type RunLifecycleStatus, RunObserveTransportUnavailableError, type RunsListOptions, type RunsListPage, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, type RunsWatchOptions, 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 };