deepline 0.3.201 → 0.3.203

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

@@ -123,7 +123,10 @@ import {
   TOOL_EXECUTION_ERROR_SCHEMA_HEADER,
   TOOL_EXECUTION_ERROR_SCHEMA_VERSION,
 } from '../../shared_libs/plays/tool-execution-error';
-import { decodePlayRunPublicStatus } from '../../shared_libs/play-runtime/run-lifecycle-policy.js';
+import {
+  decodePlayRunPublicStatus,
+  type PlayRunPublicStatus,
+} from '../../shared_libs/play-runtime/run-lifecycle-policy.js';
 import {
   legacyRawFromToolResponseRawV2,
   providerMetaFromToolResponseRawV2,
@@ -959,6 +962,8 @@ export type PlaySecretCheck = {
 export type RunsNamespace = {
   /** Get current run status by public run id. */
   get: (runId: string, options?: RunsGetOptions) => Promise<PlayStatus>;
+  /** Read bounded scalar lifecycle and confirmed work counts only. */
+  status: (runId: string) => Promise<RunLifecycleStatus>;
   /** Explicitly read the retained original input (may include customer data). */
   input: (runId: string) => Promise<{
     runId: string;
@@ -985,6 +990,8 @@ export type RunsNamespace = {
     limit?: number;
     offset?: number;
     rowMode?: 'output' | 'all';
+    /** Cancel the page request, including its response body and retry waits. */
+    signal?: AbortSignal;
   }) => Promise<PlaySheetRowsResult>;
   /** Stop a running/waiting run. */
   stop: (
@@ -1006,6 +1013,48 @@ export type RunsNamespace = {
   };
 };
 
+/** Result of the bounded `/api/v2/runs/:runId/status` endpoint. */
+export type RunLifecycleStatus =
+  | { available: false; runId: string }
+  | {
+      available: true;
+      runId: string;
+      lifecycle: {
+        status: PlayRunPublicStatus;
+        updatedAt: number;
+        startedAt: number | null;
+        finishedAt: number | null;
+      };
+      steps: {
+        observed: number;
+        running: number;
+        completed: number;
+        failed: number;
+        skipped: number;
+        confirmed: boolean;
+      };
+      /** Sums across observed step.progress records, not unique output rows. */
+      mapStepWork: {
+        sourceSteps: number;
+        completed: { value: number | null; confirmed: boolean };
+        total: { value: number | null; confirmed: boolean };
+        failed: { value: number | null; confirmed: boolean };
+        startedRows: { value: number | null; confirmed: boolean };
+        activeRows: { value: number | null; confirmed: boolean };
+        waitingRows: { value: number | null; confirmed: boolean };
+        completedRows: { value: number | null; confirmed: boolean };
+        supersededRows: { value: number | null; confirmed: boolean };
+      };
+      datasets: {
+        observed: number;
+        persistedRows: { value: number | null; confirmed: boolean };
+        succeededRows: { value: number | null; confirmed: boolean };
+        failedRows: { value: number | null; confirmed: boolean };
+        complete: { value: boolean | null; confirmed: boolean };
+      };
+      wait: { kind: string | null; until: number | null; confirmed: boolean };
+    };
+
 /** Options for {@link RunsNamespace.stopAll} / {@link DeeplineClient.stopAllRuns}. */
 export type StopAllRunsOptions = {
   /** Enumerate the candidate runs without cancelling or mutating anything. */
@@ -2845,6 +2894,7 @@ export class DeeplineClient {
     this.http = new HttpClient(this.config);
     this.runs = {
       get: (runId, options) => this.getRunStatus(runId, options),
+      status: (runId) => this.getRunLifecycleStatus(runId),
       list: (options) => this.listRuns(options),
       listPage: (options) => this.listRunsPage(options),
       tail: (runId, options) => this.tailRun(runId, options),
@@ -4793,6 +4843,14 @@ export class DeeplineClient {
     };
   }
 
+  /** Read only the bounded scalar projection; does not hydrate the run package. */
+  async getRunLifecycleStatus(runId: string): Promise<RunLifecycleStatus> {
+    const response = await this.http.get<RunLifecycleStatus>(
+      `/api/v2/runs/${encodeURIComponent(runId)}/status`,
+    );
+    return response;
+  }
+
   /**
    * List play runs using the public runs resource model.
    *
@@ -5256,6 +5314,8 @@ export class DeeplineClient {
     limit?: number;
     offset?: number;
     rowMode?: 'output' | 'all';
+    /** Cancel the page request, including its response body and retry waits. */
+    signal?: AbortSignal;
   }): Promise<PlaySheetRowsResult> {
     const params = new URLSearchParams({
       tableNamespace: input.tableNamespace,
@@ -5270,6 +5330,7 @@ export class DeeplineClient {
     }
     const result = await this.http.get<PlaySheetRowsResult>(
       `/api/v2/plays/${encodeURIComponent(input.playName)}/sheet?${params.toString()}`,
+      { signal: input.signal },
     );
     const requestedRunId = input.runId?.trim() || '';
     if (requestedRunId) {

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

@@ -59,6 +59,8 @@ interface RequestOptions {
   headers?: Record<string, string>;
   /** Per-request timeout override in milliseconds. */
   timeout?: number;
+  /** Cancel this request, including body reads, failover, and retry waits. */
+  signal?: AbortSignal;
   /**
    * Retry HTTP 408/425/5xx JSON API responses. Use only for idempotent requests;
    * most mutating API calls must fail loudly after the first server response.
@@ -93,6 +95,12 @@ type RequestAbortTaggedError = Error & {
   [REQUEST_ABORT_MARKER]?: true;
 };
 
+function requestCancelledError(signal: AbortSignal): RequestAbortTaggedError {
+  const error = withErrorCause(new Error('Request aborted'), signal.reason);
+  (error as RequestAbortTaggedError)[REQUEST_ABORT_MARKER] = true;
+  return error;
+}
+
 function normalizeRequestAbortError(
   error: unknown,
   input: { timeoutMs: number; timedOut: boolean },
@@ -391,7 +399,11 @@ export class HttpClient {
 
     const maxRetries = options?.maxRetries ?? this.config.maxRetries;
 
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    requestAttempts: for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      if (options?.signal?.aborted) {
+        lastError = requestCancelledError(options.signal);
+        break;
+      }
       if (attempt > 0) {
         const backoffMs = Math.min(1000 * Math.pow(2, attempt - 1), 30_000);
         const delayMs =
@@ -399,10 +411,19 @@ export class HttpClient {
             ? backoffMs
             : Math.max(backoffMs, retryAfterDelayMs);
         retryAfterDelayMs = null;
-        await sleep(delayMs);
+        try {
+          await sleep(delayMs, options?.signal);
+        } catch (error) {
+          lastError = error instanceof Error ? error : new Error(String(error));
+          break;
+        }
       }
 
       for (const candidateUrl of candidateUrls) {
+        if (options?.signal?.aborted) {
+          lastError = requestCancelledError(options.signal);
+          break requestAttempts;
+        }
         const controller = new AbortController();
         const timeoutMs = options?.timeout ?? this.config.timeout;
         let requestTimedOut = false;
@@ -410,6 +431,10 @@ export class HttpClient {
           requestTimedOut = true;
           controller.abort();
         }, timeoutMs);
+        const abortRequest = () => controller.abort();
+        options?.signal?.addEventListener('abort', abortRequest, {
+          once: true,
+        });
 
         try {
           const response = await fetch(candidateUrl, {
@@ -432,9 +457,10 @@ export class HttpClient {
             return null as T;
           }
 
-          clearTimeout(timeoutId);
-
+          // Receiving headers is not completion: a stalled response body must
+          // remain inside the same request deadline and abort its connection.
           const body = await response.text();
+          clearTimeout(timeoutId);
           const parsed = parseResponseBody(body);
 
           const structuredToolError =
@@ -584,6 +610,10 @@ export class HttpClient {
           return parsed as T;
         } catch (error) {
           clearTimeout(timeoutId);
+          if (options?.signal?.aborted) {
+            lastError = requestCancelledError(options.signal);
+            break requestAttempts;
+          }
           if (error instanceof AuthError || error instanceof DeeplineError) {
             throw error;
           }
@@ -595,6 +625,9 @@ export class HttpClient {
             timeoutMs,
             timedOut: requestTimedOut,
           });
+        } finally {
+          clearTimeout(timeoutId);
+          options?.signal?.removeEventListener('abort', abortRequest);
         }
       }
 
@@ -666,6 +699,7 @@ export class HttpClient {
       RequestOptions,
       | 'retryApiErrors'
       | 'timeout'
+      | 'signal'
       | 'maxRetries'
       | 'exactUrlOnly'
       | 'toolId'
@@ -1087,8 +1121,23 @@ function decodeSseFrame<TEvent extends LiveEventEnvelope>(
   return parsed as TEvent;
 }
 
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(requestCancelledError(signal));
+      return;
+    }
+    const timeoutId = setTimeout(() => {
+      signal?.removeEventListener('abort', abort);
+      resolve();
+    }, ms);
+    const abort = () => {
+      clearTimeout(timeoutId);
+      signal?.removeEventListener('abort', abort);
+      reject(requestCancelledError(signal!));
+    };
+    signal?.addEventListener('abort', abort, { once: true });
+  });
 }
 
 function withCoworkNetworkHint(message: string): string {

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

@@ -124,6 +124,7 @@ export type {
   PlaySheetRowsResult,
   RunsListOptions,
   RunsListPage,
+  RunLifecycleStatus,
   PlaysListOptions,
   PlaysListPage,
   RunsLogsOptions,

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.201',
+  version: '0.3.203',
   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/sdk/src/types.ts

@@ -763,6 +763,14 @@ export interface PlayRunPackage {
     path: string;
     tableNamespace?: string;
     rowCount?: number;
+    /** The materialized dataset count is exact only after this lifecycle completes. */
+    lifecycle?: {
+      phase: 'registered' | 'available' | 'failed';
+      complete: boolean;
+      persistedRowsAtLeast: number;
+      succeededRowsAtLeast: number;
+      failedRowsAtLeast: number;
+    };
     sqlTableName?: string;
     sqlQualifiedTableName?: string;
     recovered?: true;

package/dist/bundling-sources/shared_libs/play-runtime/app-runtime-api.ts

@@ -978,6 +978,9 @@ function isRetryableAppRuntimeAction(
 ): boolean {
   return (
     action === 'append_run_events' ||
+    // Retrying with the same owner refreshes the lock; a different owner
+    // remains excluded by the database predicate even if the first reply was lost.
+    action === 'acquire_runtime_receipt_execution_lock' ||
     // Classification remains replay-safe for the durable outbox even though
     // projectRunEventsViaAppRuntime disables in-process transport retries.
     action === 'project_run_events' ||
@@ -994,8 +997,6 @@ function isRetryableAppRuntimeAction(
     action === 'heartbeat_runtime_step_receipts' ||
     action === 'claim_runtime_step_receipt' ||
     action === 'claim_runtime_step_receipts' ||
-    // Replaying the same owner only renews its existing execution fence.
-    action === 'acquire_runtime_receipt_execution_lock' ||
     action === 'mark_runtime_step_receipt_running' ||
     action === 'mark_runtime_step_receipts_running' ||
     action === 'mark_runtime_step_receipts_queued' ||
@@ -1021,6 +1022,7 @@ function isRuntimeStepReceiptAction(
   action: RuntimeApiRequest['action'],
 ): boolean {
   return (
+    action === 'acquire_runtime_receipt_execution_lock' ||
     action === 'get_runtime_step_receipt' ||
     action === 'get_runtime_step_receipts' ||
     action === 'heartbeat_runtime_step_receipts' ||