deepline 0.1.85 → 0.1.89

package/dist/index.d.mts

@@ -13,7 +13,17 @@ declare const PLAY_ARTIFACT_KINDS: {
 };
 type PlayArtifactKind = (typeof PLAY_ARTIFACT_KINDS)[keyof typeof PLAY_ARTIFACT_KINDS];
 
-interface PlayStaticPipelineSnapshot {
+/**
+ * A top-level key the play's function literally `return`s. Derived from the
+ * `return { ... }` object literal — NOT from dataset `.withColumn(...)` names —
+ * so the "Returns" graph node mirrors the function's real output shape.
+ * `isDataset` is true when the key's value is a `PlayDataset` handle (a table).
+ */
+interface PlayStaticReturnField {
+    name: string;
+    isDataset: boolean;
+}
+interface PlayStaticPipeline {
     tableNamespace?: string;
     inputFields?: string[];
     rowKeyFields?: string[];
@@ -22,16 +32,22 @@ interface PlayStaticPipelineSnapshot {
     csvDescription?: string;
     datasetDescription?: string;
     fields: string[];
-    stages?: PlayStaticSubstepSnapshot[];
-    substeps: PlayStaticSubstepSnapshot[];
-    sheetContract?: PlaySheetContractSnapshot | null;
+    /**
+     * Top-level keys of the play's `return { ... }` object literal, in source
+     * order. Undefined when the terminal return isn't a statically-known object
+     * literal (bare value, dataset handle, conditional returns, etc.).
+     */
+    returnFields?: PlayStaticReturnField[];
+    stages?: PlayStaticSubstep[];
+    substeps: PlayStaticSubstep[];
+    sheetContract?: PlaySheetContract | null;
     sheetContractErrors?: string[];
 }
-type PlaySheetColumnSourceSnapshot = 'input' | 'datasetColumn' | 'waterfallStep' | 'childPlayColumn';
-interface PlaySheetColumnContractSnapshot {
+type PlaySheetColumnSource = 'input' | 'datasetColumn' | 'waterfallStep' | 'childPlayColumn';
+interface PlaySheetColumnContract {
     id: string;
     sqlName: string;
-    source: PlaySheetColumnSourceSnapshot;
+    source: PlaySheetColumnSource;
     field?: string;
     parentField?: string;
     playId?: string;
@@ -42,44 +58,49 @@ interface PlaySheetColumnContractSnapshot {
     toolId?: string;
     isRowKey?: boolean;
 }
-interface PlaySheetContractSnapshot {
+interface PlaySheetContract {
     tableNamespace: string;
-    columns: PlaySheetColumnContractSnapshot[];
+    columns: PlaySheetColumnContract[];
 }
-type PlayStaticColumnProducerKindSnapshot = 'tool' | 'waterfall' | 'stepProgram' | 'playCall' | 'controlFlow' | 'transform';
-interface PlayStaticColumnProducerSnapshot {
+type PlayStaticColumnProducerKind = 'tool' | 'waterfall' | 'stepProgram' | 'playCall' | 'controlFlow' | 'transform';
+interface PlayStaticColumnProducer {
     id: string;
-    kind: PlayStaticColumnProducerKindSnapshot;
+    kind: PlayStaticColumnProducerKind;
     field: string;
     toolId?: string;
     playId?: string;
+    dependsOnFields?: string[];
+    staleAfterSeconds?: number;
     conditional?: boolean;
-    sourceRange?: PlayStaticSourceRangeSnapshot;
-    steps?: PlayStaticColumnProducerSnapshot[];
-    substep: PlayStaticSubstepSnapshot;
+    sourceRange?: PlayStaticSourceRange;
+    steps?: PlayStaticColumnProducer[];
+    substep: PlayStaticSubstep;
 }
-interface PlayStaticDatasetColumnSnapshot {
+interface PlayStaticDatasetColumn {
     id: string;
-    source: PlaySheetColumnSourceSnapshot;
+    source: PlaySheetColumnSource;
     sqlName?: string;
-    producers: PlayStaticColumnProducerSnapshot[];
+    staleAfterSeconds?: number;
+    producers: PlayStaticColumnProducer[];
 }
-interface PlayStaticSourceRangeSnapshot {
+interface PlayStaticSourceRange {
     sourcePath?: string;
     startLine: number;
     endLine: number;
     startColumn: number;
     endColumn: number;
 }
-type PlayStaticSubstepMetadataSnapshot = {
+type PlayStaticSubstepMetadata = {
     conditional?: boolean;
+    dependsOnFields?: string[];
+    staleAfterSeconds?: number;
 };
-type PlayStaticSubstepSnapshot = PlayStaticSubstepMetadataSnapshot & ({
+type PlayStaticSubstep = PlayStaticSubstepMetadata & ({
     type: 'csv';
     field: string;
     path?: string;
     description?: string;
-    sourceRange?: PlayStaticSourceRangeSnapshot;
+    sourceRange?: PlayStaticSourceRange;
     callDepth?: number;
     callPath?: string[];
 } | {
@@ -90,22 +111,24 @@ type PlayStaticSubstepSnapshot = PlayStaticSubstepMetadataSnapshot & ({
     inputFields?: string[];
     rowKeyFields?: string[];
     outputFields?: string[];
-    columns?: PlayStaticDatasetColumnSnapshot[];
+    columns?: PlayStaticDatasetColumn[];
     waterfallIds?: string[];
-    steps?: PlayStaticSubstepSnapshot[];
-    sheetContract?: PlaySheetContractSnapshot | null;
+    steps?: PlayStaticSubstep[];
+    sheetContract?: PlaySheetContract | null;
     description?: string;
-    sourceRange?: PlayStaticSourceRangeSnapshot;
+    sourceRange?: PlayStaticSourceRange;
     callDepth?: number;
     callPath?: string[];
 } | {
     type: 'tool';
     toolId: string;
     field: string;
+    paramsSource?: string;
+    sourceText?: string;
     description?: string;
     inLoop?: boolean;
     isEventWait?: boolean;
-    sourceRange?: PlayStaticSourceRangeSnapshot;
+    sourceRange?: PlayStaticSourceRange;
     callDepth?: number;
     callPath?: string[];
 } | {
@@ -124,16 +147,16 @@ type PlayStaticSubstepSnapshot = PlayStaticSubstepMetadataSnapshot & ({
         paramsSource?: string;
     }>;
     description?: string;
-    sourceRange?: PlayStaticSourceRangeSnapshot;
+    sourceRange?: PlayStaticSourceRange;
     callDepth?: number;
     callPath?: string[];
 } | {
     type: 'step_suite';
     field: string;
-    steps: PlayStaticSubstepSnapshot[];
+    steps: PlayStaticSubstep[];
     returnSource?: string;
     description?: string;
-    sourceRange?: PlayStaticSourceRangeSnapshot;
+    sourceRange?: PlayStaticSourceRange;
     callDepth?: number;
     callPath?: string[];
 } | {
@@ -141,37 +164,40 @@ type PlayStaticSubstepSnapshot = PlayStaticSubstepMetadataSnapshot & ({
     playId: string;
     field: string;
     inLoop?: boolean;
-    pipeline?: PlayStaticPipelineSnapshot | null;
+    pipeline?: PlayStaticPipeline | null;
     cycleDetected?: boolean;
     resolutionError?: string;
     description?: string;
-    sourceRange?: PlayStaticSourceRangeSnapshot;
+    sourceRange?: PlayStaticSourceRange;
     callDepth?: number;
     callPath?: string[];
 } | {
     type: 'control_flow';
     kind: 'conditional' | 'loop';
     field: string;
-    steps: PlayStaticSubstepSnapshot[];
+    steps: PlayStaticSubstep[];
     description?: string;
-    sourceRange?: PlayStaticSourceRangeSnapshot;
+    sourceRange?: PlayStaticSourceRange;
     callDepth?: number;
     callPath?: string[];
 } | {
     type: 'run_javascript';
     alias: string;
+    sourceText?: string;
     description?: string;
-    sourceRange?: PlayStaticSourceRangeSnapshot;
+    sourceRange?: PlayStaticSourceRange;
     callDepth?: number;
     callPath?: string[];
 } | {
     type: 'code';
     field: string;
+    sourceText?: string;
     description?: string;
-    sourceRange?: PlayStaticSourceRangeSnapshot;
+    sourceRange?: PlayStaticSourceRange;
     callDepth?: number;
     callPath?: string[];
 });
+
 type PlayCompilerDependencyManifest = {
     playName: string;
     /** Original source path for direct imported definePlay dependencies. */
@@ -179,7 +205,7 @@ type PlayCompilerDependencyManifest = {
     sourceHash: string;
     graphHash: string;
     artifactHash: string;
-    staticPipeline: PlayStaticPipelineSnapshot;
+    staticPipeline: PlayStaticPipeline;
 };
 type PlayCompilerManifest = {
     compilerVersion: number;
@@ -188,7 +214,7 @@ type PlayCompilerManifest = {
     graphHash: string;
     artifactHash: string;
     artifactKind?: PlayArtifactKind;
-    staticPipeline: PlayStaticPipelineSnapshot;
+    staticPipeline: PlayStaticPipeline;
     importedPlayDependencies: PlayCompilerDependencyManifest[];
 };
 
@@ -267,17 +293,33 @@ interface ResolvedConfig {
     /** Max retry count for transient failures. */
     maxRetries: number;
 }
+/** Column metadata returned by a customer data query. */
 interface CustomerDbColumn {
+    /** Column name as returned by the database. */
     name: string;
+    /** Internal table identifier when available. */
     table_id: number | null;
+    /** Internal data-type identifier when available. */
     data_type_id: number | null;
 }
+/**
+ * Result returned by {@link DeeplineClient.queryCustomerDb}.
+ *
+ * Rows are intentionally untyped because the schema depends on the caller's SQL
+ * query and selected customer tables.
+ */
 interface CustomerDbQueryResult {
+    /** Database command executed by the query endpoint. */
     command: string;
+    /** Total affected row count when reported by the database. */
     row_count: number | null;
+    /** Number of rows included in this response. */
     row_count_returned: number;
+    /** Whether server-side row limits truncated the result. */
     truncated: boolean;
+    /** Column metadata for the returned rows. */
     columns: CustomerDbColumn[];
+    /** Result rows. */
     rows: unknown[];
 }
 interface ToolPricingSummary {
@@ -297,6 +339,13 @@ interface ToolPricingSummary {
     details: string[];
 }
 
+/**
+ * Summary definition of a callable provider-backed tool.
+ *
+ * Returned by {@link DeeplineClient.listTools} and ranked tool search. Use
+ * `getTool(toolId)` or the matching HTTP describe route for provider-specific
+ * schema, examples, pricing, and extraction guidance before executing.
+ */
 interface ToolDefinition {
     /** Unique tool identifier used in API calls (e.g. `"apollo_people_search"`). */
     toolId: string;
@@ -394,28 +443,53 @@ interface ToolDefinition {
         term?: string;
     }>;
 }
+/**
+ * Query options for ranked tool/provider discovery.
+ */
 interface ToolSearchOptions {
+    /** Free-text search query. */
     query?: string;
+    /** Comma-separated category filter such as `company_search` or `email_finder`. */
     categories?: string;
+    /** Optional explicit search terms used by agent/CLI callers. */
     searchTerms?: string;
+    /** Search algorithm/version. Defaults to the current ranked mode. */
     searchMode?: 'v1' | 'v2';
+    /** Include backend debug metadata in the search response. */
     includeSearchDebug?: boolean;
 }
+/**
+ * Ranked tool/provider discovery response.
+ *
+ * Includes matching tools plus render/action hints used by the CLI and agents.
+ */
 interface ToolSearchResult {
+    /** Ranked matching tools. */
     tools: ToolDefinition[];
+    /** Count included in this response when available. */
     count?: number;
+    /** Total available count when the backend reports it. */
     total?: number;
+    /** Whether results were truncated by server-side limits. */
     truncated?: boolean;
+    /** Echoed query. */
     query?: string;
+    /** Parsed category filters. */
     categories?: string[];
+    /** Parsed search terms. */
     search_terms?: string[];
+    /** Search mode used. */
     search_mode?: 'v1' | 'v2';
+    /** Whether search fell back to category matching. */
     search_fallback_to_category?: boolean;
+    /** Hint explaining omitted play results when searching tools only. */
     omitted_plays_hint?: string;
+    /** Copyable CLI command templates for follow-up discovery/execution. */
     commandTemplates?: {
         describe?: string;
         execute?: string;
     };
+    /** Pre-rendered sections and actions for CLI/agent display. */
     render?: {
         sections?: Array<{
             title: string;
@@ -534,9 +608,19 @@ type PlayRunActionPackage = {
     datasetPath: string;
     format: 'csv';
 };
+/**
+ * Compact canonical package for an inspected play run.
+ *
+ * This object is designed for SDK/CLI/API consumers that need stable run
+ * metadata, output handles, and follow-up actions without reading dashboard
+ * internals.
+ */
 interface PlayRunPackage {
+    /** Package schema version. */
     schemaVersion: 1;
+    /** Package discriminator. */
     kind: 'play_run';
+    /** Run identity, status, timing, and dashboard metadata. */
     run: {
         id: string;
         playName: string;
@@ -548,8 +632,11 @@ interface PlayRunPackage {
         durationMs?: number | null;
         error?: string;
     };
+    /** Step-level summaries emitted by the runtime. */
     steps: Array<Record<string, unknown>>;
+    /** Named output summaries, including dataset handles and scalar outputs. */
     outputs: Record<string, Record<string, unknown>>;
+    /** Follow-up actions a caller can perform against the run. */
     next?: {
         inspect?: PlayRunActionPackage;
         export?: PlayRunActionPackage;
@@ -1136,6 +1223,13 @@ type EnrichCompiledConfig = {
 type ExecuteToolRawOptions = {
     includeToolMetadata?: boolean;
 };
+/**
+ * Standard provider/tool execution envelope returned by low-level SDK calls.
+ *
+ * `toolResponse.raw` contains the provider result. `extractedValues` and
+ * `extractedLists` contain Deepline-normalized getters when the tool exposes
+ * them. Billing fields are Deepline-facing and must not expose provider spend.
+ */
 type ToolExecution<TData = unknown, TMeta = Record<string, unknown>> = {
     status: string;
     job_id?: string;
@@ -1149,16 +1243,20 @@ type ToolExecution<TData = unknown, TMeta = Record<string, unknown>> = {
     billing?: Record<string, unknown>;
     [key: string]: unknown;
 };
+/** Filters for `client.runs.list(...)`. */
 type RunsListOptions = {
     play: string;
     status?: string;
 };
+/** Streaming options for `client.runs.tail(...)`. */
 type RunsTailOptions = {
     signal?: AbortSignal;
 };
+/** Log fetch options for `client.runs.logs(...)`. */
 type RunsLogsOptions = {
     limit?: number;
 };
+/** Persisted log response for one play run. */
 type RunsLogsResult = {
     runId: string;
     totalCount: number;
@@ -1169,12 +1267,14 @@ type RunsLogsResult = {
     hasMore: boolean;
     entries: string[];
 };
+/** One persisted runtime-sheet row returned by `client.runs.exportDatasetRows(...)`. */
 type PlaySheetRow = {
     key?: string;
     status?: string;
     data?: Record<string, unknown>;
     [key: string]: unknown;
 };
+/** Runtime-sheet rows and aggregate progress for one dataset/table namespace. */
 type PlaySheetRowsResult = {
     rows: PlaySheetRow[];
     summary?: {
@@ -1204,13 +1304,27 @@ type PlaySecretMetadata = {
     updatedAt: number;
     lastUsedAt?: number;
 };
+/**
+ * Public runs namespace exposed as `client.runs`.
+ *
+ * This namespace mirrors the canonical `/api/v2/runs` resource family and is
+ * the preferred low-level surface for polling, streaming, stopping, reading
+ * logs, and exporting durable dataset rows.
+ *
+ * @sdkReference client 020 client.runs
+ */
 type RunsNamespace = {
+    /** Get current run status by public run id. */
     get: (runId: string, options?: {
         full?: boolean;
     }) => Promise<PlayStatus>;
+    /** List runs for one play, optionally filtered by status. */
     list: (options: RunsListOptions) => Promise<PlayRunListItem[]>;
+    /** Stream run events and return the latest/terminal run status. */
     tail: (runId: string, options?: RunsTailOptions) => Promise<PlayStatus>;
+    /** Fetch persisted log lines for a run. */
     logs: (runId: string, options?: RunsLogsOptions) => Promise<RunsLogsResult>;
+    /** Export persisted rows for a runtime-sheet dataset/table namespace. */
     exportDatasetRows: (input: {
         playName: string;
         tableNamespace: string;
@@ -1218,6 +1332,7 @@ type RunsNamespace = {
         limit?: number;
         offset?: number;
     }) => Promise<PlaySheetRowsResult>;
+    /** Stop a running/waiting run. */
     stop: (runId: string, options?: {
         reason?: string;
     }) => Promise<StopPlayRunResult>;
@@ -1241,12 +1356,20 @@ type RunsNamespace = {
  *   baseUrl: 'http://localhost:3000',
  * });
  * ```
+ *
+ * @sdkReference client 010
  */
 declare class DeeplineClient {
     private readonly http;
     private readonly config;
+    /** Canonical run lifecycle namespace backed by `/api/v2/runs`. */
     readonly runs: RunsNamespace;
     /**
+     * Create a low-level SDK client.
+     *
+     * Most callers can omit options and let the SDK resolve auth/config from
+     * environment variables and CLI-managed credentials.
+     *
      * @param options - Optional overrides for API key, base URL, timeout, and retries.
      * @throws {@link ConfigError} if no API key can be resolved from any source.
      */
@@ -1260,7 +1383,14 @@ declare class DeeplineClient {
     private playCloneEditStarter;
     private summarizePlayListItem;
     private summarizePlayDetail;
+    /** List secret metadata visible to the current workspace. */
     listSecrets(): Promise<PlaySecretMetadata[]>;
+    /**
+     * Check whether a named secret exists, is active, and has a stored value.
+     *
+     * @param name - Secret name. It is normalized to uppercase before lookup.
+     * @returns Matching active secret metadata, or `null`.
+     */
     checkSecret(name: string): Promise<PlaySecretMetadata | null>;
     /**
      * List all available tools.
@@ -1316,7 +1446,19 @@ 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>>;
+    /**
+     * Back-compatible alias for {@link executeTool}.
+     *
+     * Retained for callers that still use the older raw naming while the response
+     * envelope remains the same.
+     */
     executeToolRaw<TData = unknown, TMeta = Record<string, unknown>>(toolId: string, input: Record<string, unknown>, options?: ExecuteToolRawOptions): Promise<ToolExecution<TData, TMeta>>;
+    /**
+     * Run a bounded SQL query against the customer data plane.
+     *
+     * Use this from trusted backend or agent contexts only. The API enforces
+     * workspace scoping and row limits.
+     */
     queryCustomerDb(input: {
         sql: string;
         maxRows?: number;
@@ -1355,6 +1497,17 @@ declare class DeeplineClient {
      * ```
      */
     startPlayRun(request: StartPlayRunRequest): Promise<PlayRunStart>;
+    /**
+     * Start a play run and stream live runtime events from the same request.
+     *
+     * Use this when a caller wants low-level event handling instead of submitting
+     * first and then connecting to `streamPlayRunEvents(runId)`.
+     *
+     * @param request - Play run configuration.
+     * @param options - Optional streaming options.
+     * @param options.signal - Optional abort signal for the streaming request.
+     * @returns Async stream of play-scoped live events.
+     */
     startPlayRunStream(request: StartPlayRunRequest, options?: {
         signal?: AbortSignal;
     }): AsyncGenerator<PlayLiveEvent>;
@@ -1387,6 +1540,12 @@ declare class DeeplineClient {
         triggerMetadata?: unknown;
         triggerBindings?: unknown;
     }>;
+    /**
+     * Register multiple bundled play artifacts in one request.
+     *
+     * Used by packaging and prebuilt publication flows. Each artifact is compiled
+     * first when a compiler manifest is not already supplied.
+     */
     registerPlayArtifacts(artifacts: Array<{
         name: string;
         sourceCode: string;
@@ -1413,6 +1572,13 @@ declare class DeeplineClient {
             triggerBindings?: unknown;
         }>;
     }>;
+    /**
+     * Compile a bundled play artifact into the server-side compiler manifest.
+     *
+     * The manifest records imports, trigger bindings, static pipeline shape, and
+     * runtime metadata needed before a play artifact can be checked, registered,
+     * or run.
+     */
     compilePlayManifest(input: {
         name: string;
         sourceCode: string;
@@ -1433,12 +1599,24 @@ declare class DeeplineClient {
         sourceFiles?: Record<string, string>;
         artifact: Record<string, unknown>;
     }): Promise<PlayCheckResult>;
+    /**
+     * Compile legacy enrich command arguments into a runtime plan.
+     *
+     * This is primarily used by CLI compatibility paths that translate older
+     * enrichment commands onto the play runtime.
+     */
     compileEnrichPlan(input: {
         plan_args?: string[];
         config?: unknown;
     }): Promise<{
         config: EnrichCompiledConfig;
     }>;
+    /**
+     * Register an already-bundled play artifact and start a run from it.
+     *
+     * This is the low-level file-backed run path used by SDK/CLI packaging
+     * wrappers after local bundling has produced the runtime artifact.
+     */
     startPlayRunFromBundle(input: {
         name: string;
         sourceCode: string;
@@ -1515,6 +1693,12 @@ declare class DeeplineClient {
         contentType: string;
         bytes: number;
     }>): Promise<PlayStagedFileRef[]>;
+    /**
+     * Resolve staged play files by content hash without uploading bytes.
+     *
+     * Missing files are returned so callers can upload only the files the server
+     * does not already have.
+     */
     resolveStagedPlayFiles(files: Array<{
         logicalPath: string;
         contentHash: string;
@@ -1632,6 +1816,12 @@ declare class DeeplineClient {
      * ```
      */
     getRunLogs(runId: string, options?: RunsLogsOptions): Promise<RunsLogsResult>;
+    /**
+     * Export persisted runtime-sheet rows for a play dataset/table namespace.
+     *
+     * This is the SDK form of exporting `ctx.dataset(...).run()` output for a
+     * specific play and optional run id.
+     */
     getPlaySheetRows(input: {
         playName: string;
         tableNamespace: string;
@@ -1651,14 +1841,27 @@ declare class DeeplineClient {
     stopRun(runId: string, options?: {
         reason?: string;
     }): Promise<StopPlayRunResult>;
+    /**
+     * List callable plays visible to the workspace.
+     *
+     * Pass `origin: "prebuilt"` for Deepline-managed prebuilts or
+     * `origin: "owned"` for org-owned plays.
+     */
     listPlays(options?: {
         origin?: 'prebuilt' | 'owned';
         grep?: string;
         grepMode?: 'all' | 'any' | 'phrase';
     }): Promise<PlayListItem[]>;
+    /**
+     * Search callable plays and return compact play descriptions.
+     *
+     * Prebuilt plays are preferred by default because they have maintained
+     * contracts and stable run behavior.
+     */
     searchPlays(options: {
         query: string;
         compact?: boolean;
+        scope?: 'prebuilt' | 'owned' | 'all';
     }): Promise<PlayDescription[]>;
     /**
      * Get the full definition and state of a named play.
@@ -1678,6 +1881,12 @@ declare class DeeplineClient {
      * ```
      */
     getPlay(name: string): Promise<PlayDetail>;
+    /**
+     * Get a normalized play description suitable for agents and CLIs.
+     *
+     * The description includes runnable examples, input/output summaries, clone
+     * guidance, revision state, and latest run metadata when available.
+     */
     describePlay(name: string, options?: {
         compact?: boolean;
     }): Promise<PlayDescription>;
@@ -2004,6 +2213,8 @@ type PlayDatasetTransformOptions = {
  * small and bounded. `PlayDataset` intentionally does not expose `.rows`,
  * `.toArray()`, or other array aliases; those hide the runtime cost of loading
  * persisted rows into memory.
+ *
+ * @sdkReference runtime 190
  */
 interface PlayDataset<T> extends AsyncIterable<T> {
     readonly [PLAY_DATASET_BRAND]: true;
@@ -2337,15 +2548,28 @@ type ToolExecuteResultAccessors<TExtracted extends Record<string, unknown> = Par
  * Use extractors first when a tool contract exposes them. Drop to
  * `toolResponse.raw` when you need provider-specific fields or when debugging
  * from persisted run rows.
+ *
+ * @sdkReference runtime 200
  */
 type ToolExecuteResult<TResult = unknown, TMeta = Record<string, unknown>, TExtracted extends Record<string, unknown> = Partial<DeeplineGetterValueMap>, TLists extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>> = ToolExecuteResultBase<TResult, TMeta> & ToolExecuteResultAccessors<TExtracted, TLists>;
 
-type StaleAfterSecondsResolver<Value = unknown> = (value: Value) => number | null;
-type AuthoredStaleAfterSeconds<Value = unknown> = number | StaleAfterSecondsResolver<Value>;
+/**
+ * Previous durable cell value passed to object-column resolvers.
+ *
+ * The runtime supplies this when a row+column is being recomputed after a
+ * previous value existed. `value` has the same type that the column returns;
+ * freshness metadata lives beside it.
+ *
+ * @sdkReference runtime 120
+ */
 type PreviousCell<Value = unknown> = {
+    /** Previous completed value for this row+column. */
     value: Value;
+    /** Millisecond timestamp when the previous value completed. */
     completedAt?: number;
+    /** Millisecond timestamp when the previous value becomes stale; `null` means no expiry. */
     staleAt?: number | null;
+    /** Resolved numeric TTL in seconds for the previous value, when present. */
     staleAfterSeconds?: number;
 };
 
@@ -2375,6 +2599,8 @@ type PreviousCell<Value = unknown> = {
  *   cron: { schedule: '0 2 * * *', timezone: 'UTC' },
  * });
  * ```
+ *
+ * @sdkReference runtime 030
  */
 type PlayBindings = {
     /** Optional per-run billing controls enforced by the runtime. */
@@ -2433,6 +2659,8 @@ type LoosePlayObject = {
  *
  * The `tool` value comes from live tool discovery. The `id` is the stable
  * logical call name inside this play and participates in replay/idempotency.
+ *
+ * @sdkReference runtime 160
  */
 type ToolExecutionRequest = {
     /** Stable logical id for this tool call within the play. */
@@ -2443,13 +2671,36 @@ type ToolExecutionRequest = {
     input: Record<string, unknown>;
     /** Human-readable description for logs and run inspection. */
     description?: string;
+    /** Numeric TTL in seconds for this tool checkpoint. */
     staleAfterSeconds?: number;
 };
-type StaleAfterSeconds<Value = unknown> = AuthoredStaleAfterSeconds<Value>;
+/**
+ * Freshness policy for dataset cells and step-program columns.
+ *
+ * Use a positive whole number of seconds for a fixed TTL. Use a function when
+ * the next expiry depends on the value that was just produced. The function
+ * receives the completed cell value; return a positive whole number of seconds
+ * to set the next expiry, or `null` to keep that value indefinitely.
+ *
+ * Result-based policies are evaluated only for dataset/step-program cells. The
+ * scalar `ctx.step`, `ctx.fetch`, `ctx.runPlay`, and `ctx.tools.execute` APIs
+ * accept numeric TTLs.
+ *
+ * @sdkReference runtime 080
+ */
+type StaleAfterSeconds<Value = unknown> = number | ((value: Value) => number | null);
 type StepResolver<Row, Value> = (row: Row, ctx: DeeplinePlayRuntimeContext, index: number, previousCell?: PreviousCell<Value>) => Value | Promise<Value>;
+/**
+ * Input object passed to an object-column `run` resolver.
+ *
+ * @sdkReference runtime 090
+ */
 type DatasetColumnRunInput<Row, Value> = {
+    /** Current row, including previously computed columns. */
     row: Row;
+    /** Runtime context for tool/play/fetch/log calls. */
     ctx: DeeplinePlayRuntimeContext;
+    /** Zero-based row index for this dataset run. */
     index: number;
     /**
      * The prior stored value for this exact row+column when the runtime has
@@ -2459,9 +2710,20 @@ type DatasetColumnRunInput<Row, Value> = {
      */
     previousCell?: PreviousCell<Value>;
 };
+/**
+ * Object-column form for `.withColumn(...)`.
+ *
+ * Use this when a column needs `runIf`, typed `previousCell`, or a
+ * result-based `staleAfterSeconds(value)` policy.
+ *
+ * @sdkReference runtime 100
+ */
 type DatasetColumnDefinition<Row, Value> = {
+    /** Compute one cell value. Receives the previous stored value when rerunning. */
     run: (input: DatasetColumnRunInput<Row, Value>) => Value | Promise<Value>;
+    /** Optional row-level gate. Skipped rows produce `null` for this column. */
     readonly runIf?: (row: Row, index: number) => boolean | Promise<boolean>;
+    /** Fixed or value-dependent freshness policy for this cell. */
     readonly staleAfterSeconds?: StaleAfterSeconds<Value>;
 };
 type ConditionalStepResolver<Row, Value, Else = null> = {
@@ -2471,8 +2733,15 @@ type ConditionalStepResolver<Row, Value, Else = null> = {
     readonly elseValue: Else;
     else<ValueElse>(value: ValueElse): ConditionalStepResolver<Row, Value, ValueElse>;
 };
+/**
+ * Options for row-level `.withColumn(...)` and `steps().step(...)` entries.
+ *
+ * @sdkReference runtime 110
+ */
 type StepOptions<Row, Value = unknown> = {
+    /** Optional row-level gate. Skipped rows produce `null` for this column. */
     readonly runIf?: (row: Row, index: number) => boolean | Promise<boolean>;
+    /** Fixed or value-dependent freshness policy for this cell. */
     readonly staleAfterSeconds?: StaleAfterSeconds<Value>;
 };
 type StepProgram<Input, Output, Return = Output> = {
@@ -2497,6 +2766,11 @@ type PlayStepProgramStep = {
 };
 type ColumnResolver<Row, Value> = StepResolver<Row, Value> | ConditionalStepResolver<Row, Value> | StepProgramResolver<Row, Value>;
 type StepProgramOutput<TProgram> = TProgram extends StepProgram<any, infer Output, any> ? Output : never;
+/**
+ * Builder returned by `ctx.dataset(...)` for row-level durable columns.
+ *
+ * @sdkReference runtime 070 .dataset(...).withColumn(name, resolver).run(options)
+ */
 type DatasetBuilder<InputRow extends object, OutputRow extends object> = {
     /**
      * Define one output column for every row in this dataset.
@@ -2512,10 +2786,35 @@ type DatasetBuilder<InputRow extends object, OutputRow extends object> = {
      * @returns The same dataset builder with the new column type.
      */
     withColumn<Name extends string, Value>(name: Name, resolver: ColumnResolver<OutputRow, Value>): DatasetBuilder<InputRow, OutputRow & Record<Name, Value>>;
+    /**
+     * Define one output column with object-column authoring and a row gate.
+     *
+     * @param name - Output column name.
+     * @param definition - Object-column definition with required `runIf`.
+     * @returns The same dataset builder with a nullable column type for skipped rows.
+     */
     withColumn<Name extends string, Value>(name: Name, definition: DatasetColumnDefinition<OutputRow, Value> & {
         readonly runIf: (row: OutputRow, index: number) => boolean | Promise<boolean>;
     }): DatasetBuilder<InputRow, OutputRow & Record<Name, Value | null>>;
+    /**
+     * Define one output column with object-column authoring.
+     *
+     * Use this form for typed `previousCell` access or result-based
+     * `staleAfterSeconds(value)` policies.
+     *
+     * @param name - Output column name.
+     * @param definition - Object-column definition.
+     * @returns The same dataset builder with the new column type.
+     */
     withColumn<Name extends string, Value>(name: Name, definition: DatasetColumnDefinition<OutputRow, Value>): DatasetBuilder<InputRow, OutputRow & Record<Name, Value>>;
+    /**
+     * Define one output column with a resolver plus row-level options.
+     *
+     * @param name - Output column name.
+     * @param resolver - Computes the value for one row.
+     * @param options - Row gate and freshness options.
+     * @returns The same dataset builder with a nullable column type for skipped rows.
+     */
     withColumn<Name extends string, Value>(name: Name, resolver: StepResolver<OutputRow, Value> | StepProgramResolver<OutputRow, Value>, options: StepOptions<OutputRow, Value>): DatasetBuilder<InputRow, OutputRow & Record<Name, Value | null>>;
     withColumns<Program extends StepProgram<OutputRow, object, unknown>>(program: Program): DatasetBuilder<InputRow, StepProgramOutput<Program>>;
     /** @deprecated Dataset `.step(...)` was replaced by `.withColumn(...)`. */
@@ -2554,7 +2853,11 @@ type CsvInput<TRow extends object = Record<string, unknown>> = FileInput<{
     readonly row: TRow;
 }>;
 type ColumnMap<TRow extends object> = Partial<Record<Extract<keyof TRow, string>, string | readonly string[]>>;
-/** Options for loading a staged CSV with `ctx.csv(...)`. */
+/**
+ * Options for loading a staged CSV with `ctx.csv(...)`.
+ *
+ * @sdkReference runtime 050
+ */
 type CsvOptions = {
     /** Human-readable description for runtime logs and inspection. */
     description?: string;
@@ -2628,6 +2931,8 @@ interface DeeplinePlayRuntimeContext {
      * @param options - CSV load options.
      *
      * @returns A {@link PlayDataset} whose rows should usually flow directly into `ctx.dataset(...)`.
+     *
+     * @sdkReference runtime 040 ctx.csv(path, options)
      */
     csv<T = Record<string, unknown>>(path: string, options?: CsvOptions): Promise<PlayDataset<T>>;
     /**
@@ -2684,6 +2989,8 @@ interface DeeplinePlayRuntimeContext {
      *     row.company?.employeeCount > 100 ? 'enterprise' : 'smb')
      *   .run({ description: 'Enrich leads.' });
      * ```
+     *
+     * @sdkReference runtime 060 ctx.dataset(key, items)
      */
     dataset<TItem extends object>(key: string, items: PlayDatasetInput<TItem>): DatasetBuilder<TItem, TItem>;
     /**
@@ -2697,6 +3004,8 @@ interface DeeplinePlayRuntimeContext {
          *
          * @param request - Tool call request.
          * @returns Tool execution result.
+         *
+         * @sdkReference runtime 150 ctx.tools.execute(request)
          */
         execute<TOutput = LoosePlayObject>(request: ToolExecutionRequest & {
             staleAfterSeconds?: number;
@@ -2723,6 +3032,8 @@ interface DeeplinePlayRuntimeContext {
      * @param input - Program input.
      * @param options - Run options.
      * @returns Program output.
+     *
+     * @sdkReference runtime 180 ctx.runSteps(program, input, options)
      */
     runSteps<TInput extends Record<string, unknown>, TOutput>(program: StepProgram<TInput, any, TOutput>, input: TInput, options?: {
         description?: string;
@@ -2743,6 +3054,8 @@ interface DeeplinePlayRuntimeContext {
      * @param run - Computes the value once.
      * @param options - Checkpoint options.
      * @returns Checkpoint value.
+     *
+     * @sdkReference runtime 130 ctx.step(id, fn)
      */
     step<T>(id: string, run: () => T | Promise<T>, options?: {
         staleAfterSeconds?: number;
@@ -2759,6 +3072,8 @@ interface DeeplinePlayRuntimeContext {
      * @param url - URL to fetch.
      * @param init - Fetch options.
      * @returns Recorded response.
+     *
+     * @sdkReference runtime 170 ctx.fetch(key, url, init)
      */
     fetch(key: string, url: string | URL, init?: SecretAwareRequestInit, options?: {
         staleAfterSeconds?: number;
@@ -2771,6 +3086,11 @@ interface DeeplinePlayRuntimeContext {
         bodyText: string;
         json: unknown | null;
     }>;
+    secrets: {
+        get(name: string): SecretHandle;
+        bearer(secret: SecretHandle): SecretAuth;
+        header(header: string, secret: SecretHandle): SecretAuth;
+    };
     /**
      * Invoke another registered or file-backed play as a child workflow.
      *
@@ -2786,12 +3106,9 @@ interface DeeplinePlayRuntimeContext {
      * @param input - Input object passed to the child play.
      * @param options - Child play options.
      * @returns Child play output.
+     *
+     * @sdkReference runtime 140 ctx.runPlay(key, playRef, input, options)
      */
-    secrets: {
-        get(name: string): SecretHandle;
-        bearer(secret: SecretHandle): SecretAuth;
-        header(header: string, secret: SecretHandle): SecretAuth;
-    };
     runPlay<TOutput = unknown>(key: string, playRef: string | PlayReferenceLike, input: Record<string, unknown>, options: {
         description?: string;
         staleAfterSeconds?: number;
@@ -2846,6 +3163,8 @@ interface DeeplinePlayRuntimeContext {
  * // Cancel if needed
  * await job.cancel();
  * ```
+ *
+ * @sdkReference plays 030
  */
 interface PlayJob<TOutput = unknown> {
     /** Temporal workflow ID for this execution. */
@@ -2919,6 +3238,8 @@ interface PlayJob<TOutput = unknown> {
  * // Publish the current draft
  * await play.publish();
  * ```
+ *
+ * @sdkReference plays 020
  */
 interface DeeplineNamedPlay<TInput = Record<string, unknown>, TOutput = unknown> {
     /** The play's name. */
@@ -2960,6 +3281,39 @@ interface DeeplineNamedPlay<TInput = Record<string, unknown>, TOutput = unknown>
         revisionId?: string;
     }): Promise<TOutput>;
 }
+/**
+ * Tool/provider operations available from a connected {@link DeeplineContext}.
+ *
+ * This namespace is for regular SDK callers outside a play runtime. Inside a
+ * `definePlay(...)` body, use `ctx.tools.execute({ id, tool, input, ... })`
+ * so provider calls become durable runtime checkpoints.
+ *
+ * @sdkReference tools 010 DeeplineContext.tools
+ */
+type DeeplineToolsNamespace = {
+    /** List all available provider-backed tools. */
+    list(): Promise<ToolDefinition[]>;
+    /** Get detailed metadata for one provider-backed tool. */
+    get(toolId: string): Promise<ToolMetadata>;
+    /**
+     * Execute a provider-backed tool from a regular SDK process.
+     *
+     * 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>;
+};
+/**
+ * Named-play discovery and handle operations from a connected {@link DeeplineContext}.
+ *
+ * @sdkReference plays 010 DeeplineContext.plays
+ */
+type DeeplinePlaysNamespace = {
+    /** List saved and callable plays visible to the current workspace. */
+    list(): Promise<PlayListItem[]>;
+    /** Return a typed handle for a named, saved, shared, or prebuilt play. */
+    get<TInput = Record<string, unknown>, TOutput = unknown>(name: string): DeeplineNamedPlay<TInput, TOutput>;
+};
 type PrebuiltPlayRef = {
     readonly playName: string;
     readonly name: string;
@@ -2983,6 +3337,8 @@ type PlayInputContract<TInput> = {
  * through `defineInput<T>(schema)`, or when configuration reads clearer as one
  * object. The shorthand `definePlay(name, fn, bindings?)` is equivalent for
  * simple file-backed plays.
+ *
+ * @sdkReference runtime 020
  */
 type DefinePlayConfig<TInput, TOutput extends PlayReturnObject> = {
     /** Play id/name. */
@@ -3062,9 +3418,19 @@ type PlayMetadata = {
  * const job = await deepline.play('email-waterfall').run({ domain: 'stripe.com' });
  * const output = await job.get();
  * ```
+ *
+ * @sdkReference entrypoints 020
  */
 declare class DeeplineContext {
     private readonly client;
+    /**
+     * Create a high-level SDK context.
+     *
+     * Most callers should use {@link Deepline.connect}; direct construction is
+     * equivalent when you already have explicit client options.
+     *
+     * @param options - Optional SDK client configuration.
+     */
     constructor(options?: DeeplineClientOptions);
     /**
      * Tool operations namespace.
@@ -3077,18 +3443,21 @@ declare class DeeplineContext {
      * const company = companyLookup.toolResponse.raw;
      * ```
      */
-    get tools(): {
-        /** List all available tools. */
-        list: () => Promise<ToolDefinition[]>;
-        /** Get detailed metadata for a tool. */
-        get: (toolId: string) => Promise<ToolMetadata>;
-        /** Execute a tool and return the standard execution envelope. */
-        execute: (toolId: string, input: Record<string, unknown>) => Promise<ToolExecuteResult>;
-    };
-    get plays(): {
-        list: () => Promise<PlayListItem[]>;
-        get: <TInput = Record<string, unknown>, TOutput = unknown>(name: string) => DeeplineNamedPlay<TInput, TOutput>;
-    };
+    get tools(): DeeplineToolsNamespace;
+    /**
+     * Play discovery and named-play handles.
+     *
+     * Use `plays.list()` for discovery and `plays.get(name)` when you prefer a
+     * namespace spelling over `ctx.play(name)`.
+     */
+    get plays(): DeeplinePlaysNamespace;
+    /**
+     * Convenience references for Deepline-managed prebuilt plays.
+     *
+     * Known prebuilts are exposed by camel-cased aliases. Any other property is
+     * converted into `prebuilt/<property>` so callers can pass the reference to
+     * `ctx.runPlay(...)`.
+     */
     get prebuilt(): Record<string, PrebuiltPlayRef>;
     /**
      * Get a named play handle for remote lifecycle operations.
@@ -3106,6 +3475,17 @@ declare class DeeplineContext {
      * ```
      */
     play<TInput = Record<string, unknown>, TOutput = unknown>(name: string): DeeplineNamedPlay<TInput, TOutput>;
+    /**
+     * Run a named or prebuilt play and wait for its output.
+     *
+     * This is the high-level SDK equivalent of `ctx.play(name).runSync(input)`.
+     * Inside a play runtime, prefer the in-play `ctx.runPlay(key, playRef, input,
+     * options)` form so the child run is checkpointed under a stable key.
+     *
+     * @param playOrRef - Play name or prebuilt/reference object.
+     * @param input - JSON input passed to the play.
+     * @returns Completed play output.
+     */
     runPlay<TInput = Record<string, unknown>, TOutput = unknown>(playOrRef: string | PlayReferenceLike, input: TInput): Promise<TOutput>;
 }
 /**
@@ -3119,6 +3499,8 @@ declare class DeeplineContext {
  * const tools = await deepline.tools.list();
  * const result = await deepline.tools.execute('test_company_search', { domain: 'stripe.com' });
  * ```
+ *
+ * @sdkReference entrypoints 010
  */
 declare class Deepline {
     /**
@@ -3409,4 +3791,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, DEEPLINE_EXTRACTOR_TARGETS, DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, type DeeplineEmailStatusGetterValue, DeeplineError, type DeeplineExtractorTarget, type DeeplineGetterValue, type DeeplineGetterValueMap, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplineToolCategory, 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 PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, SDK_API_CONTRACT, SDK_VERSION, type StartPlayRunRequest, type StepProgram, type StepProgramResolver, type StepResolver, type ToolDefinition, type ToolExecuteResult, type ToolExecution, type ToolMetadata, 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, 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 };