deepline 0.3.149 → 0.3.151

package/dist/index.d.mts

@@ -3093,6 +3093,40 @@ type ExecuteToolRawOptions = {
     metadata?: Record<string, unknown>;
     timeout?: number;
     maxRetries?: number;
+    /** Reuse this stable key to recover or retry an ambiguous execution. */
+    idempotencyKey?: string;
+    /** Generate a key and enable recoverable execution before dispatch. */
+    recover?: boolean;
+    /** Called and awaited with the key before the first network request. */
+    onExecution?: (execution: {
+        idempotencyKey: string;
+    }) => void | Promise<void>;
+    /** Maximum time to reconnect to an in-progress keyed execution. Defaults to 15 minutes. */
+    recoveryTimeoutMs?: number;
+};
+/** Durable state returned for a keyed tool execution. */
+type ExecutionRecovery = {
+    /** Stable caller key used to resume or replay this execution. */
+    idempotencyKey: string;
+    /** Whether the execution is still running, completed, or has an unknown provider outcome. */
+    state: 'running' | 'completed' | 'outcome_unknown';
+    /** Whether this response came from an existing durable execution. */
+    replayed: boolean;
+    /** ISO timestamp after which the completed execution can no longer be replayed. */
+    expiresAt?: string;
+};
+/** Durable lookup result for a keyed tool execution. */
+type ExecutionByKeyResult = {
+    /** Recovery state and the key that owns the execution. */
+    executionRecovery: ExecutionRecovery;
+    /** Provider tool associated with the execution. */
+    toolId: string;
+    /** Original server-owned billing request ID, allocated before provider dispatch. */
+    requestId?: string;
+    /** HTTP status saved with the original response, when it was terminal. */
+    responseStatus?: number;
+    /** Saved execution response, when one is available for replay. */
+    response?: unknown;
 };
 /**
  * Standard provider/tool execution envelope returned by low-level SDK calls.
@@ -4521,6 +4555,13 @@ declare class DeeplineClient {
      * Deepline execution envelope.
      */
     executeTool<TData = unknown, TMeta = Record<string, unknown>>(toolId: string, input: Record<string, unknown>, options?: ExecuteToolRawOptions): Promise<ToolExecution<TData, TMeta>>;
+    /** Read the durable state of a keyed tool execution. */
+    getExecutionByKey(idempotencyKey: string): Promise<ExecutionByKeyResult>;
+    private lookupExecutionByKey;
+    /** Public recovery namespace. */
+    get executions(): {
+        getByKey: (key: string) => Promise<ExecutionByKeyResult>;
+    };
     /**
      * Back-compatible alias for {@link executeTool}.
      *
@@ -5970,7 +6011,23 @@ type DeeplineToolsNamespace = {
      * For durable play code, prefer `ctx.tools.execute(...)` because the play
      * runtime records the call under a stable id.
      */
-    execute(toolId: string, input: Record<string, unknown>): Promise<ToolExecuteResult>;
+    execute(toolId: string, input: Record<string, unknown>, options?: {
+        idempotencyKey?: string;
+        recover?: boolean;
+        onExecution?: (execution: {
+            idempotencyKey: string;
+        }) => void | Promise<void>;
+        recoveryTimeoutMs?: number;
+    }): Promise<DeeplineToolExecuteResult>;
+};
+type DeeplineToolExecuteResult = ToolExecuteResult & {
+    /** Stable key used to recover this direct tool execution, when enabled. */
+    idempotencyKey?: string;
+    executionRecovery?: ExecutionRecovery;
+};
+type DeeplineExecutionsNamespace = {
+    /** Look up a recoverable tool execution by its stable idempotency key. */
+    getByKey(idempotencyKey: string): Promise<ExecutionByKeyResult>;
 };
 /**
  * Named-play discovery and handle operations from a connected {@link DeeplineContext}.
@@ -6099,6 +6156,8 @@ declare class DeeplineContext {
      * ```
      */
     get tools(): DeeplineToolsNamespace;
