deepline 0.1.91 → 0.1.93

package/dist/index.d.mts

@@ -717,12 +717,19 @@ type PlayLiveEvent = LiveEventEnvelope<unknown> & {
  * Result returned by {@link DeeplineClient.stopPlay}.
  */
 interface StopPlayRunResult {
-    /** Public play-run identifier that was stopped. */
+    /** Public play-run identifier the stop request targeted. */
     runId: string;
-    /** Stop request acknowledgement. */
-    stopped: true;
+    /** Whether the server confirmed the run was stopped. */
+    stopped: boolean;
     /** Number of open HITL interactions marked cancelled. */
     hitlCancelledCount: number;
+    /**
+     * True when the scheduler state for the run was stale and the stop could
+     * not be confirmed. Absent on older servers (treated as confirmed).
+     */
+    staleSchedulerState?: boolean;
+    /** Server-side error detail when the stop was not confirmed. */
+    error?: string;
 }
 /**
  * Summary of a single play run, returned by {@link DeeplineClient.listPlayRuns}.
@@ -1251,10 +1258,28 @@ type RunsListOptions = {
 /** Streaming options for `client.runs.tail(...)`. */
 type RunsTailOptions = {
     signal?: AbortSignal;
+    /**
+     * Called before each stream reconnect. Server stream windows are finite, so
+     * long runs reconnect with backoff until a terminal status is observed.
+     */
+    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).
+     */
+    onNotice?: (message: string) => void;
 };
 /** Log fetch options for `client.runs.logs(...)`. */
 type RunsLogsOptions = {
+    /** Return the LAST `limit` stored log lines (default 200). */
     limit?: number;
+    /** Fetch every stored log line, paginating to the full totalCount. */
+    all?: boolean;
 };
 /** Persisted log response for one play run. */
 type RunsLogsResult = {
@@ -1266,6 +1291,11 @@ type RunsLogsResult = {
     truncated: boolean;
     hasMore: boolean;
     entries: string[];
+    /**
+     * True when the run crossed the Run Log Stream retention cap: `totalCount`
+     * keeps counting, but stored line bodies end at a loud truncation marker.
+     */
+    logsTruncated?: boolean;
 };
 /** One persisted runtime-sheet row returned by `client.runs.exportDatasetRows(...)`. */
 type PlaySheetRow = {
@@ -1804,7 +1834,37 @@ declare class DeeplineClient {
      * ```
      */
     listRuns(options: RunsListOptions): Promise<PlayRunListItem[]>;
-    /** Read the canonical run stream and return the latest run snapshot. */
+    /**
+     * Observe one run's live events through the Convex Run Snapshot
+     * subscription transport (ADR-0008). Yields the same `play.*` event
+     * envelopes as {@link streamPlayRunEvents} and ends after the terminal
+     * snapshot. Throws {@link RunObserveTransportUnavailableError} when this
+     * server cannot serve the transport (older server, unconfigured grants, or
+     * unreachable Convex) — callers fall back to the SSE stream with a notice.
+     */
+    observeRunEvents(runId: string, options?: {
+        signal?: AbortSignal;
+        onNotice?: (message: string) => void;
+    }): AsyncGenerator<PlayLiveEvent>;
+    /**
+     * 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>;
     /**
      * Fetch persisted logs for a run using the public runs resource model.
@@ -2034,6 +2094,15 @@ declare class DeeplineClient {
     }>;
 }
 
+/**
+ * Bootstrap failure: this server/deployment cannot serve the subscription
+ * transport. Callers fall back to the support-window SSE stream (ADR-0008).
+ */
+declare class RunObserveTransportUnavailableError extends Error {
+    readonly reason: string;
+    constructor(message: string, reason: string);
+}
+
 declare const SDK_VERSION: string;
 declare const SDK_API_CONTRACT: string;
 
@@ -3791,4 +3860,4 @@ declare function writeCsvOutputFile(rows: Array<Record<string, unknown>>, stem:
  */
 declare function extractSummaryFields(payload: unknown): Record<string, Scalar>;
 
-export { AuthError, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CsvInput, type CsvOptions, type CustomerDbQueryResult, DEEPLINE_EXTRACTOR_TARGETS, DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, type DatasetColumnDefinition, type DatasetColumnRunInput, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, type DeeplineEmailStatusGetterValue, DeeplineError, type DeeplineExtractorTarget, type DeeplineGetterValue, type DeeplineGetterValueMap, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, type FileInput, JOB_CHANGE_STATUS_VALUES, type JobChangeStatus, type LiveEventEnvelope, PHONE_STATUS_VALUES, 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 PhoneStatus, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayDataset, type PlayDatasetInput, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PreviousCell, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, type RunsListOptions, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, SDK_API_CONTRACT, SDK_VERSION, type StaleAfterSeconds, type StartPlayRunRequest, type StepOptions, type StepProgram, type StepProgramResolver, type StepResolver, type StopPlayRunResult, type ToolDefinition, type ToolExecuteResult, type ToolExecution, type ToolExecutionRequest, type ToolMetadata, type ToolSearchOptions, type ToolSearchResult, defineInput, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isDeeplineExtractorTarget, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };
+export { AuthError, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CsvInput, type CsvOptions, type CustomerDbQueryResult, DEEPLINE_EXTRACTOR_TARGETS, DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, type DatasetColumnDefinition, type DatasetColumnRunInput, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, type DeeplineEmailStatusGetterValue, DeeplineError, type DeeplineExtractorTarget, type DeeplineGetterValue, type DeeplineGetterValueMap, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, type FileInput, JOB_CHANGE_STATUS_VALUES, type JobChangeStatus, type LiveEventEnvelope, PHONE_STATUS_VALUES, 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 PhoneStatus, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayDataset, type PlayDatasetInput, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PreviousCell, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, RunObserveTransportUnavailableError, type RunsListOptions, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, SDK_API_CONTRACT, SDK_VERSION, type StaleAfterSeconds, type StartPlayRunRequest, type StepOptions, type StepProgram, type StepProgramResolver, type StepResolver, type StopPlayRunResult, type ToolDefinition, type ToolExecuteResult, type ToolExecution, type ToolExecutionRequest, type ToolMetadata, type ToolSearchOptions, type ToolSearchResult, defineInput, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isDeeplineExtractorTarget, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };

package/dist/index.d.ts

@@ -717,12 +717,19 @@ type PlayLiveEvent = LiveEventEnvelope<unknown> & {
  * Result returned by {@link DeeplineClient.stopPlay}.
  */
 interface StopPlayRunResult {
-    /** Public play-run identifier that was stopped. */
+    /** Public play-run identifier the stop request targeted. */
     runId: string;
-    /** Stop request acknowledgement. */
-    stopped: true;
+    /** Whether the server confirmed the run was stopped. */
+    stopped: boolean;
     /** Number of open HITL interactions marked cancelled. */
     hitlCancelledCount: number;
+    /**
+     * True when the scheduler state for the run was stale and the stop could
+     * not be confirmed. Absent on older servers (treated as confirmed).
+     */
+    staleSchedulerState?: boolean;
+    /** Server-side error detail when the stop was not confirmed. */
+    error?: string;
 }
 /**
  * Summary of a single play run, returned by {@link DeeplineClient.listPlayRuns}.
@@ -1251,10 +1258,28 @@ type RunsListOptions = {
 /** Streaming options for `client.runs.tail(...)`. */
 type RunsTailOptions = {
     signal?: AbortSignal;
+    /**
+     * Called before each stream reconnect. Server stream windows are finite, so
+     * long runs reconnect with backoff until a terminal status is observed.
+     */
+    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).
+     */
+    onNotice?: (message: string) => void;
 };
 /** Log fetch options for `client.runs.logs(...)`. */
 type RunsLogsOptions = {
+    /** Return the LAST `limit` stored log lines (default 200). */
     limit?: number;
+    /** Fetch every stored log line, paginating to the full totalCount. */
+    all?: boolean;
 };
 /** Persisted log response for one play run. */
 type RunsLogsResult = {
@@ -1266,6 +1291,11 @@ type RunsLogsResult = {
     truncated: boolean;
     hasMore: boolean;
     entries: string[];
+    /**
+     * True when the run crossed the Run Log Stream retention cap: `totalCount`
+     * keeps counting, but stored line bodies end at a loud truncation marker.
+     */
+    logsTruncated?: boolean;
 };
 /** One persisted runtime-sheet row returned by `client.runs.exportDatasetRows(...)`. */
 type PlaySheetRow = {
@@ -1804,7 +1834,37 @@ declare class DeeplineClient {
      * ```
      */
     listRuns(options: RunsListOptions): Promise<PlayRunListItem[]>;
-    /** Read the canonical run stream and return the latest run snapshot. */
+    /**
+     * Observe one run's live events through the Convex Run Snapshot
+     * subscription transport (ADR-0008). Yields the same `play.*` event
+     * envelopes as {@link streamPlayRunEvents} and ends after the terminal
+     * snapshot. Throws {@link RunObserveTransportUnavailableError} when this
+     * server cannot serve the transport (older server, unconfigured grants, or
+     * unreachable Convex) — callers fall back to the SSE stream with a notice.
+     */
+    observeRunEvents(runId: string, options?: {
+        signal?: AbortSignal;
+        onNotice?: (message: string) => void;
+    }): AsyncGenerator<PlayLiveEvent>;
+    /**
+     * 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>;
     /**
      * Fetch persisted logs for a run using the public runs resource model.
@@ -2034,6 +2094,15 @@ declare class DeeplineClient {
     }>;
 }
 
+/**
+ * Bootstrap failure: this server/deployment cannot serve the subscription
+ * transport. Callers fall back to the support-window SSE stream (ADR-0008).
+ */
+declare class RunObserveTransportUnavailableError extends Error {
+    readonly reason: string;
+    constructor(message: string, reason: string);
+}
+
 declare const SDK_VERSION: string;
 declare const SDK_API_CONTRACT: string;
 
@@ -3791,4 +3860,4 @@ declare function writeCsvOutputFile(rows: Array<Record<string, unknown>>, stem:
  */
 declare function extractSummaryFields(payload: unknown): Record<string, Scalar>;
 
-export { AuthError, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CsvInput, type CsvOptions, type CustomerDbQueryResult, DEEPLINE_EXTRACTOR_TARGETS, DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, type DatasetColumnDefinition, type DatasetColumnRunInput, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, type DeeplineEmailStatusGetterValue, DeeplineError, type DeeplineExtractorTarget, type DeeplineGetterValue, type DeeplineGetterValueMap, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, type FileInput, JOB_CHANGE_STATUS_VALUES, type JobChangeStatus, type LiveEventEnvelope, PHONE_STATUS_VALUES, 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 PhoneStatus, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayDataset, type PlayDatasetInput, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PreviousCell, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, type RunsListOptions, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, SDK_API_CONTRACT, SDK_VERSION, type StaleAfterSeconds, type StartPlayRunRequest, type StepOptions, type StepProgram, type StepProgramResolver, type StepResolver, type StopPlayRunResult, type ToolDefinition, type ToolExecuteResult, type ToolExecution, type ToolExecutionRequest, type ToolMetadata, type ToolSearchOptions, type ToolSearchResult, defineInput, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isDeeplineExtractorTarget, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };
+export { AuthError, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CsvInput, type CsvOptions, type CustomerDbQueryResult, DEEPLINE_EXTRACTOR_TARGETS, DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, type DatasetColumnDefinition, type DatasetColumnRunInput, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, type DeeplineEmailStatusGetterValue, DeeplineError, type DeeplineExtractorTarget, type DeeplineGetterValue, type DeeplineGetterValueMap, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, type FileInput, JOB_CHANGE_STATUS_VALUES, type JobChangeStatus, type LiveEventEnvelope, PHONE_STATUS_VALUES, 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 PhoneStatus, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayDataset, type PlayDatasetInput, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PreviousCell, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, RunObserveTransportUnavailableError, type RunsListOptions, type RunsLogsOptions, type RunsLogsResult, type RunsNamespace, type RunsTailOptions, SDK_API_CONTRACT, SDK_VERSION, type StaleAfterSeconds, type StartPlayRunRequest, type StepOptions, type StepProgram, type StepProgramResolver, type StepResolver, type StopPlayRunResult, type ToolDefinition, type ToolExecuteResult, type ToolExecution, type ToolExecutionRequest, type ToolMetadata, type ToolSearchOptions, type ToolSearchResult, defineInput, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isDeeplineExtractorTarget, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, runIf, steps, tryConvertToList, writeCsvOutputFile, writeJsonOutputFile };