deepline 0.3.236 → 0.3.238

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

@@ -64,15 +64,7 @@ import {
   type EffectiveProductNotificationGroup,
   type ProductNotificationGroupDraft,
 } from '../../shared_libs/product-notifications/configuration.js';
-import {
-  STREAM_HEALTHY_CONNECTION_MS,
-  isTransientPlayStreamError,
-  streamReconnectDelayMs,
-} from './stream-reconnect.js';
-import {
-  observeRunEvents,
-  RunObserveTransportUnavailableError,
-} from './runs/observe-transport.js';
+import { watchRunEvents as pollRunSnapshotEvents } from './runs/watch-polling.js';
 import type {
   DeeplineClientOptions,
   ResolvedConfig,
@@ -627,28 +619,35 @@ export type RunGetStatus =
 
 const RUNS_FAILED_LOG_LIMIT = 20;
 
-/** Streaming options for `client.runs.tail(...)`. */
-export type RunsTailOptions = {
+/** Options for `client.runs.watch(...)`. */
+export 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`. */
+export type RunsTailOptions = RunsWatchOptions;
+
 /** Log fetch options for `client.runs.logs(...)`. */
 export type RunsLogsOptions = {
   /** Return the LAST `limit` stored log lines (default 200). */
@@ -756,7 +755,7 @@ export type PlaySecretCheck = {
 };
 
 /**
- * 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
  */
@@ -782,7 +781,9 @@ export 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>;
@@ -2047,6 +2048,8 @@ export type BillingRecentUsageEntry = {
     | '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;
 };
@@ -2076,6 +2079,10 @@ export 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;
@@ -2659,6 +2666,7 @@ export class DeeplineClient {
       status: (runId) => this.getRunLifecycleStatus(runId),
       list: (options) => this.listRuns(options),
       listPage: (options) => this.listRunsPage(options),
+      watch: (runId, options) => this.watchRunToTerminal(runId, options),
       tail: (runId, options) => this.tailRun(runId, options),
       logs: (runId, options) => this.getRunLogs(runId, options),
       input: (runId) => this.getRunInput(runId),
@@ -3385,15 +3393,17 @@ export class DeeplineClient {
   }
 
   /**
-   * Start a play run and stream live runtime events from the same request.
+   * Submit a play run through the legacy event response.
    *
-   * Use this when a caller wants low-level event handling instead of submitting
-   * first and then connecting to `streamPlayRunEvents(runId)`.
+   * This reports admission from the start request; it does not watch an
+   * existing run. Use `startPlayRun()` and `watchRunEvents(runId)` separately.
+   *
+   * @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.
    */
   async *startPlayRunStream(
     request: StartPlayRunRequest,
@@ -4122,11 +4132,31 @@ export class DeeplineClient {
     return normalizePlayStatus(response);
   }
 
+  /** Poll authenticated run snapshots every two seconds and emit changed events. */
+  async *watchRunEvents(
+    workflowId: string,
+    options?: {
+      signal?: AbortSignal;
+      onNotice?: (message: string) => void;
+      onRetry?: RunsWatchOptions['onRetry'];
+    },
+  ): AsyncGenerator<PlayLiveEvent> {
+    for await (const event of pollRunSnapshotEvents({
+      http: this.http,
+      runId: workflowId,
+      signal: options?.signal,
+      onNotice: options?.onNotice,
+      onRetry: options?.onRetry,
+    })) {
+      yield event as 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.
    */
   async *streamPlayRunEvents(
     workflowId: string,
@@ -4152,6 +4182,82 @@ export class DeeplineClient {
     }
   }
 
+  /**
+   * 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.
+   */
+  async *observeRunEvents(
+    runId: string,
+    options?: {
+      signal?: AbortSignal;
+      onNotice?: (message: string) => void;
+      /** @deprecated Ignored; watching always uses REST snapshot polling. */
+      fallback?: 'sse' | 'none';
+    },
+  ): AsyncGenerator<PlayLiveEvent> {
+    yield* this.watchRunEvents(runId, {
+      signal: options?.signal,
+      onNotice: options?.onNotice,
+    });
+  }
+
+  /** Poll snapshots to terminal status and return the durable package. */
+  private async watchRunToTerminal(
+    runId: string,
+    options?: RunsWatchOptions,
+  ): Promise<PlayStatus> {
+    const state: PlayLiveStatusState = {
+      runId,
+      status: 'running',
+      logs: [],
+      lastLogSeq: 0,
+      latest: null,
+    };
+    let terminalObserved = false;
+    for await (const event of this.watchRunEvents(runId, {
+      signal: options?.signal,
+      onNotice: options?.onNotice,
+      onRetry: options?.onRetry ?? options?.onReconnect,
+    })) {
+      options?.onEvent?.(event);
+      const status = updatePlayLiveStatusState(state, event);
+      if (status && TERMINAL_PLAY_STATUSES.has(status.status)) {
+        terminalObserved = true;
+      }
+    }
+    if (options?.signal?.aborted) {
+      throw new DeeplineError('Run watch aborted.', undefined, 'ABORTED');
+    }
+    if (terminalObserved) {
+      return await this.getRunStatus(runId);
+    }
+    const refreshed = await this.getRunStatus(runId);
+    if (TERMINAL_PLAY_STATUSES.has(refreshed.status)) return refreshed;
+    throw new DeeplineError(
+      `Run watch for ${runId} ended before a terminal status.`,
+      undefined,
+      'PLAY_WATCH_ENDED',
+    );
+  }
+
+  /**
+   * 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.
+   */
+  async tailRun(runId: string, options?: RunsTailOptions): Promise<PlayStatus> {
+    return this.watchRunToTerminal(runId, options);
+  }
+
   /**
    * Cancel a running play execution.
    *
@@ -4486,263 +4592,6 @@ export class DeeplineClient {
     return { ...response, runs: response.runs ?? [] };
   }
 
-  /**
-   * 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.
-   */
-  async *observeRunEvents(
-    runId: string,
-    options?: {
-      signal?: AbortSignal;
-      onNotice?: (message: string) => void;
-      fallback?: 'sse' | 'none';
-    },
-  ): AsyncGenerator<PlayLiveEvent> {
-    let yieldedObserveEvent = false;
-    try {
-      for await (const event of observeRunEvents({
-        http: this.http,
-        runId,
-        signal: options?.signal,
-        onNotice: options?.onNotice,
-      }) as AsyncGenerator<PlayLiveEvent>) {
-        yieldedObserveEvent = true;
-        yield event;
-      }
-    } catch (error) {
-      if (
-        !(error instanceof RunObserveTransportUnavailableError) ||
-        yieldedObserveEvent ||
-        options?.fallback === 'none'
-      ) {
-        throw error;
-      }
-      options?.onNotice?.(
-        `[observe] live subscription unavailable (${error.reason}); falling back to SSE tail (support window, ADR-0008)`,
-      );
-      yield* this.streamPlayRunEventsUntilTerminal(runId, options);
-    }
-  }
-
-  private async *streamPlayRunEventsUntilTerminal(
-    runId: string,
-    options?: { signal?: AbortSignal; onNotice?: (message: string) => void },
-  ): AsyncGenerator<PlayLiveEvent> {
-    const state: PlayLiveStatusState = {
-      runId,
-      status: 'running',
-      logs: [],
-      lastLogSeq: 0,
-      latest: null,
-    };
-    let lastEventId: string | undefined;
-    let reconnectAttempt = 0;
-
-    for (;;) {
-      if (options?.signal?.aborted) {
-        return;
-      }
-      const connectedAt = Date.now();
-      let sawEvent = false;
-      let endedReason = 'stream window ended before a terminal event';
-      try {
-        for await (const event of this.streamPlayRunEvents(runId, {
-          mode: 'cli',
-          signal: options?.signal,
-          ...(lastEventId ? { lastEventId } : {}),
-        })) {
-          sawEvent = true;
-          if (event.cursor?.trim()) {
-            lastEventId = event.cursor;
-          }
-          yield event;
-          const status = updatePlayLiveStatusState(state, event);
-          if (status && TERMINAL_PLAY_STATUSES.has(status.status)) {
-            return;
-          }
-        }
-      } catch (error) {
-        if (options?.signal?.aborted) {
-          return;
-        }
-        if (!isTransientPlayStreamError(error)) {
-          throw error;
-        }
-        endedReason = error instanceof Error ? error.message : String(error);
-      }
-
-      let refreshed: PlayStatus | null = null;
-      try {
-        refreshed = await this.getRunStatus(runId);
-      } catch (error) {
-        if (!isTransientPlayStreamError(error)) {
-          throw error;
-        }
-      }
-      if (refreshed && TERMINAL_PLAY_STATUSES.has(refreshed.status)) {
-        yield {
-          cursor: String(Date.now()),
-          streamId: `sse-fallback:${runId}`,
-          scope: 'play',
-          type: 'play.run.status',
-          at: new Date().toISOString(),
-          payload: refreshed as unknown as Record<string, unknown>,
-        };
-        return;
-      }
-
-      if (
-        sawEvent ||
-        Date.now() - connectedAt >= STREAM_HEALTHY_CONNECTION_MS
-      ) {
-        reconnectAttempt = 0;
-      }
-      const delayMs = streamReconnectDelayMs(reconnectAttempt);
-      reconnectAttempt += 1;
-      options?.onNotice?.(
-        `[observe] SSE tail window ended before terminal status (${endedReason}); reconnecting to run ${runId}`,
-      );
-      await sleep(delayMs);
-    }
-  }
-
-  /**
-   * Tail one run through the subscription transport until terminal, then
-   * return one durable REST status read (the final Run Response Package).
-   */
-  private async tailRunViaObserveTransport(
-    runId: string,
-    options?: RunsTailOptions,
-  ): Promise<PlayStatus> {
-    const state: PlayLiveStatusState = {
-      runId,
-      status: 'running',
-      logs: [],
-      lastLogSeq: 0,
-      latest: null,
-    };
-    for await (const event of this.observeRunEvents(runId, {
-      signal: options?.signal,
-      onNotice: options?.onNotice,
-      fallback: 'none',
-    })) {
-      options?.onEvent?.(event);
-      const status = updatePlayLiveStatusState(state, event);
-      if (!status || !TERMINAL_PLAY_STATUSES.has(status.status)) {
-        continue;
-      }
-      return await this.getRunStatus(status.runId || runId);
-    }
-    if (options?.signal?.aborted) {
-      throw new DeeplineError('Run observation aborted.', undefined, 'ABORTED');
-    }
-    // The transport ends only after a terminal snapshot; the differ always
-    // emits a terminal `play.run.status` first, so reaching here means the
-    // terminal package read raced — re-check durable status once, loudly.
-    const refreshed = await this.getRunStatus(runId);
-    if (TERMINAL_PLAY_STATUSES.has(refreshed.status)) {
-      return refreshed;
-    }
-    throw new DeeplineError(
-      `Run observation for ${runId} ended before a terminal status.`,
-      undefined,
-      'PLAY_LIVE_STREAM_ENDED',
-    );
-  }
-
-  /**
-   * 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.
-   */
-  async tailRun(runId: string, options?: RunsTailOptions): Promise<PlayStatus> {
-    try {
-      return await this.tailRunViaObserveTransport(runId, options);
-    } catch (error) {
-      if (!(error instanceof RunObserveTransportUnavailableError)) {
-        throw error;
-      }
-      options?.onNotice?.(
-        `[observe] live subscription unavailable (${error.reason}); falling back to SSE tail (support window, ADR-0008)`,
-      );
-    }
-    const state: PlayLiveStatusState = {
-      runId,
-      status: 'running',
-      logs: [],
-      lastLogSeq: 0,
-      latest: null,
-    };
-    let reconnectAttempt = 0;
-
-    for (;;) {
-      const connectedAt = Date.now();
-      let sawEvent = false;
-      let terminalRunId: string | null = null;
-      let endedReason = 'stream window ended before a terminal event';
-      try {
-        for await (const event of this.streamPlayRunEvents(runId, {
-          mode: 'cli',
-          signal: options?.signal,
-        })) {
-          options?.onEvent?.(event);
-          sawEvent = true;
-          const status = updatePlayLiveStatusState(state, event);
-          if (!status || !TERMINAL_PLAY_STATUSES.has(status.status)) {
-            continue;
-          }
-          terminalRunId = status.runId || runId;
-          break;
-        }
-      } catch (error) {
-        if (options?.signal?.aborted || !isTransientPlayStreamError(error)) {
-          throw error;
-        }
-        endedReason = error instanceof Error ? error.message : String(error);
-      }
-
-      if (terminalRunId) {
-        return await this.getRunStatus(terminalRunId);
-      }
-
-      // Window ended without a terminal event. The run may have finished
-      // during the gap — re-check durable status once before reconnecting.
-      // `runs.get` owns the durable snapshot; its optional status evidence is
-      // additive and must not prevent old servers from ending this stream.
-      const refreshed = await this.getRunStatus(runId);
-      if (TERMINAL_PLAY_STATUSES.has(refreshed.status)) {
-        return refreshed;
-      }
-
-      if (
-        sawEvent ||
-        Date.now() - connectedAt >= STREAM_HEALTHY_CONNECTION_MS
-      ) {
-        reconnectAttempt = 0;
-      }
-      const delayMs = streamReconnectDelayMs(reconnectAttempt);
-      reconnectAttempt += 1;
-      options?.onReconnect?.({
-        attempt: reconnectAttempt,
-        delayMs,
-        reason: endedReason,
-      });
-      await sleep(delayMs);
-    }
-  }
-
   /** Get the exact original input retained for a run. This is intentionally separate from status. */
   async getRunInput(runId: string): Promise<{
     runId: string;
@@ -5816,10 +5665,10 @@ export class DeeplineClient {
   // ——————————————————————————————————————————————————————————
 
   /**
-   * 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`
@@ -5896,6 +5745,7 @@ export class DeeplineClient {
       lastLogSeq: 0,
       latest: null,
     };
+    let terminalObserved: PlayStatus | null = null;
 
     if (options?.signal?.aborted) {
       await this.cancelPlay(workflowId);
@@ -5908,8 +5758,7 @@ export class DeeplineClient {
       };
     }
 
-    for await (const event of this.streamPlayRunEvents(workflowId, {
-      mode: 'cli',
+    for await (const event of this.watchRunEvents(workflowId, {
       signal: options?.signal,
     })) {
       if (options?.signal?.aborted) {
@@ -5923,22 +5772,42 @@ export class DeeplineClient {
         };
       }
 
+      const previousStatus = state.latest?.status;
       const status = updatePlayLiveStatusState(state, event);
       if (!status) {
         continue;
       }
-      options?.onProgress?.(status);
+      if (
+        event.type !== 'play.run.status' ||
+        status.status !== previousStatus
+      ) {
+        options?.onProgress?.(status);
+      }
 
       if (TERMINAL_PLAY_STATUSES.has(status.status)) {
-        const finalStatus = await this.getPlayStatus(
-          status.runId || workflowId,
-        ).catch(() => status);
-        return playRunResultFromStatus(finalStatus, start, workflowId);
+        terminalObserved = status;
       }
     }
 
+    if (options?.signal?.aborted) {
+      await this.cancelPlay(workflowId);
+      return {
+        success: false,
+        runId: workflowId,
+        logs: state.logs,
+        durationMs: Date.now() - start,
+        error: 'Cancelled by user',
+      };
+    }
+    if (terminalObserved) {
+      const finalStatus = await this.getPlayStatus(
+        terminalObserved.runId || workflowId,
+      ).catch(() => terminalObserved!);
+      return playRunResultFromStatus(finalStatus, start, workflowId);
+    }
+
     throw new DeeplineError(
-      `Run stream for ${workflowId} ended before the run reached a terminal state.`,
+      `Run watch for ${workflowId} ended before the run reached a terminal state.`,
       undefined,
       'PLAY_RUN_STREAM_ENDED',
       { runId: workflowId, workflowId },

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

@@ -992,7 +992,7 @@ function isRetryableApiErrorResponse(status: number): boolean {
  * to CLI users — it lands verbatim in `DeeplineError.message`/`details`. When
  * detected, we synthesize a structured message (status + extracted <title>) and
  * preserve the literal token `Worker threw exception` when present, since SDK
- * retry classifiers (`isTransientPlayStreamError`) regex-match on it.
+ * retry classifiers (`isTransientPlayRunReadError`) regex-match on it.
  */
 function detectHtmlErrorBody(
   body: string,

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

@@ -137,6 +137,7 @@ export type {
   RunsLogsOptions,
   RunsLogsResult,
   RunsNamespace,
+  RunsWatchOptions,
   RunsTailOptions,
   StopAllRunsOptions,
   ToolExecution,

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.236',
+  version: '0.3.238',
   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: {