+    /** Durable state for recoverable direct tool executions. */
+    get executions(): DeeplineExecutionsNamespace;
     /**
      * Play discovery and named-play handles.
      *
@@ -6592,4 +6651,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 BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type BillingTopUpResult, type BillingUsageEvent, 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 DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, 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 PlayReferenceLike, type PlayRevisionSummary, type PlayRunActionPackage, type PlayRunActivityProjection, type PlayRunDatasetActions, type PlayRunId, type PlayRunPackage, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PlaysListOptions, type PlaysListPage, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type RerunOptions, type RerunPlayRunResult, type ResolvedConfig, 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 BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type BillingTopUpResult, type BillingUsageEvent, 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 PlayReferenceLike, type PlayRevisionSummary, type PlayRunActionPackage, type PlayRunActivityProjection, type PlayRunDatasetActions, type PlayRunId, type PlayRunPackage, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PlaysListOptions, type PlaysListPage, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type RerunOptions, type RerunPlayRunResult, type ResolvedConfig, 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 };

package/dist/index.d.ts

@@ -3093,6 +3093,40 @@ type ExecuteToolRawOptions = {
     metadata?: Record<string, unknown>;
     timeout?: number;
     maxRetries?: number;
+    /** Reuse this stable key to recover or retry an ambiguous execution. */
+    idempotencyKey?: string;
+    /** Generate a key and enable recoverable execution before dispatch. */
+    recover?: boolean;
+    /** Called and awaited with the key before the first network request. */
+    onExecution?: (execution: {
+        idempotencyKey: string;
+    }) => void | Promise<void>;
+    /** Maximum time to reconnect to an in-progress keyed execution. Defaults to 15 minutes. */
+    recoveryTimeoutMs?: number;
+};
+/** Durable state returned for a keyed tool execution. */
+type ExecutionRecovery = {
+    /** Stable caller key used to resume or replay this execution. */
+    idempotencyKey: string;
+    /** Whether the execution is still running, completed, or has an unknown provider outcome. */
+    state: 'running' | 'completed' | 'outcome_unknown';
+    /** Whether this response came from an existing durable execution. */
+    replayed: boolean;
+    /** ISO timestamp after which the completed execution can no longer be replayed. */
+    expiresAt?: string;
+};
+/** Durable lookup result for a keyed tool execution. */
+type ExecutionByKeyResult = {
+    /** Recovery state and the key that owns the execution. */
+    executionRecovery: ExecutionRecovery;
+    /** Provider tool associated with the execution. */
+    toolId: string;
+    /** Original server-owned billing request ID, allocated before provider dispatch. */
+    requestId?: string;
+    /** HTTP status saved with the original response, when it was terminal. */
+    responseStatus?: number;
+    /** Saved execution response, when one is available for replay. */
+    response?: unknown;
 };
 /**
  * Standard provider/tool execution envelope returned by low-level SDK calls.
@@ -4521,6 +4555,13 @@ declare class DeeplineClient {
      * Deepline execution envelope.
      */
     executeTool<TData = unknown, TMeta = Record<string, unknown>>(toolId: string, input: Record<string, unknown>, options?: ExecuteToolRawOptions): Promise<ToolExecution<TData, TMeta>>;
+    /** Read the durable state of a keyed tool execution. */
+    getExecutionByKey(idempotencyKey: string): Promise<ExecutionByKeyResult>;
+    private lookupExecutionByKey;
+    /** Public recovery namespace. */
+    get executions(): {
+        getByKey: (key: string) => Promise<ExecutionByKeyResult>;
+    };
     /**
      * Back-compatible alias for {@link executeTool}.
      *
@@ -5970,7 +6011,23 @@ type DeeplineToolsNamespace = {
      * For durable play code, prefer `ctx.tools.execute(...)` because the play
      * runtime records the call under a stable id.
      */
-    execute(toolId: string, input: Record<string, unknown>): Promise<ToolExecuteResult>;
+    execute(toolId: string, input: Record<string, unknown>, options?: {
+        idempotencyKey?: string;
+        recover?: boolean;
+        onExecution?: (execution: {
+            idempotencyKey: string;
+        }) => void | Promise<void>;
+        recoveryTimeoutMs?: number;
+    }): Promise<DeeplineToolExecuteResult>;
+};
+type DeeplineToolExecuteResult = ToolExecuteResult & {
+    /** Stable key used to recover this direct tool execution, when enabled. */
+    idempotencyKey?: string;
+    executionRecovery?: ExecutionRecovery;
+};
+type DeeplineExecutionsNamespace = {
+    /** Look up a recoverable tool execution by its stable idempotency key. */
+    getByKey(idempotencyKey: string): Promise<ExecutionByKeyResult>;
 };
 /**
  * Named-play discovery and handle operations from a connected {@link DeeplineContext}.
@@ -6099,6 +6156,8 @@ declare class DeeplineContext {
      * ```
      */
     get tools(): DeeplineToolsNamespace;
