deepline 0.1.54 → 0.1.56

package/dist/repo/apps/play-runner-workers/src/runtime/dataset-handles.ts

@@ -1,5 +1,7 @@
 import {
   applyCsvRenameProjection,
+  stripCsvProjectedFields,
+  stripCsvProjectionMetadata,
   type CsvRenameOptions,
 } from '../../../../shared_libs/play-runtime/csv-rename';
 import {
@@ -38,7 +40,32 @@ const datasetCountHints = new WeakMap<object, number | null>();
 const datasetCapabilities = new WeakMap<object, WorkerDatasetCapabilities>();
 
 function cloneRow<T extends DatasetRow>(row: T): T {
-  return { ...row };
+  const cloned: DatasetRow = {};
+  for (const key of Reflect.ownKeys(row)) {
+    const descriptor = Object.getOwnPropertyDescriptor(row, key);
+    if (!descriptor) continue;
+    Object.defineProperty(cloned, key, descriptor);
+  }
+  return cloned as T;
+}
+
+function internalDatasetRow<T extends DatasetRow>(row: T): T {
+  const stripped = stripCsvProjectionMetadata(row) as DatasetRow;
+  const publicRow: DatasetRow = {};
+  for (const key of Reflect.ownKeys(stripped)) {
+    if (typeof key === 'string' && key.startsWith('__deepline')) continue;
+    const descriptor = Object.getOwnPropertyDescriptor(stripped, key);
+    if (!descriptor) continue;
+    Object.defineProperty(publicRow, key, descriptor);
+  }
+  return publicRow as T;
+}
+
+function materializedDatasetRow<T extends DatasetRow>(row: T): T {
+  const stripped = stripCsvProjectedFields(row) as DatasetRow;
+  return Object.fromEntries(
+    Object.entries(stripped).filter(([key]) => !key.startsWith('__deepline')),
+  ) as T;
 }
 
 function registerChunkReader<T extends DatasetRow>(
@@ -138,10 +165,10 @@ export function createPersistedDatasetHandle<T extends DatasetRow>(input: {
   const count = Math.max(0, Math.floor(input.count));
   const previewRows = (input.previewRows ?? [])
     .slice(0, WORKER_DATASET_PREVIEW_ROWS)
-    .map(cloneRow);
+    .map(materializedDatasetRow);
   const cachedRows =
     input.cachedRows && input.cachedRows.length <= WORKER_DATASET_IN_MEMORY_ROWS
-      ? input.cachedRows.map(cloneRow)
+      ? input.cachedRows.map(internalDatasetRow)
       : null;
 
   async function loadRows(limit: number, offset: number): Promise<T[]> {
@@ -157,7 +184,7 @@ export function createPersistedDatasetHandle<T extends DatasetRow>(input: {
     ) {
       return cachedRows
         .slice(normalizedOffset, normalizedOffset + normalizedLimit)
-        .map(cloneRow);
+        .map(internalDatasetRow);
     }
     const startedAt = input.nowMs();
     const rows = await input.readRows({
@@ -172,7 +199,7 @@ export function createPersistedDatasetHandle<T extends DatasetRow>(input: {
       offset: normalizedOffset,
       rows: rows.length,
     });
-    return rows.map(cloneRow);
+    return rows.map(internalDatasetRow);
   }
 
   async function* readChunks(chunkSize: number): AsyncGenerator<T[], void, void> {
@@ -205,14 +232,15 @@ export function createPersistedDatasetHandle<T extends DatasetRow>(input: {
     workProgress: input.workProgress,
     resolvers: {
       count: async () => count,
-      peek: async (limit) => await loadRows(Math.max(0, limit), 0),
+      peek: async (limit) =>
+        (await loadRows(Math.max(0, limit), 0)).map(materializedDatasetRow),
       materialize: async (limit) => {
         const rows: T[] = [];
         const maxRows = limit ?? count;
         for await (const chunk of readChunks(STREAM_MATERIALIZE_CHUNK_ROWS)) {
           for (const row of chunk) {
             if (rows.length >= maxRows) return rows;
-            rows.push(row);
+            rows.push(materializedDatasetRow(row));
           }
         }
         return rows;

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

@@ -485,6 +485,37 @@ export class DeeplineClient {
     return `deepline plays run ${target} --input '{...}' --watch`;
   }
 
+  private starterPlayPath(play: Pick<PlayListItem, 'name' | 'reference'>): string {
+    const target = play.reference || play.name;
+    const unqualifiedName = target.split('/').pop() || play.name;
+    const safeName = unqualifiedName
+      .trim()
+      .toLowerCase()
+      .replace(/[^a-z0-9-]/g, '-')
+      .replace(/-+/g, '-')
+      .replace(/^-|-$/g, '');
+    return `./${safeName || 'play'}.play.ts`;
+  }
+
+  private playCloneEditStarter(
+    play: Pick<
+      PlayListItem,
+      'name' | 'reference' | 'canClone' | 'canEdit' | 'origin' | 'ownerType'
+    >,
+  ): PlayDescription['cloneEditStarter'] | undefined {
+    const readonlyPrebuilt =
+      (play.origin === 'prebuilt' || play.ownerType === 'deepline') &&
+      !play.canEdit;
+    if (!play.canClone && !readonlyPrebuilt) return undefined;
+    const target = play.reference || play.name;
+    const path = this.starterPlayPath(play);
+    return {
+      path,
+      command: `deepline plays get ${target} --source --out ${path}`,
+      checkCommand: `deepline plays check ${path}`,
+    };
+  }
+
   private summarizePlayListItem(
     play: PlayListItem,
     options?: { compact?: boolean },
@@ -496,6 +527,7 @@ export class DeeplineClient {
       'rowOutputSchema',
     );
     const runCommand = this.playRunCommand(play, { csvInput });
+    const cloneEditStarter = this.playCloneEditStarter(play);
     return {
       name: play.name,
       ...(play.reference ? { reference: play.reference } : {}),
@@ -515,6 +547,7 @@ export class DeeplineClient {
       ...(rowOutputSchema ? { rowOutputSchema } : {}),
       runCommand,
       examples: [runCommand],
+      ...(cloneEditStarter ? { cloneEditStarter } : {}),
       currentPublishedVersion: play.currentPublishedVersion ?? null,
       isDraftDirty: play.isDraftDirty,
     };
@@ -1472,12 +1505,10 @@ export class DeeplineClient {
 
   async searchPlays(options: {
     query: string;
-    origin?: 'prebuilt' | 'owned';
     compact?: boolean;
   }): Promise<PlayDescription[]> {
     const params = new URLSearchParams();
     params.set('search', options.query.trim());
-    if (options.origin) params.set('origin', options.origin);
     const response = await this.http.get<{ plays: PlayListItem[] }>(
       `/api/v2/plays?${params.toString()}`,
     );

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/plays/bundle-play-file.ts

@@ -14,13 +14,10 @@ import {
 } from '../../../shared_libs/plays/bundling/index.js';
 import {
   PLAY_ARTIFACT_KINDS,
-  PLAY_BACKEND_DESCRIPTORS,
   type PlayArtifactKind,
 } from '../../../shared_libs/play-runtime/backend.js';
 import { resolveExecutionProfile } from '../../../shared_libs/play-runtime/profiles.js';
-import {
-  discoverPackagedLocalFiles,
-} from './local-file-discovery.js';
+import { discoverPackagedLocalFiles } from './local-file-discovery.js';
 
 export type {
   BundlePlayFileOptions,
@@ -39,9 +36,7 @@ export type {
   PlayRuntimeFeature,
 } from '../../../shared_libs/plays/bundling/index.js';
 
-export {
-  extractDefinedPlayName,
-} from '../../../shared_libs/plays/bundling/index.js';
+export { extractDefinedPlayName } from '../../../shared_libs/plays/bundling/index.js';
 
 const PLAY_BUNDLE_CACHE_VERSION = 30;
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
@@ -57,21 +52,32 @@ const HAS_PACKAGED_BUNDLING_SOURCES = existsSync(
 const PROJECT_ROOT = HAS_SOURCE_BUNDLING_SOURCES
   ? SOURCE_REPO_ROOT
   : HAS_PACKAGED_BUNDLING_SOURCES
-  ? PACKAGED_REPO_ROOT
-  : resolve(SDK_PACKAGE_ROOT, '..');
+    ? PACKAGED_REPO_ROOT
+    : resolve(SDK_PACKAGE_ROOT, '..');
 const SDK_SOURCE_ROOT = HAS_SOURCE_BUNDLING_SOURCES
   ? resolve(SOURCE_REPO_ROOT, 'sdk', 'src')
   : HAS_PACKAGED_BUNDLING_SOURCES
-  ? resolve(PACKAGED_REPO_ROOT, 'sdk', 'src')
-  : resolve(SDK_PACKAGE_ROOT, 'src');
+    ? resolve(PACKAGED_REPO_ROOT, 'sdk', 'src')
+    : resolve(SDK_PACKAGE_ROOT, 'src');
 const SDK_PACKAGE_JSON = resolve(SDK_PACKAGE_ROOT, 'package.json');
 const SDK_ENTRY_FILE = resolve(SDK_SOURCE_ROOT, 'index.ts');
 const SDK_TYPES_ENTRY_FILE = HAS_SOURCE_BUNDLING_SOURCES
   ? SDK_ENTRY_FILE
   : resolve(SDK_PACKAGE_ROOT, 'dist', 'index.d.ts');
 const SDK_WORKERS_ENTRY_FILE = resolve(SDK_SOURCE_ROOT, 'worker-play-entry.ts');
-const WORKERS_HARNESS_ENTRY_FILE = resolve(PROJECT_ROOT, 'apps', 'play-runner-workers', 'src', 'entry.ts');
-const WORKERS_HARNESS_FILES_DIR = resolve(PROJECT_ROOT, 'apps', 'play-runner-workers', 'src');
+const WORKERS_HARNESS_ENTRY_FILE = resolve(
+  PROJECT_ROOT,
+  'apps',
+  'play-runner-workers',
+  'src',
+  'entry.ts',
+);
+const WORKERS_HARNESS_FILES_DIR = resolve(
+  PROJECT_ROOT,
+  'apps',
+  'play-runner-workers',
+  'src',
+);
 let hasWarnedAboutNonDevelopmentBundling = false;
 
 /**
@@ -93,7 +99,9 @@ function warnAboutNonDevelopmentBundling(filePath: string): void {
     return;
   }
 
-  const nodeEnv = String(process.env.NODE_ENV ?? '').trim().toLowerCase();
+  const nodeEnv = String(process.env.NODE_ENV ?? '')
+    .trim()
+    .toLowerCase();
   if (!nodeEnv || nodeEnv === 'development' || nodeEnv === 'test') {
     return;
   }
@@ -111,16 +119,17 @@ function warnAboutNonDevelopmentBundling(filePath: string): void {
 }
 
 function defaultPlayBundleTarget(): PlayArtifactKind {
-  return PLAY_BACKEND_DESCRIPTORS[
-    resolveExecutionProfile(null).runner
-  ].artifactKind;
+  return resolveExecutionProfile(null).artifactKind;
 }
 
 export function createSdkPlayBundlingAdapter(): PlayBundlingAdapter {
   return {
     projectRoot: PROJECT_ROOT,
     nodeModulesDir: resolve(PROJECT_ROOT, 'node_modules'),
-    cacheDir: join(tmpdir(), `deepline-play-artifacts-v${PLAY_BUNDLE_CACHE_VERSION}`),
+    cacheDir: join(
+      tmpdir(),
+      `deepline-play-artifacts-v${PLAY_BUNDLE_CACHE_VERSION}`,
+    ),
     sdkSourceRoot: SDK_SOURCE_ROOT,
     sdkPackageJson: SDK_PACKAGE_JSON,
     sdkEntryFile: SDK_ENTRY_FILE,

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

@@ -50,10 +50,10 @@ export type SdkRelease = {
 };
 
 export const SDK_RELEASE = {
-  version: '0.1.54',
-  apiContract: '2026-05-run-response-package',
+  version: '0.1.56',
+  apiContract: '2026-05-play-tool-describe-starters',
   supportPolicy: {
-    latest: '0.1.54',
+    latest: '0.1.56',
     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;