deepline 0.1.83 → 0.1.88

package/dist/repo/sdk/src/play.ts

@@ -81,10 +81,12 @@ import type {
   ToolExecuteResult,
   ToolResultMetadataInput,
 } from '../../shared_libs/play-runtime/tool-result-types.js';
+import type { PreviousCell } from '../../shared_libs/play-runtime/cell-staleness.js';
 import type {
   DeeplineClientOptions,
   PlayDetail,
   ClearPlayHistoryResult,
+  PlayListItem,
   PlayRevisionSummary,
   PlayRunListItem,
   PlayStatus,
@@ -121,6 +123,8 @@ import type { ToolExecution } from './client.js';
  *   cron: { schedule: '0 2 * * *', timezone: 'UTC' },
  * });
  * ```
+ *
+ * @sdkReference runtime 030
  */
 export type PlayBindings = {
   /** Optional per-run billing controls enforced by the runtime. */
@@ -187,12 +191,30 @@ export type {
   ToolResultListAccessor,
   ToolResultTargetAccessor as ToolExtractedValue,
 } from '../../shared_libs/play-runtime/tool-result-types.js';
+export {
+  DEEPLINE_EXTRACTOR_TARGETS,
+  DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS,
+  JOB_CHANGE_STATUS_VALUES,
+  PHONE_STATUS_VALUES,
+  isDeeplineExtractorTarget,
+} from '../../shared_libs/play-runtime/extractor-targets.js';
+export type {
+  DeeplineEmailStatusGetterValue,
+  DeeplineExtractorTarget,
+  DeeplineGetterValue,
+  DeeplineGetterValueMap,
+  JobChangeStatus,
+  PhoneStatus,
+} from '../../shared_libs/play-runtime/extractor-targets.js';
+export type { PreviousCell } from '../../shared_libs/play-runtime/cell-staleness.js';
 
 /**
  * Keyword-style request object for `ctx.tools.execute(...)`.
  *
  * 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
  */
 export type ToolExecutionRequest = {
   /** Stable logical id for this tool call within the play. */
@@ -203,15 +225,73 @@ export 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;
 };
 
+/**
+ * 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
+ */
+export type StaleAfterSeconds<Value = unknown> =
+  | number
+  | ((value: Value) => number | null);
+
 export 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
+ */
+export 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
+   * decided the cell is due to run again. `previousCell.value` is the same type
+   * this column returns; metadata such as `completedAt` and `staleAt` lives
+   * beside it and is not mixed into the 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
+ */
+export 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>;
+};
+
 export type ConditionalStepResolver<Row, Value, Else = null> = {
   readonly kind: 'conditional';
   readonly when: (row: Row, index: number) => boolean | Promise<boolean>;
@@ -222,9 +302,16 @@ export type ConditionalStepResolver<Row, Value, Else = null> = {
   ): ConditionalStepResolver<Row, Value, ValueElse>;
 };
 
-export type StepOptions<Row> = {
+/**
+ * Options for row-level `.withColumn(...)` and `steps().step(...)` entries.
+ *
+ * @sdkReference runtime 110
+ */
+export 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>;
-  readonly staleAfterSeconds?: number;
+  /** Fixed or value-dependent freshness policy for this cell. */
+  readonly staleAfterSeconds?: StaleAfterSeconds<Value>;
 };
 
 export type StepProgram<Input, Output, Return = Output> = {
@@ -242,7 +329,7 @@ export type StepProgram<Input, Output, Return = Output> = {
   step<Name extends string, Value>(
     name: Name,
     resolver: StepResolver<Output, Value> | StepProgramResolver<Output, Value>,
-    options: StepOptions<Output>,
+    options: StepOptions<Output, Value>,
   ): StepProgram<Input, Output & Record<Name, Value | null>, Return>;
   return<Value>(
     resolver: StepResolver<Output, Value>,
@@ -258,7 +345,7 @@ export type StepProgramResolver<Input, Return> = {
 
 export type PlayStepProgramStep = {
   readonly name: string;
-  readonly staleAfterSeconds?: number;
+  readonly staleAfterSeconds?: StaleAfterSeconds;
   readonly resolver:
     | StepResolver<Record<string, unknown>, unknown>
     | ConditionalStepResolver<Record<string, unknown>, unknown>
@@ -273,6 +360,11 @@ export type ColumnResolver<Row, Value> =
 export 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)
+ */
 export type DatasetBuilder<
   InputRow extends object,
   OutputRow extends object,
@@ -294,12 +386,50 @@ export type DatasetBuilder<
     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>,
+    options: StepOptions<OutputRow, Value>,
   ): DatasetBuilder<InputRow, OutputRow & Record<Name, Value | null>>;
   withColumns<Program extends StepProgram<OutputRow, object, unknown>>(
     program: Program,
@@ -357,7 +487,11 @@ export 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
+ */
 export type CsvOptions = {
   /** Human-readable description for runtime logs and inspection. */
   description?: string;
@@ -432,6 +566,8 @@ export 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,
@@ -492,6 +628,8 @@ export 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,
@@ -509,6 +647,8 @@ export 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 },
@@ -538,6 +678,8 @@ export 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>,
@@ -560,6 +702,8 @@ export 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,
@@ -578,6 +722,8 @@ export 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,
@@ -593,6 +739,11 @@ export 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.
    *
@@ -608,12 +759,9 @@ export 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,
@@ -674,6 +822,8 @@ export interface DeeplinePlayRuntimeContext {
  * // Cancel if needed
  * await job.cancel();
  * ```