+    /** Durable state for recoverable direct tool executions. */
+    get executions(): DeeplineExecutionsNamespace;
     /**
      * Play discovery and named-play handles.
      *
@@ -6592,4 +6651,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 BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type BillingTopUpResult, type BillingUsageEvent, 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 DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplinePlaysNamespace, type DeeplineToolCategory, type DeeplineToolsNamespace, type DefinePlayConfig, type DefinedPlay, 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 PlayReferenceLike, type PlayRevisionSummary, type PlayRunActionPackage, type PlayRunActivityProjection, type PlayRunDatasetActions, type PlayRunId, type PlayRunPackage, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PlaysListOptions, type PlaysListPage, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type RerunOptions, type RerunPlayRunResult, type ResolvedConfig, 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 BillingSubscriptionCancelResult, type BillingSubscriptionStatus, type BillingTopUpResult, type BillingUsageEvent, 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 PlayReferenceLike, type PlayRevisionSummary, type PlayRunActionPackage, type PlayRunActivityProjection, type PlayRunDatasetActions, type PlayRunId, type PlayRunPackage, type PlayRunResult, type PlayRunStart, type PlaySheetRow, type PlaySheetRowsResult, type PlayStatus, type PlayStepProgramStep, type PlaysListOptions, type PlaysListPage, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type RerunOptions, type RerunPlayRunResult, type ResolvedConfig, 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 };

package/dist/index.js

@@ -864,7 +864,7 @@ var 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.149",
+  version: "0.3.151",
   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: {
     updatePreferences: 1
@@ -1605,6 +1605,11 @@ var HttpClient = class {
             body: options?.formData !== void 0 ? typeof options.formData === "function" ? options.formData() : options.formData : options?.body !== void 0 ? JSON.stringify(options.body) : void 0,
             signal: controller.signal
           });
+          options?.onResponse?.(response);
+          if (response.status === 404 && options?.allowNotFound) {
+            clearTimeout(timeoutId);
+            return null;
+          }
           clearTimeout(timeoutId);
           const body = await response.text();
           const parsed = parseResponseBody(body);
@@ -1744,7 +1749,8 @@ var HttpClient = class {
             retryAfterMs: null,
             networkKind: code === "NETWORK_TIMEOUT" ? "timeout" : code === "NETWORK_ABORTED" ? "unknown" : "unavailable",
             networkScope: "client_to_deepline",
-            details: mappedNetworkError.details
+            details: mappedNetworkError.details,
+            publicDetails: options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : null
           }
         ),
         lastError
@@ -4223,6 +4229,56 @@ var MONITOR_NON_RETRYABLE_MUTATION_OPTIONS = {
   exactUrlOnly: true
 };
 var RAW_V2_EXECUTE_RESPONSE_CONTRACT = RAW_V2_TOOL_RESPONSE_CONTRACT;
+var DEFAULT_EXECUTION_RECOVERY_TIMEOUT_MS = 15 * 60 * 1e3;
+function validateExecutionIdempotencyKey(key) {
+  if (typeof key !== "string" || key.length < 1 || key.length > 200 || !/^[A-Za-z0-9._:-]+$/.test(key)) {
+    throw new DeeplineError(
+      "Execution idempotency keys must be 1\u2013200 ASCII letters, digits, dots, underscores, colons, or hyphens.",
+      void 0,
+      "IDEMPOTENCY_KEY_INVALID"
+    );
+  }
+}
+function isExecutionInProgressResponse(value) {
+  return typeof value === "object" && value !== null && typeof value.executionRecovery === "object" && value.executionRecovery.state === "running";
+}
+function getExecutionRecoveryState(value) {
+  if (typeof value !== "object" || value === null || typeof value.executionRecovery !== "object") {
+    return null;
+  }
+  const state = value.executionRecovery.state;
+  return state === "running" || state === "completed" || state === "outcome_unknown" ? state : null;
+}
+function isRecoverableExecutionAttemptError(error) {
+  if (error instanceof ToolExecutionError) {
+    return error.code === "EXECUTION_IN_PROGRESS" || error.origin === "deepline" && error.category === "network" && error.networkScope === "client_to_deepline";
+  }
+  return error instanceof DeeplineError && (error.code === "EXECUTION_IN_PROGRESS" || error.code?.startsWith("NETWORK_") === true && error.statusCode === void 0);
+}
+function isRecoverableExecutionLookupError(error) {
+  if (isRecoverableExecutionAttemptError(error)) return true;
+  return error instanceof DeeplineError && (error.statusCode === 429 || error.statusCode !== void 0 && error.statusCode >= 500);
+}
+function timeoutWithinRecoveryBudget(requestTimeoutMs, defaultRequestTimeoutMs, remainingMs) {
+  return Math.min(requestTimeoutMs ?? defaultRequestTimeoutMs, remainingMs);
+}
+function executionRecoveryError(input) {
+  return new ToolExecutionError(input.message, {
+    toolId: input.toolId,
+    provider: null,
+    operation: input.toolId,
+    code: input.code,
+    origin: "deepline",
+    category: input.code === "EXECUTION_OUTCOME_UNKNOWN" ? "unknown" : "conflict",
+    retryable: input.code !== "EXECUTION_OUTCOME_UNKNOWN",
+    statusCode: null,
+    requestId: null,
+    retryAfterMs: null,
+    networkKind: null,
+    networkScope: null,
+    publicDetails: { idempotencyKey: input.idempotencyKey }
+  });
+}
 var COMPILE_MANIFEST_RETRY_DELAYS_MS = [250, 1e3];
 var REGISTER_PLAY_ARTIFACTS_COMPILE_CONCURRENCY = 3;
 var REGISTER_PLAY_ARTIFACTS_MAX_BATCH_COUNT = 3;
@@ -5157,29 +5213,183 @@ var DeeplineClient = class _DeeplineClient {
    * Deepline execution envelope.
    */
   async executeTool(toolId, input, options) {
+    const inputSnapshot = JSON.parse(JSON.stringify(input));
+    const metadataSnapshot = options?.metadata ? JSON.parse(JSON.stringify(options.metadata)) : void 0;
+    const idempotencyKey = options?.idempotencyKey ?? (options?.recover ? crypto.randomUUID() : void 0);
+    if (idempotencyKey !== void 0) {
+      validateExecutionIdempotencyKey(idempotencyKey);
+      if (options?.recoveryTimeoutMs !== void 0 && (!Number.isFinite(options.recoveryTimeoutMs) || options.recoveryTimeoutMs < 0)) {
+        throw new DeeplineError(
+          "recoveryTimeoutMs must be a finite, non-negative number.",
+          void 0,
+          "IDEMPOTENCY_KEY_INVALID"
+        );
+      }
+      await options?.onExecution?.({ idempotencyKey });
+      const timeoutMs2 = options?.timeout ?? resolveToolExecuteTimeoutMs(toolId, inputSnapshot);
+      await this.lookupExecutionByKey(idempotencyKey, timeoutMs2);
+    }
+    const timeoutMs = options?.timeout ?? resolveToolExecuteTimeoutMs(toolId, inputSnapshot);
     const headers = {
       [EXECUTE_RESPONSE_CONTRACT_HEADER]: RAW_V2_EXECUTE_RESPONSE_CONTRACT,
       [TOOL_EXECUTION_ERROR_SCHEMA_HEADER]: String(
         TOOL_EXECUTION_ERROR_SCHEMA_VERSION
       ),
       ...options?.includeToolMetadata ? { [INCLUDE_TOOL_METADATA_HEADER]: "true" } : {},
-      [EXECUTE_RESPONSE_INTENT_HEADER]: options?.responseIntent ?? "raw"
+      [EXECUTE_RESPONSE_INTENT_HEADER]: options?.responseIntent ?? "raw",
+      ...idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}
     };
