deepline 0.1.55 → 0.1.56

package/dist/index.d.mts

@@ -276,6 +276,22 @@ interface ToolDefinition {
     /** Copyable play-runtime guidance for V2 tool execution results. */
     usageGuidance?: {
         execute?: string;
+        prefer?: string[];
+        access?: {
+            extractedLists?: {
+                expression?: string;
+                meaning?: string;
+            };
+            extractedValues?: {
+                expression?: string;
+                meaning?: string;
+            };
+            rawToolResponse?: {
+                expression?: string;
+                meaning?: string;
+            };
+            invalidGetterHint?: string;
+        };
         toolExecutionResult?: {
             type?: 'ToolExecutionResult';
             toolResponse?: {
@@ -758,6 +774,11 @@ interface PlayDescription {
     rowOutputSchema?: Record<string, unknown> | null;
     runCommand: string;
     examples: string[];
+    cloneEditStarter?: {
+        path: string;
+        command: string;
+        checkCommand: string;
+    };
     currentPublishedVersion?: number | null;
     isDraftDirty?: boolean;
     latestRunId?: string | null;
@@ -1073,6 +1094,8 @@ declare class DeeplineClient {
     private compactSchema;
     private schemaMetadata;
     private playRunCommand;
+    private starterPlayPath;
+    private playCloneEditStarter;
     private summarizePlayListItem;
     private summarizePlayDetail;
     /**
@@ -1464,7 +1487,6 @@ declare class DeeplineClient {
     }): Promise<PlayListItem[]>;
     searchPlays(options: {
         query: string;
-        origin?: 'prebuilt' | 'owned';
         compact?: boolean;
     }): Promise<PlayDescription[]>;
     /**
@@ -1763,14 +1785,34 @@ type PlayDatasetWorkProgressSummary = {
     };
 };
 type PlayDatasetInput<T> = ReadonlyArray<T> | Iterable<T> | AsyncIterable<T> | PlayDataset<T>;
+/**
+ * Durable handle for rows produced by `ctx.csv(...)` or `ctx.map(...).run()`.
+ *
+ * A `PlayDataset` is not a normal in-memory array. It points at runtime-managed
+ * rows, usually backed by persisted sheet storage, and carries metadata such as
+ * dataset kind, dataset id, table namespace, count, and preview rows.
+ *
+ * Pass dataset handles directly into later `ctx.map(...)` stages by default so
+ * Deepline keeps row progress, retries, memory use, and table output under
+ * runtime control. Use `count()` and `peek()` for bounded inspection. Use
+ * `materialize(limit)` or async iteration only when the dataset is intentionally
+ * small and bounded.
+ */
 interface PlayDataset<T> extends AsyncIterable<T> {
     readonly [PLAY_DATASET_BRAND]: true;
+    /** Dataset kind. */
     readonly datasetKind: PlayDatasetKind;
+    /** Dataset id. */
     readonly datasetId: string;
+    /** Backing store info. */
     readonly backing?: PlayDatasetBacking;
+    /** Display label. */
     readonly sourceLabel?: string | null;
+    /** Runtime table name. */
     readonly tableNamespace?: string | null;
+    /** Row count. */
     count(): Promise<number>;
+    /** Preview rows. */
     peek(limit?: number): Promise<T[]>;
     /**
      * Explicit escape hatch for bounded result sets.
@@ -1857,6 +1899,19 @@ type ToolExecuteResultAccessors<TExtracted extends Record<string, unknown> = Rec
         [K in keyof TLists]: ToolResultListAccessor<TLists[K]>;
     };
 };
+/**
+ * Canonical result returned by Deepline tool execution.
+ *
+ * The top-level object is Deepline-owned execution metadata and semantic
+ * extraction state. Raw tool/provider data lives under `toolResponse.raw`;
+ * response metadata lives under `toolResponse.meta`. Semantic single-value
+ * getters live under `extractedValues.<name>.get()`, and list getters live
+ * under `extractedLists.<name>.get()`.
+ *
+ * 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.
+ */
 type ToolExecuteResult<TResult = unknown, TMeta = Record<string, unknown>, TExtracted extends Record<string, unknown> = Record<string, unknown>, TLists extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>> = ToolExecuteResultBase<TResult, TMeta> & ToolExecuteResultAccessors<TExtracted, TLists>;
 
 /**
@@ -1915,10 +1970,20 @@ type LoosePlayObject = {
     [key: string]: LoosePlayObject;
 };
 
+/**
+ * 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.
+ */
 type ToolExecutionRequest = {
+    /** Stable logical id for this tool call within the play. */
     id: string;
+    /** Current tool id from `deepline tools search` / `deepline tools describe`. */
     tool: string;
+    /** JSON-serializable provider/tool input object. */
     input: Record<string, unknown>;
+    /** Human-readable description for logs and run inspection. */
     description?: string;
     staleAfterSeconds?: number;
 };
@@ -1950,7 +2015,29 @@ type PlayStepProgramStep = {
 };
 type MapStepResolver<Row, Value> = StepResolver<Row, Value> | ConditionalStepResolver<Row, Value> | StepProgramResolver<Row, Value>;
 type MapStepBuilder<InputRow extends object, OutputRow extends object> = {
+    /**
+     * Define one output column for every row in this map dataset.
+     *
+     * The `name` becomes a field on each output row. For example,
+     * `.step('contact', ...)` creates `row.contact` in later map stages; it does
+     * not spread returned object fields such as `contact.email` into `row.email`.
+     * Add a later column resolver when you want a top-level export field:
+     * `.step('email', row => row.contact?.email ?? null)`.
+     *
+     * @param name - Output column name.
+     * @param resolver - Computes the value for one row.
+     * @returns The same map builder with the new column type.
+     */
     step<Name extends string, Value>(name: Name, resolver: MapStepResolver<OutputRow, Value>): MapStepBuilder<InputRow, OutputRow & Record<Name, Value>>;
+    /**
+     * Execute the row-column program and return a durable dataset handle.
+     *
+     * The returned {@link PlayDataset} preserves one output row per input row,
+     * with original fields merged with the columns produced by `.step(...)`.
+     *
+     * @param options - Run options.
+     * @returns Output rows as a dataset handle.
+     */
     run(options?: {
         description?: string;
         staleAfterSeconds?: number;
@@ -1977,10 +2064,15 @@ 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(...)`. */
 type CsvOptions = {
+    /** Human-readable description for runtime logs and inspection. */
     description?: string;
+    /** Canonical field-to-header aliases, e.g. `{ domain: ['domain', 'Company Domain'] }`. */
     columns?: CsvRenameMap;
+    /** Header rename map; use `columns` for new code. */
     rename?: CsvRenameMap;
+    /** Canonical fields that must be present after header normalization. */
     required?: readonly string[];
 };
 /**
@@ -2030,41 +2122,47 @@ type CsvOptions = {
  */
 interface DeeplinePlayRuntimeContext {
     /**
-     * Load a CSV file as a dataset handle.
+     * Load a staged CSV file as a durable dataset handle.
+     *
+     * Use this when a play receives a CSV path from the CLI or API and row work
+     * should continue through {@link DeeplinePlayRuntimeContext.map}. The path is
+     * normally an input field such as `input.csv`, populated by
+     * `deepline plays run my.play.ts --csv rows.csv`.
      *
-     * The CSV must be staged or available at the given path. Each row becomes
-     * an object keyed by column headers.
+     * Each CSV row becomes an object keyed by canonical column names. Use
+     * `options.columns` / `options.rename` to map user headers such as
+     * `"Company Domain"` to stable code fields such as `domain`.
      *
      * @typeParam T - Row type (defaults to `Record<string, unknown>`)
-     * @param path - Relative path to the CSV file
-     * The returned dataset supports `for await`, `peek()`, `count()`, and
-     * explicit `materialize()` for small result sets.
+     * @param path - Staged CSV path.
+     * @param options - CSV load options.
      *
-     * @returns Parsed dataset rows
+     * @returns A {@link PlayDataset} whose rows should usually flow directly into `ctx.map(...)`.
      */
     csv<T = Record<string, unknown>>(path: string, options?: CsvOptions): Promise<PlayDataset<T>>;
     /**
-     * Fan-out: process each item through one or more named columns.
+     * Create a persisted row dataset/table from input rows.
      *
-     * Each key in `columns` becomes an output column. Each value is an async
-     * callback `(row, ctx) => result` that receives the current row and the
-     * play context — call tools, run waterfalls, do arbitrary logic.
+     * `ctx.map` is Deepline's row-work primitive. It records row identity,
+     * progress, retries, table output, and idempotency for a collection of rows.
+     * Use `.step(name, resolver)` on the returned builder to define output
+     * columns, then `.run(...)` to execute the row program.
      *
-     * Items are processed in parallel (paced by the rate-limit scheduler).
-     * `key` identifies the logical output dataset/table. Row identity is derived
-     * automatically from item content unless advanced run options override it.
-     * `options.staleAfterSeconds` intentionally partitions the durable cache on a
-     * relative time window. Use `86400` for daily reruns; retries inside the same
-     * window still replay safely.
+     * The `key` identifies the logical dataset/table. Renaming it is a persistence
+     * migration: existing rows may no longer be reused. Row identity is derived
+     * automatically from input row content unless `.run({ key: ... })` overrides
+     * it with stable business fields such as `domain`, `email`, or `linkedin_url`.
      *
-     * Returns a dataset handle containing the original rows merged with the new
-     * columns. Input may be a normal array, iterable, async iterable, or another
-     * play dataset handle.
+     * By default, `ctx.map` is row-preserving: one input row produces one output
+     * row, with original fields merged with the columns produced by
+     * `.step(...)`. If one input entity must become many output rows, use the
+     * documented expand/flatten recipe instead of assuming `ctx.map` changes
+     * row cardinality.
      *
      * @typeParam T - Row type
-     * @param key - Logical output dataset/table name (e.g. `'companies'`, `'email_lookup'`)
-     * @param items - Input rows or dataset handle
-     * @returns Dataset of rows merged with the computed column values
+     * @param key - Dataset/table name.
+     * @param items - Input rows.
+     * @returns A builder. Calling `.run()` returns a `PlayDataset` of rows plus computed columns.
      *
      * @example Single tool per row
      * ```typescript
@@ -2103,21 +2201,71 @@ interface DeeplinePlayRuntimeContext {
         /**
          * Execute a single tool with a keyword-style request object.
          *
-         * @param request.id - Stable step key for idempotent execution
-         * @param request.tool - Tool identifier (e.g. `'test_company_search'`)
-         * @param request.input - Tool-specific input parameters
-         * @returns The tool's output
+         * @param request - Tool call request.
+         * @returns Tool execution result.
          */
         execute<TOutput = LoosePlayObject>(request: ToolExecutionRequest & {
             staleAfterSeconds?: number;
         }): Promise<ToolExecuteResult<TOutput>>;
     };
+    /**
+     * Execute a single tool by stable step key and tool ID.
+     *
+     * Shorthand for `ctx.tools.execute(...)`; this is the preferred spelling in
+     * row-level step programs.
+     */
+    tool<TOutput = LoosePlayObject>(key: string, toolId: string, input: Record<string, unknown>, options?: {
+        description?: string;
+    }): Promise<ToolExecuteResult<TOutput>>;
+    /**
+     * Run a reusable step program against one scalar input object.
+     *
+     * `steps().step(...)` is a composable mini-pipeline. Use `ctx.runSteps(...)`
+     * when that mini-pipeline should execute outside a row dataset. Inside a
+     * `ctx.map` column resolver, pass the step program directly to
+     * `.step(name, program)` instead.
+     *
+     * @param program - Step program.
+     * @param input - Program input.
+     * @param options - Run options.
+     * @returns Program output.
+     */
     runSteps<TInput extends Record<string, unknown>, TOutput>(program: StepProgram<TInput, unknown, TOutput>, input: TInput, options?: {
         description?: string;
     }): Promise<TOutput>;
+    /**
+     * Create one scalar checkpoint for the whole play run.
+     *
+     * Use `ctx.step` when a value is nondeterministic, expensive, external, or
+     * useful to inspect as a named boundary. The first execution stores the
+     * JSON-serializable output under `id`; replay and retries return the stored
+     * value instead of running `run` again.
+     *
+     * Plain deterministic assignment does not need `ctx.step`. Use
+     * `ctx.map(...).step(...)`, not `ctx.step`, when the value should become a
+     * field on each exported row.
+     *
+     * @param id - Checkpoint id.
+     * @param run - Computes the value once.
+     * @param options - Checkpoint options.
+     * @returns Checkpoint value.
+     */
     step<T>(id: string, run: () => T | Promise<T>, options?: {
         staleAfterSeconds?: number;
     }): Promise<T>;
+    /**
+     * Durable HTTP fetch.
+     *
+     * Use this for non-provider HTTP calls that must replay safely. The response
+     * is recorded under `key` so workflow replay sees the same value. Prefer
+     * `ctx.tools.execute(...)` for Deepline-managed provider APIs because tools
+     * handle auth, retries, rate limits, extraction metadata, and spend tracking.
+     *
+     * @param key - Checkpoint id.
+     * @param url - URL to fetch.
+     * @param init - Fetch options.
+     * @returns Recorded response.
+     */
     fetch(key: string, url: string | URL, init?: RequestInit, options?: {
         staleAfterSeconds?: number;
     }): Promise<{
@@ -2129,6 +2277,22 @@ interface DeeplinePlayRuntimeContext {
         bodyText: string;
         json: unknown | null;
     }>;
+    /**
+     * Invoke another registered or file-backed play as a child workflow.
+     *
+     * Use this for real composition boundaries, especially when a fitting
+     * scalar prebuilt play already encodes provider order, fallbacks,
+     * normalization, and no-result behavior. Do not invoke plays through
+     * `ctx.tools.execute`; tools and plays are separate namespaces.
+     *
+     * `key` is the stable child-call identity for idempotency and traceability.
+     *
+     * @param key - Child call id.
+     * @param playRef - Play name or handle.
+     * @param input - Child input.
+     * @param options - Run options.
+     * @returns Child play output.
+     */
     runPlay(key: string, playRef: string | PlayReferenceLike, input: Record<string, unknown>, options: {
         description?: string;
         staleAfterSeconds?: number;
@@ -2313,11 +2477,24 @@ type PlayInputContract<TInput> = {
     readonly schema: Record<string, unknown>;
     readonly __inputType?: TInput;
 };
+/**
+ * Object-form play definition accepted by `definePlay(config)`.
+ *
+ * Use this form when the input contract should be explicit at definition time
+ * 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.
+ */
 type DefinePlayConfig<TInput, TOutput extends PlayReturnObject> = {
+    /** Play id/name. */
     id: string;
+    /** Input schema. */
     input: PlayInputContract<TInput>;
+    /** Play function. */
     run: (ctx: DeeplinePlayRuntimeContext, input: TInput) => Promise<TOutput>;
+    /** Trigger bindings. */
     bindings?: PlayBindings;
+    /** Billing options. */
     billing?: PlayBindings['billing'];
 };
 declare function steps<TInput>(): StepProgram<TInput, TInput, TInput>;
@@ -2482,9 +2659,10 @@ declare function defineInput<TInput>(schema: Record<string, unknown>): PlayInput
  *
  * @typeParam TInput - The input type accepted by the play
  * @typeParam TOutput - The return type of the play
- * @param name - Unique play name (used for publishing, running by name, and CLI reference)
- * @param fn - Async function that receives a {@link DeeplinePlayRuntimeContext} and typed input
- * @param bindings - Optional trigger bindings (cron schedule, webhook with HMAC)
+ * @param config - Object-form play config.
+ * @param name - Play name.
+ * @param fn - Play function.
+ * @param bindings - Trigger bindings.
  * @returns A {@link DefinedPlay} that is both callable and has lifecycle methods
  *
  * @example Basic play
@@ -2505,9 +2683,9 @@ declare function defineInput<TInput>(schema: Record<string, unknown>): PlayInput
  *
  * @example CSV processing play
  * ```typescript
- * export default definePlay('bulk-enrich', async (ctx) => {
- *   const leads = await ctx.csv('leads.csv');
- *   ctx.log(`Processing ${leads.length} rows`);
+ * export default definePlay('bulk-enrich', async (ctx, input: { csv: string }) => {
+ *   const leads = await ctx.csv(input.csv);
+ *   ctx.log(`Processing ${await leads.count()} rows`);
  *   const results = await ctx
  *     .map('companies', leads)
  *     .step('company', (row, ctx) =>
@@ -2552,6 +2730,14 @@ declare function defineInput<TInput>(schema: Record<string, unknown>): PlayInput
  * ```
  */
 declare function definePlay<TInput, TOutput extends PlayReturnObject>(config: DefinePlayConfig<TInput, TOutput>): DefinedPlay<TInput, TOutput>;
+/**
+ * Define a play with a name and function.
+ *
+ * @param name - Play name.
+ * @param fn - Play function.
+ * @param bindings - Trigger bindings.
+ * @returns Play handle.
+ */
 declare function definePlay<TInput, TOutput extends PlayReturnObject>(name: string, fn: (ctx: DeeplinePlayRuntimeContext, input: TInput) => Promise<TOutput>, bindings?: PlayBindings): DefinedPlay<TInput, TOutput>;
 /**
  * Alias for {@link definePlay}. Workflows and plays share the same public