deepline 0.1.122 → 0.1.124

package/README.md

@@ -320,14 +320,13 @@ scripts/repro-rate-limit-enrich.sh redis_429
 scripts/repro-rate-limit-enrich.sh redis_429_waterfall
 ```
 
-## Transpiling native plays
+## Prebuilt plays
 
-Convert V1 native `PlayDocument` definitions to V2 `definePlay()` files:
+V2 prebuilt play sources are authored directly in `src/lib/plays/v2/`. After
+editing them, regenerate the committed Workers and share-page artifacts:
 
 ```bash
-bun scripts/transpile-native-plays.ts                     # all -> src/lib/plays/generated/v2/
-bun scripts/transpile-native-plays.ts --play test_play     # single play
-bun scripts/transpile-native-plays.ts --stdout             # print to stdout
+bun scripts/regen.ts workers-prebuilt prebuilt-share-pages
 ```
 
 ## File structure

package/dist/bundling-sources/apps/play-runner-workers/src/coordinator-entry.ts

@@ -1655,6 +1655,8 @@ async function registerInlineChildRunWithRuntime(input: {
       action: 'start_inline_child_run',
       playName: input.childPlayName,
       runId: input.childRunId,
+      parentRunId: input.governance.parentRunId,
+      rootRunId: input.governance.rootRunId,
       workflowFamilyKey:
         input.governance.rootRunId ??
         input.governance.parentRunId ??
@@ -1762,6 +1764,7 @@ async function prepareInlineChildRunWithRuntime(input: {
     body: {
       action: 'prepare_inline_child_run',
       parentRunId: input.parentRunId,
+      rootRunId: input.governance.rootRunId,
       parentPlayName: input.parentPlayName,
       childRunId: input.childRunId,
       childPlayName: input.childPlayName,

package/dist/bundling-sources/apps/play-runner-workers/src/entry.ts

@@ -5567,6 +5567,8 @@ async function registerInlineChildRun(req: RunRequest): Promise<void> {
     action: 'start_inline_child_run',
     playName: req.playName,
     runId: req.runId,
+    parentRunId: governance?.parentRunId,
+    rootRunId: governance?.rootRunId,
     workflowFamilyKey:
       governance?.rootRunId ?? governance?.parentRunId ?? req.runId,
     artifactStorageKey:

package/dist/bundling-sources/sdk/src/client.ts

@@ -60,6 +60,7 @@ import type {
   PlayListItem,
   PlayDescription,
   StopPlayRunResult,
+  StopAllPlayRunsResult,
   ClearPlayHistoryRequest,
   ClearPlayHistoryResult,
   PublishPlayVersionRequest,
@@ -186,8 +187,9 @@ export type ToolExecution<TData = unknown, TMeta = Record<string, unknown>> = {
 
 /** Filters for `client.runs.list(...)`. */
 export type RunsListOptions = {
-  play: string;
+  play?: string;
   status?: string;
+  limit?: number;
 };
 
 /** Streaming options for `client.runs.tail(...)`. */
@@ -323,6 +325,8 @@ export type RunsNamespace = {
     runId: string,
     options?: { reason?: string },
   ) => Promise<StopPlayRunResult>;
+  /** Stop active runs across the current workspace. */
+  stopAll: (options?: { reason?: string }) => Promise<StopAllPlayRunsResult>;
 };
 
 /** One credit grant pool reported by the billing subscription status endpoint. */
@@ -822,6 +826,7 @@ export class DeeplineClient {
       logs: (runId, options) => this.getRunLogs(runId, options),
       exportDatasetRows: (input) => this.getPlaySheetRows(input),
       stop: (runId, options) => this.stopRun(runId, options),
+      stopAll: (options) => this.stopAllRuns(options),
     };
     this.billing = {
       plans: () => this.getBillingPlans(),
@@ -927,12 +932,18 @@ export class DeeplineClient {
       play.outputSchema,
       'rowOutputSchema',
     );
+    const description =
+      play.description?.trim() ||
+      play.currentRevision?.description?.trim() ||
+      play.liveRevision?.description?.trim() ||
+      null;
     const runCommand = this.playRunCommand(play, { csvInput });
     const cloneEditStarter = this.playCloneEditStarter(play);
     return {
       name: play.name,
       ...(play.reference ? { reference: play.reference } : {}),
       ...(play.displayName ? { displayName: play.displayName } : {}),
+      ...(description ? { description } : {}),
       origin: play.origin,
       ownerType: play.ownerType,
       canEdit: play.canEdit,
@@ -1207,6 +1218,7 @@ export class DeeplineClient {
           : {}),
         ...(request.sourceCode ? { sourceCode: request.sourceCode } : {}),
         ...(request.sourceFiles ? { sourceFiles: request.sourceFiles } : {}),
+        ...(request.description ? { description: request.description } : {}),
         ...('staticPipeline' in request
           ? { staticPipeline: request.staticPipeline }
           : {}),
@@ -1265,6 +1277,7 @@ export class DeeplineClient {
         : {}),
       ...(request.sourceCode ? { sourceCode: request.sourceCode } : {}),
       ...(request.sourceFiles ? { sourceFiles: request.sourceFiles } : {}),
+      ...(request.description ? { description: request.description } : {}),
       ...('staticPipeline' in request
         ? { staticPipeline: request.staticPipeline }
         : {}),
@@ -1317,6 +1330,7 @@ export class DeeplineClient {
     name: string;
     sourceCode: string;
     sourceFiles?: Record<string, string>;
+    description?: string;
     artifact: Record<string, unknown>;
     compilerManifest?: PlayCompilerManifest;
     publish?: boolean;
@@ -1366,6 +1380,7 @@ export class DeeplineClient {
       name: string;
       sourceCode: string;
       sourceFiles?: Record<string, string>;
+      description?: string;
       artifact: Record<string, unknown>;
       compilerManifest?: PlayCompilerManifest;
       publish?: boolean;
@@ -1491,6 +1506,7 @@ export class DeeplineClient {
     name?: string;
     sourceCode: string;
     sourceFiles?: Record<string, string>;
+    description?: string;
     artifact: Record<string, unknown>;
   }): Promise<PlayCheckResult> {
     return this.http.post('/api/v2/plays/check', input);
@@ -1520,6 +1536,7 @@ export class DeeplineClient {
     name: string;
     sourceCode: string;
     sourceFiles?: Record<string, string>;
+    description?: string;
     artifact: Record<string, unknown>;
     compilerManifest?: PlayCompilerManifest;
     input?: Record<string, unknown>;
@@ -1539,6 +1556,7 @@ export class DeeplineClient {
       name: input.name,
       sourceCode: input.sourceCode,
       sourceFiles: input.sourceFiles,
+      description: input.description,
       artifact: input.artifact,
       compilerManifest,
       publish: false,
@@ -1552,6 +1570,7 @@ export class DeeplineClient {
     return this.startPlayRun({
       name: input.name,
       artifactStorageKey: registeredArtifact.artifactStorageKey,
+      description: input.description,
       compilerManifest,
       ...(input.input ? { input: input.input } : {}),
       ...(input.inputFile ? { inputFile: input.inputFile } : {}),
@@ -1593,6 +1612,7 @@ export class DeeplineClient {
     options?: {
       sourceCode?: string;
       sourceFiles?: Record<string, string>;
+      description?: string;
       artifact?: Record<string, unknown>;
       compilerManifest?: PlayCompilerManifest;
       input?: Record<string, unknown>;
@@ -1628,6 +1648,7 @@ export class DeeplineClient {
       name,
       sourceCode,
       sourceFiles: options?.sourceFiles,
+      description: options?.description,
       artifact,
       compilerManifest,
       publish: false,
@@ -1642,6 +1663,7 @@ export class DeeplineClient {
       name,
       artifactStorageKey: registeredArtifact.artifactStorageKey,
       sourceCode,
+      description: options?.description,
       staticPipeline: registeredArtifact.staticPipeline ?? null,
       artifactHash:
         typeof artifact.artifactHash === 'string'
@@ -2034,15 +2056,21 @@ export class DeeplineClient {
    * ```
    */
   async listRuns(options: RunsListOptions): Promise<PlayRunListItem[]> {
-    const playName = options.play.trim();
-    if (!playName) {
-      throw new Error('runs.list requires options.play.');
+    const playName = options.play?.trim();
+    const params = new URLSearchParams();
+    if (playName) {
+      params.set('play', playName);
     }
-    const params = new URLSearchParams({ play: playName });
     const status = options.status?.trim();
     if (status) {
       params.set('status', status);
     }
+    if (typeof options.limit === 'number' && Number.isFinite(options.limit)) {
+      params.set('limit', String(Math.max(1, Math.floor(options.limit))));
+    }
+    if (!playName && !status) {
+      throw new Error('runs.list requires options.play or options.status.');
+    }
     params.set('compact', 'true');
     const response = await this.http.get<{ runs: PlayRunListItem[] }>(
       `/api/v2/runs?${params.toString()}`,
@@ -2415,6 +2443,27 @@ export class DeeplineClient {
     );
   }
 
+  /**
+   * Stop every active run visible to the current workspace.
+   *
+   * This is the SDK equivalent of:
+   *
+   * ```bash
+   * deepline runs stop-all --reason "stale lock" --json
+   * ```
+   *
+   * Use this when a failed parent run left child or waiting runs active and you
+   * need to clear the workspace run-slot state without knowing each run id.
+   */
+  async stopAllRuns(options?: {
+    reason?: string;
+  }): Promise<StopAllPlayRunsResult> {
+    return this.http.post<StopAllPlayRunsResult>(
+      '/api/v2/runs/stop-all',
+      options?.reason ? { reason: options.reason } : {},
+    );
+  }
+
   /**
    * List callable plays visible to the workspace.
    *

package/dist/bundling-sources/sdk/src/play.ts

@@ -135,6 +135,14 @@ import type { ToolExecution } from './client.js';
  * @sdkReference runtime 030
  */
 export type PlayBindings = {
+  /**
+   * Human-readable one-line description of what this play does.
+   *
+   * New SDK-authored file workflows require this in `plays check`, `plays run
+   * --file`, and `plays publish <file>`. The server API keeps it optional so
+   * older clients can continue to register revisions during the migration.
+   */
+  description?: string;
   /** Optional per-run billing controls enforced by the runtime. */
   billing?: {
     /** Stop the run before a billed action would push total run credits above this cap. */
@@ -1123,6 +1131,8 @@ export type PlayInputContract<TInput> = {
 export type DefinePlayConfig<TInput, TOutput extends PlayReturnObject> = {
   /** Play id/name. */
   id: string;
+  /** Human-readable one-line description of what this play does. */
+  description?: string;
   /** Input schema. */
   input: PlayInputContract<TInput>;
   /** Play function. */
@@ -1299,6 +1309,7 @@ export type DefinedPlay<TInput, TOutput extends PlayReturnObject> = ((
 
 type PlayMetadata = {
   name: string;
+  description?: string;
   bindings?: PlayBindings;
   inputSchema?: Record<string, unknown>;
   billing?: PlayBindings['billing'];
@@ -1891,6 +1902,7 @@ export function definePlay<TInput, TOutput extends PlayReturnObject>(
           name: nameOrConfig,
           fn: maybeFn,
           bindings: maybeBindings,
+          description: maybeBindings?.description,
           inputSchema: undefined,
           billing: maybeBindings?.billing,
         }
@@ -1898,12 +1910,14 @@ export function definePlay<TInput, TOutput extends PlayReturnObject>(
           name: nameOrConfig.id,
           fn: nameOrConfig.run,
           bindings: nameOrConfig.bindings,
+          description: nameOrConfig.description,
           inputSchema: nameOrConfig.input.schema,
           billing: nameOrConfig.billing,
         };
   const name = config.name;
   const fn = config.fn;
   const bindings = config.bindings;
+  const description = config.description?.trim();
   const billing = config.billing;
   const inputSchema = config.inputSchema;
   if (typeof fn !== 'function') {
@@ -1935,6 +1949,7 @@ export function definePlay<TInput, TOutput extends PlayReturnObject>(
 
   const metadata: PlayMetadata = {
     name,
+    ...(description ? { description } : {}),
     ...(bindings ? { bindings } : {}),
     ...(inputSchema ? { inputSchema } : {}),
     ...(billing ? { billing } : {}),

package/dist/bundling-sources/sdk/src/release.ts

@@ -55,6 +55,7 @@ export type SdkSupportPolicy = {
    */
   commandMinimumSupported?: ReadonlyArray<{
     command: string;
+    displayCommand?: string;
     minimumSupported: string;
     reason: string;
   }>;
@@ -99,10 +100,11 @@ export const SDK_RELEASE = {
   // skill on the sdk sync surface, and the people-search-to-email prebuilt.
   // 0.1.108 ships explicit dataset column/tool recompute policy and removes
   // the SDK enrich generator's one-second stale policy.
-  version: '0.1.122',
+  // 0.1.110 ships authored V2 prebuilts and required top-level play descriptions.
+  version: '0.1.124',
   apiContract: '2026-06-dataset-column-cell-stale-hard-cutover',
   supportPolicy: {
-    latest: '0.1.122',
+    latest: '0.1.124',
     minimumSupported: '0.1.53',
     deprecatedBelow: '0.1.53',
     commandMinimumSupported: [
@@ -112,6 +114,64 @@ export const SDK_RELEASE = {
         reason:
           'Older SDK CLI enrich generated stale play source for the current dataset API.',
       },
+      {
+        command: 'plays',
+        minimumSupported: '0.1.110',
+        reason:
+          'Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays.',
+      },
+      {
+        command: 'plays run',
+        minimumSupported: '0.1.110',
+        reason:
+          'Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays.',
+      },
+      {
+        command: 'run',
+        displayCommand: 'plays run',
+        minimumSupported: '0.1.110',
+        reason:
+          'Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays.',
+      },
+      {
+        command: 'plays check',
+        minimumSupported: '0.1.110',
+        reason:
+          'Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays.',
+      },
+      {
+        command: 'check',
+        displayCommand: 'plays check',
+        minimumSupported: '0.1.110',
+        reason:
+          'Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays.',
+      },
+      {
+        command: 'plays publish',
+        minimumSupported: '0.1.110',
+        reason:
+          'Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays.',
+      },
+      {
+        command: 'publish',
+        displayCommand: 'plays publish',
+        minimumSupported: '0.1.110',
+        reason:
+          'Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays.',
+      },
+      {
+        command: 'plays set-live',
+        minimumSupported: '0.1.110',
+        reason:
+          'Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays.',
+      },
+      {
+        command: 'set-live',
+        displayCommand: 'plays set-live',
+        minimumSupported: '0.1.110',
+        reason:
+          'Play file commands now require top-level definePlay descriptions so agents and play surfaces can explain local plays.',
+      },
     ],
     autoUpdatePatchLag: 2,
   },

package/dist/bundling-sources/sdk/src/types.ts

@@ -557,22 +557,40 @@ export interface StopPlayRunResult {
   error?: string;
 }
 
+export interface StopAllPlayRunsResult {
+  stopped: number;
+  failed: number;
+  skipped: number;
+  partial?: boolean;
+  runs: Array<StopPlayRunResult & { status?: string | null }>;
+}
+
 /**
  * Summary of a single play run, returned by {@link DeeplineClient.listPlayRuns}.
  */
 export interface PlayRunListItem {
   /** Public Deepline play-run id. */
   workflowId: string;
+  /** Saved play name for this run, when available. */
+  playName?: string | null;
   /** Backend run attempt id, when exposed. */
   runId: string;
+  /** Parent play-run id when this run was launched through ctx.runPlay. */
+  parentRunId?: string | null;
+  /** Root play-run id for nested ctx.runPlay descendants. */
+  rootRunId?: string | null;
   /** Workflow type (typically `'Workflow'`). */
   type: string;
   /** Human-readable status (e.g. `'Completed'`, `'Failed'`). */
   status: string;
   /** ISO 8601 timestamp when the run started. */
-  startTime: string | null;
+  startTime?: string | null;
+  /** Unix epoch milliseconds when the run started, returned by normalized V2 run summaries. */
+  startedAt?: number | string | null;
   /** ISO 8601 timestamp when the run finished. */
-  closeTime: string | null;
+  closeTime?: string | null;
+  /** Unix epoch milliseconds when the run finished, returned by normalized V2 run summaries. */
+  finishedAt?: number | string | null;
   /** Duration string (e.g. `'2.5s'`). */
   executionTime: string | null;
   /** Total Deepline credits charged for the run, when available. */
@@ -726,6 +744,7 @@ export interface PlayListItem {
   reference?: string;
   name: string;
   displayName?: string;
+  description?: string | null;
   origin?: 'prebuilt' | 'owned';
   ownerType?: 'deepline' | 'org';
   ownerSlug?: string;
@@ -752,6 +771,7 @@ export interface PlayDescription {
   name: string;
   reference?: string;
   displayName?: string;
+  description?: string | null;
   origin?: 'prebuilt' | 'owned';
   ownerType?: 'deepline' | 'org';
   canEdit?: boolean;
@@ -910,6 +930,8 @@ export interface StartPlayRunRequest {
   sourceCode?: string;
   /** Source graph snapshots for local helper files included in cloud preflight. */
   sourceFiles?: Record<string, string>;
+  /** Human-readable one-line description for the revision created by file-backed runs. */
+  description?: string;
   /** Static pipeline already produced while registering this artifact. */
   staticPipeline?: unknown;
   /** Artifact content hash already validated while registering this artifact. */

package/dist/bundling-sources/sdk/src/worker-play-entry.ts

@@ -53,6 +53,7 @@ const PLAY_METADATA_SYMBOL = Symbol.for('deepline.play.metadata');
 
 type PlayMetadata = {
   name: string;
+  description?: string;
   bindings?: PlayBindings;
   inputSchema?: Record<string, unknown>;
   billing?: PlayBindings['billing'];
@@ -206,6 +207,7 @@ export function definePlay<TInput, TOutput extends PlayReturnObject>(
           name: nameOrConfig,
           fn: maybeFn,
           bindings: maybeBindings,
+          description: maybeBindings?.description,
           inputSchema: undefined,
           billing: maybeBindings?.billing,
         }
@@ -213,12 +215,14 @@ export function definePlay<TInput, TOutput extends PlayReturnObject>(
           name: nameOrConfig.id,
           fn: nameOrConfig.run,
           bindings: nameOrConfig.bindings,
+          description: nameOrConfig.description,
           inputSchema: nameOrConfig.input.schema,
           billing: nameOrConfig.billing,
         };
 
   const name = config.name;
   const fn = config.fn;
+  const description = config.description?.trim();
   if (typeof fn !== 'function') {
     throw new Error('definePlay run must be async');
   }
@@ -240,6 +244,7 @@ export function definePlay<TInput, TOutput extends PlayReturnObject>(
 
   const metadata: PlayMetadata = {
     name,
+    ...(description ? { description } : {}),
     ...(config.bindings ? { bindings: config.bindings } : {}),
     ...(config.inputSchema ? { inputSchema: config.inputSchema } : {}),
     ...(config.billing ? { billing: config.billing } : {}),

package/dist/bundling-sources/shared_libs/play-runtime/app-runtime-api.ts

@@ -101,6 +101,8 @@ type RuntimeApiRequest =
       action: 'start_inline_child_run';
       playName: string;
       runId: string;
+      parentRunId?: string | null;
+      rootRunId?: string | null;
       workflowFamilyKey?: string | null;
       artifactStorageKey?: string | null;
       artifactHash?: string | null;
@@ -678,6 +680,8 @@ export async function startRunViaAppRuntime(
   input: {
     playName: string;
     runId: string;
+    parentRunId?: string | null;
+    rootRunId?: string | null;
     workflowFamilyKey?: string | null;
     artifactStorageKey?: string | null;
     artifactHash?: string | null;