deepline 0.1.55 → 0.1.57

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

@@ -161,10 +161,20 @@ export type {
   ToolResultTargetAccessor as ToolExtractedValue,
 } from '../../shared_libs/play-runtime/tool-result-types.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.
+ */
 export 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;
 };
@@ -226,10 +236,32 @@ export 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;
@@ -270,10 +302,15 @@ export type ColumnMap<TRow extends object> = Partial<
   Record<Extract<keyof TRow, string>, string | readonly string[]>
 >;
 
+/** Options for loading a staged CSV with `ctx.csv(...)`. */
 export 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[];
 };
 
@@ -324,17 +361,22 @@ export type CsvOptions = {
  */
 export interface DeeplinePlayRuntimeContext {
   /**
-   * Load a CSV file as a dataset handle.
+   * Load a staged CSV file as a durable dataset handle.
    *
-   * The CSV must be staged or available at the given path. Each row becomes
-   * an object keyed by column headers.
+   * 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`.
+   *
+   * 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,
@@ -342,27 +384,28 @@ export interface DeeplinePlayRuntimeContext {
   ): 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
@@ -405,25 +448,78 @@ export 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,
@@ -438,6 +534,22 @@ export 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,
@@ -646,11 +758,24 @@ export type PlayInputContract<TInput> = {
   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.
+ */
 export 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'];
 };
 
@@ -1184,9 +1309,10 @@ export function defineInput<TInput>(
  *
  * @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
@@ -1207,9 +1333,9 @@ export function defineInput<TInput>(
  *
  * @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) =>
@@ -1256,6 +1382,14 @@ export function defineInput<TInput>(
 export 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.
+ */
 export function definePlay<TInput, TOutput extends PlayReturnObject>(
   name: string,
   fn: (ctx: DeeplinePlayRuntimeContext, input: TInput) => Promise<TOutput>,

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

@@ -50,10 +50,10 @@ export type SdkRelease = {
 };
 
 export const SDK_RELEASE = {
-  version: '0.1.55',
-  apiContract: '2026-05-run-response-package',
+  version: '0.1.57',
+  apiContract: '2026-05-play-tool-describe-starters',
   supportPolicy: {
-    latest: '0.1.55',
+    latest: '0.1.57',
     minimumSupported: '0.1.53',
     deprecatedBelow: '0.1.53',
   },

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

@@ -125,6 +125,22 @@ export 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?: {
@@ -637,6 +653,11 @@ export 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;

package/dist/repo/shared_libs/play-runtime/csv-rename.ts

@@ -8,10 +8,12 @@ export type CsvRenameOptions = {
 
 const CSV_PROJECTED_FIELDS = Symbol.for('deepline.play.csv.projected_fields');
 const CSV_PROJECTED_FIELDS_KEY = '__deeplineCsvProjectedFields';
+const CSV_PROJECTED_VALUES_KEY = '__deeplineCsvProjectedValues';
 
 type ProjectedRow = Record<string, unknown> & {
   [CSV_PROJECTED_FIELDS]?: ReadonlySet<string>;
   [CSV_PROJECTED_FIELDS_KEY]?: readonly string[];
+  [CSV_PROJECTED_VALUES_KEY]?: Record<string, unknown>;
 };
 
 function normalizeCsvHeader(header: string): string {
@@ -58,6 +60,7 @@ export function applyCsvRenameProjection<T extends Record<string, unknown>>(
   return rows.map((row, index) => {
     const lookup = buildRowLookup(row);
     const projectedFields = new Set<string>();
+    const projectedValues: Record<string, unknown> = {};
     const projected: Record<string, unknown> = { ...row };
 
     for (const [target, sourceNames] of Object.entries(aliases)) {
@@ -81,6 +84,7 @@ export function applyCsvRenameProjection<T extends Record<string, unknown>>(
             writable: true,
           });
           projectedFields.add(target);
+          projectedValues[target] = selected;
         } else {
           projected[target] = selected;
         }
@@ -96,6 +100,20 @@ export function applyCsvRenameProjection<T extends Record<string, unknown>>(
       enumerable: false,
       configurable: true,
     });
+    if (projectedFields.size > 0) {
+      Object.defineProperty(projected, CSV_PROJECTED_FIELDS_KEY, {
+        value: [...projectedFields],
+        enumerable: true,
+        configurable: true,
+        writable: true,
+      });
+      Object.defineProperty(projected, CSV_PROJECTED_VALUES_KEY, {
+        value: projectedValues,
+        enumerable: true,
+        configurable: true,
+        writable: true,
+      });
+    }
     return projected as T & Record<string, unknown>;
   });
 }
@@ -111,6 +129,7 @@ export function cloneCsvAliasedRow<T extends Record<string, unknown>>(
   }
 
   const clonedProjectedFields = new Set<string>();
+  const serializedValues = getCsvProjectedValues(row);
   for (const field of projectedFields) {
     if (Object.prototype.hasOwnProperty.call(cloned, field)) {
       continue;
@@ -124,7 +143,7 @@ export function cloneCsvAliasedRow<T extends Record<string, unknown>>(
       });
     } else {
       Object.defineProperty(cloned, field, {
-        value: row[field],
+        value: serializedValues?.[field] ?? row[field],
         enumerable: false,
         configurable: true,
         writable: true,
@@ -139,6 +158,20 @@ export function cloneCsvAliasedRow<T extends Record<string, unknown>>(
       enumerable: false,
       configurable: true,
     });
+    Object.defineProperty(cloned, CSV_PROJECTED_FIELDS_KEY, {
+      value: [...clonedProjectedFields],
+      enumerable: true,
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(cloned, CSV_PROJECTED_VALUES_KEY, {
+      value: Object.fromEntries(
+        [...clonedProjectedFields].map((field) => [field, cloned[field]]),
+      ),
+      enumerable: true,
+      configurable: true,
+      writable: true,
+    });
   }
   return cloned;
 }
@@ -153,6 +186,7 @@ export function stripCsvProjectedFields<T extends Record<string, unknown>>(
     delete stripped[field];
   }
   delete stripped[CSV_PROJECTED_FIELDS_KEY];
+  delete stripped[CSV_PROJECTED_VALUES_KEY];
   return stripped as T;
 }
 
@@ -168,13 +202,31 @@ export function getCsvProjectedFields(
   return new Set(serializedFields.filter((field) => typeof field === 'string'));
 }
 
+function getCsvProjectedValues(
+  row: Record<string, unknown>,
+): Record<string, unknown> | null {
+  const serializedValues = (row as ProjectedRow)[CSV_PROJECTED_VALUES_KEY];
+  if (
+    !serializedValues ||
+    typeof serializedValues !== 'object' ||
+    Array.isArray(serializedValues)
+  ) {
+    return null;
+  }
+  return serializedValues;
+}
+
 export function stripCsvProjectionMetadata<T extends Record<string, unknown>>(
   row: T,
 ): T {
-  if (!Object.prototype.hasOwnProperty.call(row, CSV_PROJECTED_FIELDS_KEY)) {
+  if (
+    !Object.prototype.hasOwnProperty.call(row, CSV_PROJECTED_FIELDS_KEY) &&
+    !Object.prototype.hasOwnProperty.call(row, CSV_PROJECTED_VALUES_KEY)
+  ) {
     return row;
   }
-  const stripped = { ...row };
+  const stripped = cloneCsvAliasedRow(row) as T;
   delete stripped[CSV_PROJECTED_FIELDS_KEY];
+  delete stripped[CSV_PROJECTED_VALUES_KEY];
   return stripped as T;
 }

package/dist/repo/shared_libs/plays/dataset.ts

@@ -55,14 +55,34 @@ export type PlayDatasetInput<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.
+ */
 export 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.
@@ -310,7 +330,11 @@ export async function materializePlayDatasetInput<T>(
   input: PlayDatasetInput<T>,
 ): Promise<T[]> {
   if (isPlayDataset(input)) {
-    return await input.materialize();
+    const rows: T[] = [];
+    for await (const row of input) {
+      rows.push(row);
+    }
+    return rows;
   }
 
   if (Array.isArray(input)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepline",
-  "version": "0.1.55",
+  "version": "0.1.57",
   "description": "Deepline SDK + CLI — B2B data enrichment powered by durable cloud execution",
   "license": "MIT",
   "repository": {