+ *
+ * @sdkReference plays 030
  */
 export interface PlayJob<TOutput = unknown> {
   /** Temporal workflow ID for this execution. */
@@ -749,6 +899,8 @@ export interface PlayJob<TOutput = unknown> {
  * // Publish the current draft
  * await play.publish();
  * ```
+ *
+ * @sdkReference plays 020
  */
 export interface DeeplineNamedPlay<
   TInput = Record<string, unknown>,
@@ -798,6 +950,46 @@ export interface DeeplineNamedPlay<
   runSync(input: TInput, options?: { 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
+ */
+export 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
+ */
+export 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>;
+};
+
 export type PrebuiltPlayRef = {
   readonly playName: string;
   readonly name: string;
@@ -829,6 +1021,8 @@ export 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
  */
 export type DefinePlayConfig<TInput, TOutput extends PlayReturnObject> = {
   /** Play id/name. */
@@ -886,7 +1080,7 @@ class DeeplineStepProgram<Input, Output, ReturnValue> implements StepProgram<
   step<Name extends string, Value>(
     name: Name,
     resolver: StepResolver<Output, Value> | StepProgramResolver<Output, Value>,
-    options: StepOptions<Output>,
+    options: StepOptions<Output, Value>,
   ): StepProgram<Input, Output & Record<Name, Value | null>, ReturnValue>;
   step<Name extends string, Value>(
     name: Name,
@@ -894,7 +1088,7 @@ class DeeplineStepProgram<Input, Output, ReturnValue> implements StepProgram<
       | StepResolver<Output, Value>
       | ConditionalStepResolver<Output, Value>
       | StepProgramResolver<Output, Value>,
-    options?: StepOptions<Output>,
+    options?: StepOptions<Output, Value>,
   ): StepProgram<Input, Output & Record<Name, Value | null>, ReturnValue> {
     if (!name.trim()) {
       throw new Error(
@@ -915,6 +1109,12 @@ class DeeplineStepProgram<Input, Output, ReturnValue> implements StepProgram<
         {
           name,
           resolver: stepResolver as PlayStepProgramStep['resolver'],
+          ...(options?.staleAfterSeconds !== undefined
+            ? {
+                staleAfterSeconds:
+                  options.staleAfterSeconds as PlayStepProgramStep['staleAfterSeconds'],
+              }
+            : {}),
         },
       ],
       this.returnResolver as StepResolver<
@@ -1133,10 +1333,20 @@ function createNamedPlayHandle<
  * const job = await deepline.play('email-waterfall').run({ domain: 'stripe.com' });
  * const output = await job.get();
  * ```
+ *
+ * @sdkReference entrypoints 020
  */
 export class DeeplineContext {
   private readonly client: DeeplineClient;
 
+  /**
+   * 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) {
     this.client = new DeeplineClient(options);
   }
@@ -1152,7 +1362,7 @@ export class DeeplineContext {
    * const company = companyLookup.toolResponse.raw;
    * ```
    */
-  get tools() {
+  get tools(): DeeplineToolsNamespace {
     return {
       /** List all available tools. */
       list: (): Promise<ToolDefinition[]> => this.client.listTools(),
@@ -1172,7 +1382,13 @@ export class DeeplineContext {
     };
   }
 
-  get plays() {
+  /**
+   * 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 {
     return {
       list: () => this.client.listPlays(),
       get: <TInput = Record<string, unknown>, TOutput = unknown>(
@@ -1181,6 +1397,13 @@ export class DeeplineContext {
     };
   }
 
+  /**
+   * 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> {
     const explicit = {
       companyToContact: {
@@ -1241,6 +1464,17 @@ export class DeeplineContext {
     return createNamedPlayHandle<TInput, TOutput>(() => this.client, name);
   }
 
+  /**
+   * 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.
+   */
   async runPlay<TInput = Record<string, unknown>, TOutput = unknown>(
     playOrRef: string | PlayReferenceLike,
     input: TInput,
@@ -1264,6 +1498,8 @@ export class DeeplineContext {
  * const tools = await deepline.tools.list();
  * const result = await deepline.tools.execute('test_company_search', { domain: 'stripe.com' });
  * ```
+ *
+ * @sdkReference entrypoints 010
  */
 export class Deepline {
   /**
@@ -1490,6 +1726,9 @@ export function definePlay<TInput, TOutput extends PlayReturnObject>(
   fn: (ctx: DeeplinePlayRuntimeContext, input: TInput) => Promise<TOutput>,
   bindings?: PlayBindings,
 ): DefinedPlay<TInput, TOutput>;
+/**
+ * @sdkReference runtime 010
+ */
 export function definePlay<TInput, TOutput extends PlayReturnObject>(
   nameOrConfig: string | DefinePlayConfig<TInput, TOutput>,
   maybeFn?: (

package/dist/repo/sdk/src/plays/harness-stub.ts

@@ -46,6 +46,7 @@ import type {
   WorkReceipt,
   WorkReceiptClaim,
 } from '../../../shared_libs/play-runtime/work-receipts';
+import type { CellStalenessPolicy } from '../../../shared_libs/play-runtime/cell-staleness';
 
 /**
  * Service-binding RPC stub shape — what `env.HARNESS` looks like inside
@@ -191,7 +192,7 @@ export async function harnessStartSheetDataset(input: {
   runId: string;
   inputOffset?: number;
   userEmail?: string | null;
-  cellPolicies?: Record<string, { staleAfterSeconds?: number }>;
+  cellPolicies?: Record<string, CellStalenessPolicy>;
 }): Promise<{
   inserted: number;
   skipped: number;

package/dist/repo/sdk/src/release.ts

@@ -50,10 +50,10 @@ export type SdkRelease = {
 };
 
 export const SDK_RELEASE = {
-  version: '0.1.83',
+  version: '0.1.88',
   apiContract: '2026-06-dataset-column-cell-stale-hard-cutover',
   supportPolicy: {
-    latest: '0.1.83',
+    latest: '0.1.88',
     minimumSupported: '0.1.53',
     deprecatedBelow: '0.1.53',
   },

package/dist/repo/sdk/src/types.ts

@@ -61,18 +61,34 @@ export interface ResolvedConfig {
   maxRetries: number;
 }
 
+/** Column metadata returned by a customer data query. */
 export 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.
+ */
 export 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[];
 }
 
@@ -114,6 +130,13 @@ export type {
   PlayBootstrapTemplate,
 };
 
+/**
+ * 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.
+ */
 export interface ToolDefinition {
   /** Unique tool identifier used in API calls (e.g. `"apollo_people_search"`). */
   toolId: string;
@@ -222,29 +245,54 @@ export interface ToolDefinition {
   }>;
 }
 
+/**
+ * Query options for ranked tool/provider discovery.
+ */
 export 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.
+ */
 export 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;
@@ -372,9 +420,19 @@ export type PlayRunActionPackage =
       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.
+ */
 export interface PlayRunPackage {
+  /** Package schema version. */
   schemaVersion: 1;
+  /** Package discriminator. */
   kind: 'play_run';
+  /** Run identity, status, timing, and dashboard metadata. */
   run: {
     id: string;
     playName: string;
@@ -386,8 +444,11 @@ export 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;
@@ -505,6 +566,10 @@ export interface PlayRunListItem {
   closeTime: string | null;
   /** Duration string (e.g. `'2.5s'`). */
   executionTime: string | null;
+  /** Total Deepline credits charged for the run, when available. */
+  billingTotalCredits?: number;
+  /** Configured per-run Deepline credit cap, when available. */
+  billingMaxCreditsPerRun?: number | null;
   /** Metadata attached to the workflow. */
   memo: {
     /** Organization that owns this run. */