deepline 0.1.122 → 0.1.124

package/dist/index.d.mts

@@ -515,22 +515,41 @@ interface StopPlayRunResult {
     /** Server-side error detail when the stop was not confirmed. */
     error?: string;
 }
+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}.
  */
 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. */
@@ -678,6 +697,7 @@ interface PlayListItem {
     reference?: string;
     name: string;
     displayName?: string;
+    description?: string | null;
     origin?: 'prebuilt' | 'owned';
     ownerType?: 'deepline' | 'org';
     ownerSlug?: string;
@@ -703,6 +723,7 @@ interface PlayDescription {
     name: string;
     reference?: string;
     displayName?: string;
+    description?: string | null;
     origin?: 'prebuilt' | 'owned';
     ownerType?: 'deepline' | 'org';
     canEdit?: boolean;
@@ -854,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. */
@@ -1041,8 +1064,9 @@ type ToolExecution<TData = unknown, TMeta = Record<string, unknown>> = {
 };
 /** Filters for `client.runs.list(...)`. */
 type RunsListOptions = {
-    play: string;
+    play?: string;
     status?: string;
+    limit?: number;
 };
 /** Streaming options for `client.runs.tail(...)`. */
 type RunsTailOptions = {
@@ -1155,6 +1179,10 @@ type RunsNamespace = {
     stop: (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. */
 type BillingCreditPool = {
@@ -1488,6 +1516,7 @@ declare class DeeplineClient {
         name: string;
         sourceCode: string;
         sourceFiles?: Record<string, string>;
+        description?: string;
         artifact: Record<string, unknown>;
         compilerManifest?: PlayCompilerManifest;
         publish?: boolean;
@@ -1517,6 +1546,7 @@ declare class DeeplineClient {
         name: string;
         sourceCode: string;
         sourceFiles?: Record<string, string>;
+        description?: string;
         artifact: Record<string, unknown>;
         compilerManifest?: PlayCompilerManifest;
         publish?: boolean;
@@ -1564,6 +1594,7 @@ declare class DeeplineClient {
         name?: string;
         sourceCode: string;
         sourceFiles?: Record<string, string>;
+        description?: string;
         artifact: Record<string, unknown>;
     }): Promise<PlayCheckResult>;
     /**
@@ -1589,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>;
@@ -1623,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>;
@@ -1890,6 +1923,21 @@ declare class DeeplineClient {
     stopRun(runId: string, options?: {
         reason?: string;
     }): Promise<StopPlayRunResult>;
+    /**
+     * 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.
+     */
+    stopAllRuns(options?: {
+        reason?: string;
+    }): Promise<StopAllPlayRunsResult>;
     /**
      * List callable plays visible to the workspace.
      *
@@ -2701,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. */
@@ -3508,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. */
@@ -3561,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

@@ -515,22 +515,41 @@ interface StopPlayRunResult {
     /** Server-side error detail when the stop was not confirmed. */
     error?: string;
 }
+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}.
  */
 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. */
@@ -678,6 +697,7 @@ interface PlayListItem {
     reference?: string;
     name: string;
     displayName?: string;
+    description?: string | null;
     origin?: 'prebuilt' | 'owned';
     ownerType?: 'deepline' | 'org';
     ownerSlug?: string;
@@ -703,6 +723,7 @@ interface PlayDescription {
     name: string;
     reference?: string;
     displayName?: string;
+    description?: string | null;
     origin?: 'prebuilt' | 'owned';
     ownerType?: 'deepline' | 'org';
     canEdit?: boolean;
@@ -854,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. */
@@ -1041,8 +1064,9 @@ type ToolExecution<TData = unknown, TMeta = Record<string, unknown>> = {
 };
 /** Filters for `client.runs.list(...)`. */
 type RunsListOptions = {
-    play: string;
+    play?: string;
     status?: string;
+    limit?: number;
 };
 /** Streaming options for `client.runs.tail(...)`. */
 type RunsTailOptions = {
@@ -1155,6 +1179,10 @@ type RunsNamespace = {
     stop: (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. */
 type BillingCreditPool = {
@@ -1488,6 +1516,7 @@ declare class DeeplineClient {
         name: string;
         sourceCode: string;
         sourceFiles?: Record<string, string>;
+        description?: string;
         artifact: Record<string, unknown>;
         compilerManifest?: PlayCompilerManifest;
         publish?: boolean;
@@ -1517,6 +1546,7 @@ declare class DeeplineClient {
         name: string;
         sourceCode: string;
         sourceFiles?: Record<string, string>;
+        description?: string;
         artifact: Record<string, unknown>;
         compilerManifest?: PlayCompilerManifest;
         publish?: boolean;
@@ -1564,6 +1594,7 @@ declare class DeeplineClient {
         name?: string;
         sourceCode: string;
         sourceFiles?: Record<string, string>;
+        description?: string;
         artifact: Record<string, unknown>;
     }): Promise<PlayCheckResult>;
     /**
@@ -1589,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>;
@@ -1623,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>;
@@ -1890,6 +1923,21 @@ declare class DeeplineClient {
     stopRun(runId: string, options?: {
         reason?: string;
     }): Promise<StopPlayRunResult>;
+    /**
+     * 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.
+     */
+    stopAllRuns(options?: {
+        reason?: string;
+    }): Promise<StopAllPlayRunsResult>;
     /**
      * List callable plays visible to the workspace.
      *
@@ -2701,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. */
@@ -3508,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. */
@@ -3561,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.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: [
@@ -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
@@ -1891,7 +1941,8 @@ var DeeplineClient = class {
       tail: (runId, options2) => this.tailRun(runId, options2),
       logs: (runId, options2) => this.getRunLogs(runId, options2),
       exportDatasetRows: (input) => this.getPlaySheetRows(input),
-      stop: (runId, options2) => this.stopRun(runId, options2)
+      stop: (runId, options2) => this.stopRun(runId, options2),
+      stopAll: (options2) => this.stopAllRuns(options2)
     };
     this.billing = {
       plans: () => this.getBillingPlans(),
@@ -1956,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,
@@ -2182,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 } : {},
@@ -2220,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 } : {},
@@ -2377,6 +2432,7 @@ var DeeplineClient = class {
       name: input.name,
       sourceCode: input.sourceCode,
       sourceFiles: input.sourceFiles,
+      description: input.description,
       artifact: input.artifact,
       compilerManifest,
       publish: false
@@ -2389,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 } : {},
@@ -2443,6 +2500,7 @@ var DeeplineClient = class {
       name,
       sourceCode,
       sourceFiles: options?.sourceFiles,
+      description: options?.description,
       artifact,
       compilerManifest,
       publish: false
@@ -2456,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,
@@ -2755,15 +2814,21 @@ var DeeplineClient = class {
    * ```
    */
   async listRuns(options) {
-    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(
       `/api/v2/runs?${params.toString()}`
@@ -3070,6 +3135,24 @@ var DeeplineClient = class {
       options?.reason ? { reason: options.reason } : {}
     );
   }
+  /**
+   * 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) {
+    return this.http.post(
+      "/api/v2/runs/stop-all",
+      options?.reason ? { reason: options.reason } : {}
+    );
+  }
   /**
    * List callable plays visible to the workspace.
    *
@@ -4694,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") {
@@ -4729,6 +4815,7 @@ function definePlay(nameOrConfig, maybeFn, maybeBindings) {
   }
   const metadata = {
     name,
+    ...description ? { description } : {},
     ...bindings ? { bindings } : {},
     ...inputSchema ? { inputSchema } : {},
     ...billing ? { billing } : {}