deepline 0.1.21 → 0.1.23

package/dist/index.d.mts

@@ -342,7 +342,7 @@ interface ToolMetadata extends ToolDefinition {
 interface PlayRunResult {
     /** `true` if the play completed successfully (`status === 'completed'`). */
     success: boolean;
-    /** Public play-run identifier — use for `play tail` or status polling. */
+    /** Public play-run identifier. */
     runId: string;
     /** The play's return value. Only present on success. */
     result?: unknown;
@@ -363,8 +363,6 @@ interface PlayProgressStatus {
     totalRows?: number;
     /** Accumulated log lines from `ctx.log()`. Grows monotonically. */
     logs: string[];
-    /** Zero-based offset of the first returned log line when a tail cursor is used. */
-    logOffset?: number;
     /** Error message if the play has failed. */
     error?: string;
 }
@@ -399,7 +397,7 @@ interface PlayStatus {
     progress?: PlayProgressStatus;
     /** Partial or final result. Available once the play returns. */
     result?: unknown;
-    /** Temporal-backed run metadata when returned by the status endpoint. */
+    /** Scheduler-backed run metadata when returned by the status endpoint. */
     run?: {
         startTime?: string | null;
         closeTime?: string | null;
@@ -444,9 +442,9 @@ interface StopPlayRunResult {
  * Summary of a single play run, returned by {@link DeeplineClient.listPlayRuns}.
  */
 interface PlayRunListItem {
-    /** Temporal workflow ID. */
+    /** Public Deepline play-run id. */
     workflowId: string;
-    /** Temporal run ID (unique per retry of the same workflow). */
+    /** Backend run attempt id, when exposed. */
     runId: string;
     /** Workflow type (typically `'Workflow'`). */
     type: string;
@@ -564,7 +562,7 @@ interface PlayDefinitionDetail {
     runCount: number;
     /** Primary key column for CSV-based plays. */
     tableNamespace?: string | null;
-    /** Temporal workflow ID of the latest run. */
+    /** Public Deepline id of the latest run. */
     latestRunId?: string | null;
     /** Unix timestamp (ms). */
     createdAt: number;
@@ -677,12 +675,11 @@ interface ClearPlayHistoryResult {
  * ```typescript
  * const started = await client.startPlayRun({ name: 'my-play', input: { domain: 'stripe.com' } });
  * console.log(`Started: ${started.workflowId}`);
- * console.log(`Status URL: ${started.statusUrl}`);
  * console.log(`Dashboard: ${started.dashboardUrl}`);
  * ```
  */
 interface PlayRunStart {
-    /** Temporal workflow ID for tracking this execution. */
+    /** Public Deepline play-run id for tracking this execution. */
     workflowId: string;
     /** Public Deepline play-run API version. */
     apiVersion?: number;
@@ -694,8 +691,6 @@ interface PlayRunStart {
     runtimeBackend?: string;
     /** Canonical run contract compatibility metadata. */
     contract?: Record<string, unknown> | null;
-    /** URL to poll for status updates. */
-    statusUrl?: string;
     /** Dashboard URL for the named play. */
     dashboardUrl?: string;
     /** Terminal status returned when the start request used a short completion wait. */
@@ -706,7 +701,7 @@ interface PlayRunStart {
  *
  * This is the check-only version of play artifact registration: the server runs
  * the same preflight compiler and static-analysis pass without storing,
- * publishing, or starting a Temporal run.
+ * publishing, or starting a play run.
  */
 interface PlayCheckResult {
     valid: boolean;
@@ -773,8 +768,7 @@ interface StartPlayRunRequest {
     waitForCompletionMs?: number;
     /**
      * Per-run execution profile override. The server defaults to `workers_edge`;
-     * tests/benchmarks pass `legacy` or `local` here. Most callers should leave
-     * this unset.
+     * tests can pass `local` here. Most callers should leave this unset.
      */
     profile?: string;
 }
@@ -836,11 +830,7 @@ type RunsListOptions = {
     status?: string;
 };
 type RunsTailOptions = {
-    cursor?: string | number;
-    afterLogIndex?: number;
-    waitMs?: number;
-    terminalOnly?: boolean;
-    compact?: boolean;
+    signal?: AbortSignal;
 };
 type RunsLogsOptions = {
     limit?: number;
@@ -919,7 +909,7 @@ declare class DeeplineClient {
     /**
      * Search available tools using Deepline's ranked backend search.
      *
-     * This is the same discovery surface used by the legacy CLI: it ranks across
+     * This is the same discovery surface used by the CLI: it ranks across
      * tool metadata, categories, agent guidance, and input schema fields.
      */
     searchTools(options?: ToolSearchOptions): Promise<ToolSearchResult>;
@@ -970,7 +960,7 @@ declare class DeeplineClient {
      * `progress.logs`; they are not part of the user output object.
      *
      * @param request - Play run configuration (name, code, input, etc.)
-     * @returns Workflow metadata including the `workflowId` for status polling
+     * @returns Run metadata including the public `workflowId`
      *
      * @example
      * ```typescript
@@ -1160,9 +1150,6 @@ declare class DeeplineClient {
      * Internal/advanced primitive. Public callers should usually prefer
      * {@link runPlay}, {@link PlayJob.get}, or `deepline play run --watch`.
      *
-     * Poll this method until `status` reaches a terminal state:
-     * `'completed'`, `'failed'`, or `'cancelled'`.
-     *
      * @param workflowId - Play-run id from {@link startPlayRun}
      * @returns Current status with progress logs and partial results
      *
@@ -1176,24 +1163,11 @@ declare class DeeplineClient {
     getPlayStatus(workflowId: string, options?: {
         billing?: boolean;
     }): Promise<PlayStatus>;
-    /**
-     * Get the lightweight tail-polling status for a play execution.
-     *
-     * This is intentionally smaller than {@link getPlayStatus}: it returns the
-     * fields needed for CLI log tailing while the run is in flight, without
-     * forcing the API to rebuild final result views on every poll. Call
-     * {@link getPlayStatus} once after a terminal state for the full result.
-     */
-    getPlayTailStatus(workflowId: string, options?: {
-        afterLogIndex?: number;
-        waitMs?: number;
-        terminalOnly?: boolean;
-    }): Promise<PlayStatus>;
     /**
      * Stream semantic play-run events using the same SSE feed as the dashboard.
      *
-     * Consumers should still keep a polling fallback: SSE is the fast live-update
-     * transport, while the status endpoints remain the authoritative recovery path.
+     * The server emits a canonical `play.run.snapshot` event first for every
+     * connection, then incremental live events until terminal state or reconnect.
      */
     streamPlayRunEvents(workflowId: string, options?: {
         signal?: AbortSignal;
@@ -1205,7 +1179,7 @@ declare class DeeplineClient {
      *
      * Sends a stop request for the run.
      *
-     * @param workflowId - Temporal workflow ID to cancel
+     * @param workflowId - Public Deepline play-run id to cancel
      *
      * @example
      * ```typescript
@@ -1216,7 +1190,7 @@ declare class DeeplineClient {
     /**
      * Stop a running play execution, including open HITL waits.
      *
-     * @param workflowId - Temporal workflow ID to stop
+     * @param workflowId - Public Deepline play-run id to stop
      * @param options.reason - Optional audit/debug reason
      */
     stopPlay(workflowId: string, options?: {
@@ -1260,15 +1234,7 @@ declare class DeeplineClient {
      * ```
      */
     listRuns(options: RunsListOptions): Promise<PlayRunListItem[]>;
-    /**
-     * Fetch the lightweight tail status for a run using the public runs resource model.
-     *
-     * This is the SDK equivalent of:
-     *
-     * ```bash
-     * deepline runs tail <run-id> --json
-     * ```
-     */
+    /** Read the canonical run stream and return the latest run snapshot. */
     tailRun(runId: string, options?: RunsTailOptions): Promise<PlayStatus>;
     /**
      * Fetch persisted logs for a run using the public runs resource model.
@@ -1360,11 +1326,11 @@ declare class DeeplineClient {
      */
     deletePlay(name: string): Promise<DeletePlayResult>;
     /**
-     * Run a play end-to-end: submit, poll until terminal, return result.
+     * Run a play end-to-end: submit, stream until terminal, return result.
      *
      * This is the highest-level play execution method. It submits the play,
-     * polls for status updates, and returns a structured result with logs
-     * and timing. Supports cancellation via `AbortSignal`.
+     * reads the canonical run stream 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`
      * @param csvPath - Input CSV path, or `null`
@@ -1380,7 +1346,6 @@ declare class DeeplineClient {
      *     const logs = status.progress?.logs ?? [];
      *     console.log(`[${status.status}] ${logs.length} log lines`);
      *   },
-     *   pollIntervalMs: 1000,
      * });
      *
      * if (result.success) {
@@ -1402,10 +1367,8 @@ declare class DeeplineClient {
      * ```
      */
     runPlay(code: string, csvPath: string | null, name?: string, options?: {
-        /** Called on each poll iteration with the current status. */
+        /** Called for each status snapshot emitted by the run stream. */
         onProgress?: (status: PlayStatus) => void;
-        /** Milliseconds between status polls. Default: `500`. */
-        pollIntervalMs?: number;
         /** Abort signal — triggers cancellation and immediate return. */
         signal?: AbortSignal;
         /** Runtime input for the play function. */
@@ -1436,7 +1399,7 @@ declare class DeeplineClient {
     }>;
 }
 
-declare const SDK_VERSION = "0.1.21";
+declare const SDK_VERSION = "0.1.23";
 declare const SDK_API_CONTRACT = "2026-05-runs-v2";
 
 /**

package/dist/index.d.ts

@@ -342,7 +342,7 @@ interface ToolMetadata extends ToolDefinition {
 interface PlayRunResult {
     /** `true` if the play completed successfully (`status === 'completed'`). */
     success: boolean;
-    /** Public play-run identifier — use for `play tail` or status polling. */
+    /** Public play-run identifier. */
     runId: string;
     /** The play's return value. Only present on success. */
     result?: unknown;
@@ -363,8 +363,6 @@ interface PlayProgressStatus {
     totalRows?: number;
     /** Accumulated log lines from `ctx.log()`. Grows monotonically. */
     logs: string[];
-    /** Zero-based offset of the first returned log line when a tail cursor is used. */
-    logOffset?: number;
     /** Error message if the play has failed. */
     error?: string;
 }
@@ -399,7 +397,7 @@ interface PlayStatus {
     progress?: PlayProgressStatus;
     /** Partial or final result. Available once the play returns. */
     result?: unknown;
-    /** Temporal-backed run metadata when returned by the status endpoint. */
+    /** Scheduler-backed run metadata when returned by the status endpoint. */
     run?: {
         startTime?: string | null;
         closeTime?: string | null;
@@ -444,9 +442,9 @@ interface StopPlayRunResult {
  * Summary of a single play run, returned by {@link DeeplineClient.listPlayRuns}.
  */
 interface PlayRunListItem {
-    /** Temporal workflow ID. */
+    /** Public Deepline play-run id. */
     workflowId: string;
-    /** Temporal run ID (unique per retry of the same workflow). */
+    /** Backend run attempt id, when exposed. */
     runId: string;
     /** Workflow type (typically `'Workflow'`). */
     type: string;
@@ -564,7 +562,7 @@ interface PlayDefinitionDetail {
     runCount: number;
     /** Primary key column for CSV-based plays. */
     tableNamespace?: string | null;
-    /** Temporal workflow ID of the latest run. */
+    /** Public Deepline id of the latest run. */
     latestRunId?: string | null;
     /** Unix timestamp (ms). */
     createdAt: number;
@@ -677,12 +675,11 @@ interface ClearPlayHistoryResult {
  * ```typescript
  * const started = await client.startPlayRun({ name: 'my-play', input: { domain: 'stripe.com' } });
  * console.log(`Started: ${started.workflowId}`);
- * console.log(`Status URL: ${started.statusUrl}`);
  * console.log(`Dashboard: ${started.dashboardUrl}`);
  * ```
  */
 interface PlayRunStart {
-    /** Temporal workflow ID for tracking this execution. */
+    /** Public Deepline play-run id for tracking this execution. */
     workflowId: string;
     /** Public Deepline play-run API version. */
     apiVersion?: number;
@@ -694,8 +691,6 @@ interface PlayRunStart {
     runtimeBackend?: string;
     /** Canonical run contract compatibility metadata. */
     contract?: Record<string, unknown> | null;
-    /** URL to poll for status updates. */
-    statusUrl?: string;
     /** Dashboard URL for the named play. */
     dashboardUrl?: string;
     /** Terminal status returned when the start request used a short completion wait. */
@@ -706,7 +701,7 @@ interface PlayRunStart {
  *
  * This is the check-only version of play artifact registration: the server runs
  * the same preflight compiler and static-analysis pass without storing,
- * publishing, or starting a Temporal run.
+ * publishing, or starting a play run.
  */
 interface PlayCheckResult {
     valid: boolean;
@@ -773,8 +768,7 @@ interface StartPlayRunRequest {
     waitForCompletionMs?: number;
     /**
      * Per-run execution profile override. The server defaults to `workers_edge`;
-     * tests/benchmarks pass `legacy` or `local` here. Most callers should leave
-     * this unset.
+     * tests can pass `local` here. Most callers should leave this unset.
      */
     profile?: string;
 }
@@ -836,11 +830,7 @@ type RunsListOptions = {
     status?: string;
 };
 type RunsTailOptions = {
-    cursor?: string | number;
-    afterLogIndex?: number;
-    waitMs?: number;
-    terminalOnly?: boolean;
-    compact?: boolean;
+    signal?: AbortSignal;
 };
 type RunsLogsOptions = {
     limit?: number;
@@ -919,7 +909,7 @@ declare class DeeplineClient {
     /**
      * Search available tools using Deepline's ranked backend search.
      *
-     * This is the same discovery surface used by the legacy CLI: it ranks across
+     * This is the same discovery surface used by the CLI: it ranks across
      * tool metadata, categories, agent guidance, and input schema fields.
      */
     searchTools(options?: ToolSearchOptions): Promise<ToolSearchResult>;
@@ -970,7 +960,7 @@ declare class DeeplineClient {
      * `progress.logs`; they are not part of the user output object.
      *
      * @param request - Play run configuration (name, code, input, etc.)
-     * @returns Workflow metadata including the `workflowId` for status polling
+     * @returns Run metadata including the public `workflowId`
      *
      * @example
      * ```typescript
@@ -1160,9 +1150,6 @@ declare class DeeplineClient {
      * Internal/advanced primitive. Public callers should usually prefer
      * {@link runPlay}, {@link PlayJob.get}, or `deepline play run --watch`.
      *
-     * Poll this method until `status` reaches a terminal state:
-     * `'completed'`, `'failed'`, or `'cancelled'`.
-     *
      * @param workflowId - Play-run id from {@link startPlayRun}
      * @returns Current status with progress logs and partial results
      *
@@ -1176,24 +1163,11 @@ declare class DeeplineClient {
     getPlayStatus(workflowId: string, options?: {
         billing?: boolean;
     }): Promise<PlayStatus>;
-    /**
-     * Get the lightweight tail-polling status for a play execution.
-     *
-     * This is intentionally smaller than {@link getPlayStatus}: it returns the
-     * fields needed for CLI log tailing while the run is in flight, without
-     * forcing the API to rebuild final result views on every poll. Call
-     * {@link getPlayStatus} once after a terminal state for the full result.
-     */
-    getPlayTailStatus(workflowId: string, options?: {
-        afterLogIndex?: number;
-        waitMs?: number;
-        terminalOnly?: boolean;
-    }): Promise<PlayStatus>;
     /**
      * Stream semantic play-run events using the same SSE feed as the dashboard.
      *
-     * Consumers should still keep a polling fallback: SSE is the fast live-update
-     * transport, while the status endpoints remain the authoritative recovery path.
+     * The server emits a canonical `play.run.snapshot` event first for every
+     * connection, then incremental live events until terminal state or reconnect.
      */
     streamPlayRunEvents(workflowId: string, options?: {
         signal?: AbortSignal;
@@ -1205,7 +1179,7 @@ declare class DeeplineClient {
      *
      * Sends a stop request for the run.
      *
-     * @param workflowId - Temporal workflow ID to cancel
+     * @param workflowId - Public Deepline play-run id to cancel
      *
      * @example
      * ```typescript
@@ -1216,7 +1190,7 @@ declare class DeeplineClient {
     /**
      * Stop a running play execution, including open HITL waits.
      *
-     * @param workflowId - Temporal workflow ID to stop
+     * @param workflowId - Public Deepline play-run id to stop
      * @param options.reason - Optional audit/debug reason
      */
     stopPlay(workflowId: string, options?: {
@@ -1260,15 +1234,7 @@ declare class DeeplineClient {
      * ```
      */
     listRuns(options: RunsListOptions): Promise<PlayRunListItem[]>;
-    /**
-     * Fetch the lightweight tail status for a run using the public runs resource model.
-     *
-     * This is the SDK equivalent of:
-     *
-     * ```bash
-     * deepline runs tail <run-id> --json
-     * ```
-     */
+    /** Read the canonical run stream and return the latest run snapshot. */
     tailRun(runId: string, options?: RunsTailOptions): Promise<PlayStatus>;
     /**
      * Fetch persisted logs for a run using the public runs resource model.
@@ -1360,11 +1326,11 @@ declare class DeeplineClient {
      */
     deletePlay(name: string): Promise<DeletePlayResult>;
     /**
-     * Run a play end-to-end: submit, poll until terminal, return result.
+     * Run a play end-to-end: submit, stream until terminal, return result.
      *
      * This is the highest-level play execution method. It submits the play,
-     * polls for status updates, and returns a structured result with logs
-     * and timing. Supports cancellation via `AbortSignal`.
+     * reads the canonical run stream 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`
      * @param csvPath - Input CSV path, or `null`
@@ -1380,7 +1346,6 @@ declare class DeeplineClient {
      *     const logs = status.progress?.logs ?? [];
      *     console.log(`[${status.status}] ${logs.length} log lines`);
      *   },
-     *   pollIntervalMs: 1000,
      * });
      *
      * if (result.success) {
@@ -1402,10 +1367,8 @@ declare class DeeplineClient {
      * ```
      */
     runPlay(code: string, csvPath: string | null, name?: string, options?: {
-        /** Called on each poll iteration with the current status. */
+        /** Called for each status snapshot emitted by the run stream. */
         onProgress?: (status: PlayStatus) => void;
-        /** Milliseconds between status polls. Default: `500`. */
-        pollIntervalMs?: number;
         /** Abort signal — triggers cancellation and immediate return. */
         signal?: AbortSignal;
         /** Runtime input for the play function. */
@@ -1436,7 +1399,7 @@ declare class DeeplineClient {
     }>;
 }
 
-declare const SDK_VERSION = "0.1.21";
+declare const SDK_VERSION = "0.1.23";
 declare const SDK_API_CONTRACT = "2026-05-runs-v2";
 
 /**