deepline 0.1.123 → 0.1.124

package/dist/index.d.mts

@@ -697,6 +697,7 @@ interface PlayListItem {
     reference?: string;
     name: string;
     displayName?: string;
+    description?: string | null;
     origin?: 'prebuilt' | 'owned';
     ownerType?: 'deepline' | 'org';
     ownerSlug?: string;
@@ -722,6 +723,7 @@ interface PlayDescription {
     name: string;
     reference?: string;
     displayName?: string;
+    description?: string | null;
     origin?: 'prebuilt' | 'owned';
     ownerType?: 'deepline' | 'org';
     canEdit?: boolean;
@@ -873,6 +875,8 @@ 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. */
@@ -1512,6 +1516,7 @@ declare class DeeplineClient {
         name: string;
         sourceCode: string;
         sourceFiles?: Record<string, string>;
+        description?: string;
         artifact: Record<string, unknown>;
         compilerManifest?: PlayCompilerManifest;
         publish?: boolean;
@@ -1541,6 +1546,7 @@ declare class DeeplineClient {
         name: string;
         sourceCode: string;
         sourceFiles?: Record<string, string>;
+        description?: string;
         artifact: Record<string, unknown>;
         compilerManifest?: PlayCompilerManifest;
         publish?: boolean;
@@ -1588,6 +1594,7 @@ declare class DeeplineClient {
         name?: string;
         sourceCode: string;
         sourceFiles?: Record<string, string>;
+        description?: string;
         artifact: Record<string, unknown>;
     }): Promise<PlayCheckResult>;
     /**
@@ -1613,6 +1620,7 @@ declare class DeeplineClient {
         name: string;
         sourceCode: string;
         sourceFiles?: Record<string, string>;
+        description?: string;
         artifact: Record<string, unknown>;
         compilerManifest?: PlayCompilerManifest;
         input?: Record<string, unknown>;
@@ -1647,6 +1655,7 @@ declare class DeeplineClient {
     submitPlay(code: string, csvPath: string | null, name?: string, options?: {
         sourceCode?: string;
         sourceFiles?: Record<string, string>;
+        description?: string;
         artifact?: Record<string, unknown>;
         compilerManifest?: PlayCompilerManifest;
         input?: Record<string, unknown>;
@@ -2740,6 +2749,14 @@ type PreviousCell<Value = unknown> = {
  * @sdkReference runtime 030
  */
 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. */
@@ -3547,6 +3564,8 @@ type PlayInputContract<TInput> = {
 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. */
@@ -3600,6 +3619,7 @@ type DefinedPlay<TInput, TOutput extends PlayReturnObject> = ((ctx: DeeplinePlay
 };
 type PlayMetadata = {
     name: string;
+    description?: string;
     bindings?: PlayBindings;
     inputSchema?: Record<string, unknown>;
     billing?: PlayBindings['billing'];

package/dist/index.d.ts

@@ -697,6 +697,7 @@ interface PlayListItem {
     reference?: string;
     name: string;
     displayName?: string;
+    description?: string | null;
     origin?: 'prebuilt' | 'owned';
     ownerType?: 'deepline' | 'org';
     ownerSlug?: string;
@@ -722,6 +723,7 @@ interface PlayDescription {
     name: string;
     reference?: string;
     displayName?: string;
+    description?: string | null;
     origin?: 'prebuilt' | 'owned';
     ownerType?: 'deepline' | 'org';
     canEdit?: boolean;
@@ -873,6 +875,8 @@ 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. */
@@ -1512,6 +1516,7 @@ declare class DeeplineClient {
         name: string;
         sourceCode: string;
         sourceFiles?: Record<string, string>;
+        description?: string;
         artifact: Record<string, unknown>;
         compilerManifest?: PlayCompilerManifest;
         publish?: boolean;
@@ -1541,6 +1546,7 @@ declare class DeeplineClient {
         name: string;
         sourceCode: string;
         sourceFiles?: Record<string, string>;
+        description?: string;
         artifact: Record<string, unknown>;
         compilerManifest?: PlayCompilerManifest;
         publish?: boolean;
@@ -1588,6 +1594,7 @@ declare class DeeplineClient {
         name?: string;
         sourceCode: string;
         sourceFiles?: Record<string, string>;
+        description?: string;
         artifact: Record<string, unknown>;
     }): Promise<PlayCheckResult>;
     /**
@@ -1613,6 +1620,7 @@ declare class DeeplineClient {
         name: string;
         sourceCode: string;
         sourceFiles?: Record<string, string>;
+        description?: string;
         artifact: Record<string, unknown>;
         compilerManifest?: PlayCompilerManifest;
         input?: Record<string, unknown>;
@@ -1647,6 +1655,7 @@ declare class DeeplineClient {
     submitPlay(code: string, csvPath: string | null, name?: string, options?: {
         sourceCode?: string;
         sourceFiles?: Record<string, string>;
+        description?: string;
         artifact?: Record<string, unknown>;
         compilerManifest?: PlayCompilerManifest;
         input?: Record<string, unknown>;
@@ -2740,6 +2749,14 @@ type PreviousCell<Value = unknown> = {
  * @sdkReference runtime 030
  */
 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. */
@@ -3547,6 +3564,8 @@ type PlayInputContract<TInput> = {
 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. */
@@ -3600,6 +3619,7 @@ type DefinedPlay<TInput, TOutput extends PlayReturnObject> = ((ctx: DeeplinePlay
 };
 type PlayMetadata = {
     name: string;
+    description?: string;
     bindings?: PlayBindings;
     inputSchema?: Record<string, unknown>;
     billing?: PlayBindings['billing'];

package/dist/index.js

@@ -274,10 +274,11 @@ var 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.124",
   apiContract: "2026-06-dataset-column-cell-stale-hard-cutover",
   supportPolicy: {
-    latest: "0.1.123",
+    latest: "0.1.124",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53",
     commandMinimumSupported: [
@@ -285,6 +286,55 @@ var SDK_RELEASE = {
         command: "enrich",
         minimumSupported: "0.1.108",
         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
@@ -1957,12 +2007,14 @@ var DeeplineClient = class {
       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,
@@ -2183,6 +2235,7 @@ var DeeplineClient = class {
         ...request.artifactStorageKey ? { artifactStorageKey: request.artifactStorageKey } : {},
         ...request.sourceCode ? { sourceCode: request.sourceCode } : {},
         ...request.sourceFiles ? { sourceFiles: request.sourceFiles } : {},
+        ...request.description ? { description: request.description } : {},
         ..."staticPipeline" in request ? { staticPipeline: request.staticPipeline } : {},
         ...request.artifactHash ? { artifactHash: request.artifactHash } : {},
         ...request.graphHash ? { graphHash: request.graphHash } : {},
@@ -2221,6 +2274,7 @@ var DeeplineClient = class {
       ...request.artifactStorageKey ? { artifactStorageKey: request.artifactStorageKey } : {},
       ...request.sourceCode ? { sourceCode: request.sourceCode } : {},
       ...request.sourceFiles ? { sourceFiles: request.sourceFiles } : {},
+      ...request.description ? { description: request.description } : {},
       ..."staticPipeline" in request ? { staticPipeline: request.staticPipeline } : {},
       ...request.artifactHash ? { artifactHash: request.artifactHash } : {},
       ...request.graphHash ? { graphHash: request.graphHash } : {},
@@ -2378,6 +2432,7 @@ var DeeplineClient = class {
       name: input.name,
       sourceCode: input.sourceCode,
       sourceFiles: input.sourceFiles,
+      description: input.description,
       artifact: input.artifact,
       compilerManifest,
       publish: false
@@ -2390,6 +2445,7 @@ var DeeplineClient = class {
     return this.startPlayRun({
       name: input.name,
       artifactStorageKey: registeredArtifact.artifactStorageKey,
+      description: input.description,
       compilerManifest,
       ...input.input ? { input: input.input } : {},
       ...input.inputFile ? { inputFile: input.inputFile } : {},
@@ -2444,6 +2500,7 @@ var DeeplineClient = class {
       name,
       sourceCode,
       sourceFiles: options?.sourceFiles,
+      description: options?.description,
       artifact,
       compilerManifest,
       publish: false
@@ -2457,6 +2514,7 @@ var DeeplineClient = class {
       name,
       artifactStorageKey: registeredArtifact.artifactStorageKey,
       sourceCode,
+      description: options?.description,
       staticPipeline: registeredArtifact.staticPipeline ?? null,
       artifactHash: typeof artifact.artifactHash === "string" ? artifact.artifactHash : void 0,
       graphHash: typeof artifact.graphHash === "string" ? artifact.graphHash : void 0,
@@ -4719,18 +4777,21 @@ function definePlay(nameOrConfig, maybeFn, maybeBindings) {
     name: nameOrConfig,
     fn: maybeFn,
     bindings: maybeBindings,
+    description: maybeBindings?.description,
     inputSchema: void 0,
     billing: maybeBindings?.billing
   } : {
     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") {
@@ -4754,6 +4815,7 @@ function definePlay(nameOrConfig, maybeFn, maybeBindings) {
   }
   const metadata = {
     name,
+    ...description ? { description } : {},
     ...bindings ? { bindings } : {},
     ...inputSchema ? { inputSchema } : {},
     ...billing ? { billing } : {}

package/dist/index.mjs

@@ -196,10 +196,11 @@ var 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.124",
   apiContract: "2026-06-dataset-column-cell-stale-hard-cutover",
   supportPolicy: {
-    latest: "0.1.123",
+    latest: "0.1.124",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53",
     commandMinimumSupported: [
@@ -207,6 +208,55 @@ var SDK_RELEASE = {
         command: "enrich",
         minimumSupported: "0.1.108",
         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
@@ -1879,12 +1929,14 @@ var DeeplineClient = class {
       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,
@@ -2105,6 +2157,7 @@ var DeeplineClient = class {
         ...request.artifactStorageKey ? { artifactStorageKey: request.artifactStorageKey } : {},
         ...request.sourceCode ? { sourceCode: request.sourceCode } : {},
         ...request.sourceFiles ? { sourceFiles: request.sourceFiles } : {},
+        ...request.description ? { description: request.description } : {},
         ..."staticPipeline" in request ? { staticPipeline: request.staticPipeline } : {},
         ...request.artifactHash ? { artifactHash: request.artifactHash } : {},
         ...request.graphHash ? { graphHash: request.graphHash } : {},
@@ -2143,6 +2196,7 @@ var DeeplineClient = class {
       ...request.artifactStorageKey ? { artifactStorageKey: request.artifactStorageKey } : {},
       ...request.sourceCode ? { sourceCode: request.sourceCode } : {},
       ...request.sourceFiles ? { sourceFiles: request.sourceFiles } : {},
+      ...request.description ? { description: request.description } : {},
       ..."staticPipeline" in request ? { staticPipeline: request.staticPipeline } : {},
       ...request.artifactHash ? { artifactHash: request.artifactHash } : {},
       ...request.graphHash ? { graphHash: request.graphHash } : {},
@@ -2300,6 +2354,7 @@ var DeeplineClient = class {
       name: input.name,
       sourceCode: input.sourceCode,
       sourceFiles: input.sourceFiles,
+      description: input.description,
       artifact: input.artifact,
       compilerManifest,
       publish: false
@@ -2312,6 +2367,7 @@ var DeeplineClient = class {
     return this.startPlayRun({
       name: input.name,
       artifactStorageKey: registeredArtifact.artifactStorageKey,
+      description: input.description,
       compilerManifest,
       ...input.input ? { input: input.input } : {},
       ...input.inputFile ? { inputFile: input.inputFile } : {},
@@ -2366,6 +2422,7 @@ var DeeplineClient = class {
       name,
       sourceCode,
       sourceFiles: options?.sourceFiles,
+      description: options?.description,
       artifact,
       compilerManifest,
       publish: false
@@ -2379,6 +2436,7 @@ var DeeplineClient = class {
       name,
       artifactStorageKey: registeredArtifact.artifactStorageKey,
       sourceCode,
+      description: options?.description,
       staticPipeline: registeredArtifact.staticPipeline ?? null,
       artifactHash: typeof artifact.artifactHash === "string" ? artifact.artifactHash : void 0,
       graphHash: typeof artifact.graphHash === "string" ? artifact.graphHash : void 0,
@@ -4641,18 +4699,21 @@ function definePlay(nameOrConfig, maybeFn, maybeBindings) {
     name: nameOrConfig,
     fn: maybeFn,
     bindings: maybeBindings,
+    description: maybeBindings?.description,
     inputSchema: void 0,
     billing: maybeBindings?.billing
   } : {
     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") {
@@ -4676,6 +4737,7 @@ function definePlay(nameOrConfig, maybeFn, maybeBindings) {
   }
   const metadata = {
     name,
+    ...description ? { description } : {},
     ...bindings ? { bindings } : {},
     ...inputSchema ? { inputSchema } : {},
     ...billing ? { billing } : {}

package/dist/plays/bundle-play-file.d.mts

@@ -89,6 +89,7 @@ type BundledPlayFileSuccess = {
     sourceFiles: Record<string, string>;
     filePath: string;
     playName: string | null;
+    playDescription: string | null;
     compilerManifest?: PlayCompilerManifest;
     packagedFiles: PlayLocalFileReference[];
     unresolvedFileReferences: PlayLocalFileDiscoveryError[];

package/dist/plays/bundle-play-file.d.ts

@@ -89,6 +89,7 @@ type BundledPlayFileSuccess = {
     sourceFiles: Record<string, string>;
     filePath: string;
     playName: string | null;
+    playDescription: string | null;
     compilerManifest?: PlayCompilerManifest;
     packagedFiles: PlayLocalFileReference[];
     unresolvedFileReferences: PlayLocalFileDiscoveryError[];