-    const response = await this.http.post(
+    const request = (requestTimeoutMs) => this.http.post(
       `/api/v2/integrations/${encodeURIComponent(toolId)}/execute`,
       {
-        payload: input,
-        ...options?.metadata ? { metadata: options.metadata } : {}
+        payload: inputSnapshot,
+        ...metadataSnapshot ? { metadata: metadataSnapshot } : {}
       },
       headers,
       {
-        timeout: options?.timeout ?? resolveToolExecuteTimeoutMs(toolId, input),
-        maxRetries: options?.maxRetries ?? 0,
+        timeout: requestTimeoutMs,
+        maxRetries: idempotencyKey ? 0 : options?.maxRetries ?? 0,
+        exactUrlOnly: true,
+        toolId,
+        idempotencyKey
+      }
+    );
+    let response;
+    let recoveryDeadline = null;
+    const recoveryTimeoutMs = options?.recoveryTimeoutMs ?? DEFAULT_EXECUTION_RECOVERY_TIMEOUT_MS;
+    let retryDelayMs = 1e3;
+    const recoveryTimeoutError = () => executionRecoveryError({
+      toolId,
+      idempotencyKey,
+      code: "EXECUTION_RECOVERY_TIMEOUT",
+      message: `Execution recovery for ${idempotencyKey} did not finish before the recovery timeout. Inspect client.executions.getByKey() and resume with the same idempotency key.`
+    });
+    const waitForRecoveryRetry = async (deadline) => {
+      const remainingMs = deadline - Date.now();
+      if (remainingMs <= 0) throw recoveryTimeoutError();
+      await new Promise(
+        (resolve2) => setTimeout(resolve2, Math.min(retryDelayMs, remainingMs))
+      );
+      retryDelayMs = Math.min(retryDelayMs * 2, 5e3);
+    };
+    const lookupDuringRecovery = async () => {
+      while (true) {
+        const remainingMs = recoveryDeadline - Date.now();
+        if (remainingMs <= 0) throw recoveryTimeoutError();
+        try {
+          return await this.lookupExecutionByKey(
+            idempotencyKey,
+            timeoutWithinRecoveryBudget(
+              timeoutMs,
+              this.config.timeout,
+              remainingMs
+            )
+          );
+        } catch (error) {
+          if (!isRecoverableExecutionLookupError(error)) throw error;
+          await waitForRecoveryRetry(recoveryDeadline);
+        }
+      }
+    };
+    while (true) {
+      const remainingMs = recoveryDeadline === null ? null : recoveryDeadline - Date.now();
+      if (remainingMs !== null && remainingMs <= 0) {
+        throw recoveryTimeoutError();
+      }
+      try {
+        response = await request(
+          remainingMs === null ? timeoutMs : timeoutWithinRecoveryBudget(
+            timeoutMs,
+            this.config.timeout,
+            remainingMs
+          )
+        );
+        if (getExecutionRecoveryState(response) === "outcome_unknown") {
+          if (!idempotencyKey) break;
+          throw executionRecoveryError({
+            toolId,
+            idempotencyKey,
+            code: "EXECUTION_OUTCOME_UNKNOWN",
+            message: `The outcome of execution ${idempotencyKey} is unknown. Do not retry with a new key; inspect client.executions.getByKey().`
+          });
+        }
+        if (!idempotencyKey || !isExecutionInProgressResponse(response)) {
+          break;
+        }
+        if (recoveryDeadline === null) {
+          recoveryDeadline = Date.now() + recoveryTimeoutMs;
+        }
+      } catch (error) {
+        if (idempotencyKey && error instanceof DeeplineError && error.code === "EXECUTION_OUTCOME_UNKNOWN") {
+          throw executionRecoveryError({
+            toolId,
+            idempotencyKey,
+            code: "EXECUTION_OUTCOME_UNKNOWN",
+            message: error.message
+          });
+        }
+        if (!idempotencyKey || !isRecoverableExecutionAttemptError(error)) {
+          throw error;
+        }
+        if (recoveryDeadline === null) {
+          recoveryDeadline = Date.now() + recoveryTimeoutMs;
+        }
+      }
+      await waitForRecoveryRetry(recoveryDeadline);
+      const recovered = await lookupDuringRecovery();
+      if (getExecutionRecoveryState(recovered) === "outcome_unknown") {
+        throw executionRecoveryError({
+          toolId,
+          idempotencyKey,
+          code: "EXECUTION_OUTCOME_UNKNOWN",
+          message: `The outcome of execution ${idempotencyKey} is unknown. Do not retry with a new key; inspect client.executions.getByKey().`
+        });
+      }
+    }
+    const materialized = materializeToolExecutionResponse(response);
+    return idempotencyKey ? { ...materialized, idempotencyKey } : materialized;
+  }
+  /** Read the durable state of a keyed tool execution. */
+  async getExecutionByKey(idempotencyKey) {
+    validateExecutionIdempotencyKey(idempotencyKey);
+    const result = await this.lookupExecutionByKey(idempotencyKey);
+    if (!result) {
+      throw new DeeplineError(
+        `No execution exists for idempotency key ${idempotencyKey}.`,
+        404,
+        "EXECUTION_NOT_FOUND"
+      );
+    }
+    return result;
+  }
+  async lookupExecutionByKey(idempotencyKey, timeoutMs) {
+    validateExecutionIdempotencyKey(idempotencyKey);
+    let supported = false;
+    const result = await this.http.get(
+      `/api/v2/executions/by-key/${encodeURIComponent(idempotencyKey)}`,
+      {
         exactUrlOnly: true,
-        toolId
+        maxRetries: 0,
+        timeout: timeoutMs,
+        idempotencyKey,
+        allowNotFound: true,
+        onResponse: (response) => {
+          supported = response.headers.get("X-Deepline-Idempotency-Supported") === "true";
+        }
       }
     );
-    return materializeToolExecutionResponse(response);
+    if (!supported) {
+      throw new DeeplineError(
+        "This Deepline server does not support recoverable tool executions; no tool was dispatched.",
+        422,
+        "IDEMPOTENCY_NOT_SUPPORTED"
+      );
+    }
+    return result;
+  }
+  /** Public recovery namespace. */
+  get executions() {
+    return { getByKey: (key) => this.getExecutionByKey(key) };
   }
   /**
    * Back-compatible alias for {@link executeTool}.
@@ -11266,10 +11476,11 @@ var DeeplineContext = class {
       /** Get detailed metadata for a tool. */
       get: (toolId) => this.client.getTool(toolId),
       /** Execute a tool and return the standard execution envelope. */
