deepline 0.1.123 → 0.1.125

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/sdk/src/client.ts

@@ -932,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,
@@ -1212,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 }
           : {}),
@@ -1270,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 }
         : {}),
@@ -1322,6 +1330,7 @@ export class DeeplineClient {
     name: string;
     sourceCode: string;
     sourceFiles?: Record<string, string>;
+    description?: string;
     artifact: Record<string, unknown>;
     compilerManifest?: PlayCompilerManifest;
     publish?: boolean;
@@ -1371,6 +1380,7 @@ export class DeeplineClient {
       name: string;
       sourceCode: string;
       sourceFiles?: Record<string, string>;
+      description?: string;
       artifact: Record<string, unknown>;
       compilerManifest?: PlayCompilerManifest;
       publish?: boolean;
@@ -1496,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);
@@ -1525,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>;
@@ -1544,6 +1556,7 @@ export class DeeplineClient {
       name: input.name,
       sourceCode: input.sourceCode,
       sourceFiles: input.sourceFiles,
+      description: input.description,
       artifact: input.artifact,
       compilerManifest,
       publish: false,
@@ -1557,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 } : {}),
@@ -1598,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>;
@@ -1633,6 +1648,7 @@ export class DeeplineClient {
       name,
       sourceCode,
       sourceFiles: options?.sourceFiles,
+      description: options?.description,
       artifact,
       compilerManifest,
       publish: false,
@@ -1647,6 +1663,7 @@ export class DeeplineClient {
       name,
       artifactStorageKey: registeredArtifact.artifactStorageKey,
       sourceCode,
+      description: options?.description,
       staticPipeline: registeredArtifact.staticPipeline ?? null,
       artifactHash:
         typeof artifact.artifactHash === 'string'

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.123',
+  // 0.1.110 ships authored V2 prebuilts and required top-level play descriptions.
+  version: '0.1.125',
   apiContract: '2026-06-dataset-column-cell-stale-hard-cutover',
   supportPolicy: {
-    latest: '0.1.123',
+    latest: '0.1.125',
     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

@@ -744,6 +744,7 @@ export interface PlayListItem {
   reference?: string;
   name: string;
   displayName?: string;
+  description?: string | null;
   origin?: 'prebuilt' | 'owned';
   ownerType?: 'deepline' | 'org';
   ownerSlug?: string;
@@ -770,6 +771,7 @@ export interface PlayDescription {
   name: string;
   reference?: string;
   displayName?: string;
+  description?: string | null;
   origin?: 'prebuilt' | 'owned';
   ownerType?: 'deepline' | 'org';
   canEdit?: boolean;
@@ -928,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 } : {}),