-      execute: async (toolId, input) => {
+      execute: async (toolId, input, options) => {
         const response = await this.client.executeTool(toolId, input, {
           includeToolMetadata: true,
-          responseIntent: "dataset"
+          responseIntent: "dataset",
+          ...options
         });
         return toolExecutionEnvelopeToResult(toolId, response, {
           client: this.client,
@@ -11278,6 +11489,10 @@ var DeeplineContext = class {
       }
     };
   }
+  /** Durable state for recoverable direct tool executions. */
+  get executions() {
+    return { getByKey: (key) => this.client.getExecutionByKey(key) };
+  }
   /**
    * Play discovery and named-play handles.
    *
@@ -11585,7 +11800,7 @@ function toolExecutionEnvelopeToResult(fallbackToolId, response, options) {
   const meta = response.toolResponse?.meta;
   const metadata = isRecord9(response._metadata) ? response._metadata.tool : null;
   const toolMetadata = isRecord9(metadata) ? metadata : {};
-  return attachSdkQueryResultDatasetResult(
+  const result = attachSdkQueryResultDatasetResult(
     fallbackToolId,
     createToolExecuteResult({
       status: typeof response.status === "string" ? response.status : "completed",
@@ -11618,6 +11833,14 @@ function toolExecutionEnvelopeToResult(fallbackToolId, response, options) {
     }),
     options
   );
+  const executionRecovery = isRecord9(response.executionRecovery) ? response.executionRecovery : void 0;
+  if (typeof response.idempotencyKey === "string") {
+    result.idempotencyKey = response.idempotencyKey;
+  }
+  if (executionRecovery) {
+    result.executionRecovery = executionRecovery;
+  }
+  return result;
 }
 function defineInput(schema) {
   return createPlayInputContract(schema);