deepline 0.1.122 → 0.1.124

package/dist/cli/index.mjs

@@ -380,10 +380,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: [
@@ -391,6 +392,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
@@ -1997,7 +2047,8 @@ var DeeplineClient = class {
       tail: (runId, options2) => this.tailRun(runId, options2),
       logs: (runId, options2) => this.getRunLogs(runId, options2),
       exportDatasetRows: (input2) => this.getPlaySheetRows(input2),
-      stop: (runId, options2) => this.stopRun(runId, options2)
+      stop: (runId, options2) => this.stopRun(runId, options2),
+      stopAll: (options2) => this.stopAllRuns(options2)
     };
     this.billing = {
       plans: () => this.getBillingPlans(),
@@ -2062,12 +2113,14 @@ var DeeplineClient = class {
       play.outputSchema,
       "rowOutputSchema"
     );
+    const description = play.description?.trim() || play.currentRevision?.description?.trim() || play.liveRevision?.description?.trim() || null;
     const runCommand2 = 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,
@@ -2288,6 +2341,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 } : {},
@@ -2326,6 +2380,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 } : {},
@@ -2483,6 +2538,7 @@ var DeeplineClient = class {
       name: input2.name,
       sourceCode: input2.sourceCode,
       sourceFiles: input2.sourceFiles,
+      description: input2.description,
       artifact: input2.artifact,
       compilerManifest,
       publish: false
@@ -2495,6 +2551,7 @@ var DeeplineClient = class {
     return this.startPlayRun({
       name: input2.name,
       artifactStorageKey: registeredArtifact.artifactStorageKey,
+      description: input2.description,
       compilerManifest,
       ...input2.input ? { input: input2.input } : {},
       ...input2.inputFile ? { inputFile: input2.inputFile } : {},
@@ -2549,6 +2606,7 @@ var DeeplineClient = class {
       name,
       sourceCode,
       sourceFiles: options?.sourceFiles,
+      description: options?.description,
       artifact,
       compilerManifest,
       publish: false
@@ -2562,6 +2620,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,
@@ -2861,15 +2920,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()}`
@@ -3176,6 +3241,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.
    *
@@ -6787,7 +6870,13 @@ import { basename, dirname as dirname6, join as join5, resolve as resolve7 } fro
 import { parse as parseCsvSync2 } from "csv-parse/sync";
 
 // src/cli/commands/plays/bootstrap.ts
-import { closeSync, openSync, readSync, statSync, writeFileSync as writeFileSync7 } from "fs";
+import {
+  closeSync,
+  openSync,
+  readSync,
+  statSync,
+  writeFileSync as writeFileSync7
+} from "fs";
 import { isAbsolute, relative, resolve as resolve6 } from "path";
 import { parse as parseCsvSync } from "csv-parse/sync";
 
@@ -8129,6 +8218,8 @@ export default definePlay(${jsString(input2.options.name)}, async (ctx, input: I
     count: await rows.count(),
     rows,
   };
+}, {
+  description: ${jsString(`Bootstrap ${input2.options.template}: seed source rows, run requested stages, and return mapped rows.`)},
 });
 
 `;
@@ -9512,6 +9603,24 @@ function requireCompilerManifest(node) {
   }
   return node.compilerManifest;
 }
+function missingPlayDescriptionMessage(node) {
+  const playName = node.playName ?? extractPlayName(node.sourceCode, node.filePath);
+  return [
+    `Play description is required for ${playName} (${node.filePath}).`,
+    "Add a top-level description to definePlay so agents and future play surfaces can explain what this play does.",
+    `Example: definePlay("${playName}", async (ctx, input) => { ... }, { description: "Look up company details from a domain." })`,
+    `Object form: definePlay({ id: "${playName}", description: "Look up company details from a domain.", input, run })`
+  ].join(" ");
+}
+function collectMissingPlayDescriptionErrors(graph) {
+  return [...graph.nodes.values()].filter((node) => !node.playDescription?.trim()).map(missingPlayDescriptionMessage);
+}
+function assertBundledPlayGraphDescriptions(graph) {
+  const errors = collectMissingPlayDescriptionErrors(graph);
+  if (errors.length > 0) {
+    throw new Error(errors.join("\n"));
+  }
+}
 async function publishImportedPlayDependencies(client2, graph) {
   const published = /* @__PURE__ */ new Set();
   const publishNode = async (filePath, skipPublish) => {
@@ -9535,6 +9644,7 @@ async function publishImportedPlayDependencies(client2, graph) {
       name: node.playName,
       sourceCode: node.sourceCode,
       sourceFiles: node.sourceFiles,
+      description: node.playDescription ?? void 0,
       artifact: node.artifact,
       compilerManifest: requireCompilerManifest(node),
       publish: true
@@ -12232,6 +12342,26 @@ async function handlePlayCheck(args) {
     return 1;
   }
   const playName = graph.root.playName ?? extractPlayName(sourceCode, absolutePlayPath);
+  const descriptionErrors = collectMissingPlayDescriptionErrors(graph);
+  if (descriptionErrors.length > 0) {
+    if (options.jsonOutput) {
+      process.stdout.write(
+        `${JSON.stringify({
+          name: playName,
+          valid: false,
+          stage: "authoring",
+          errors: descriptionErrors
+        })}
+`
+      );
+    } else {
+      console.error(`\u2717 ${playName} failed local play check`);
+      for (const error of descriptionErrors) {
+        console.error(`  ${error}`);
+      }
+    }
+    return 1;
+  }
   if (shouldUseLocalOnlyPlayCheck()) {
     const result2 = {
       valid: true,
@@ -12258,6 +12388,7 @@ async function handlePlayCheck(args) {
     name: playName,
     sourceCode: graph.root.sourceCode,
     sourceFiles: graph.root.sourceFiles,
+    description: graph.root.playDescription ?? void 0,
     artifact: graph.root.artifact
   });
   const enrichedResult = {
@@ -12315,6 +12446,7 @@ async function handleFileBackedRun(options) {
       { targetKind: "file" },
       () => collectBundledPlayGraph(absolutePlayPath, options.profile)
     );
+    assertBundledPlayGraphDescriptions(graph);
     const canDeferCompilerManifest = graph.root.importedPlayDependencies.length === 0 && !sourceGraphMentionsRunPlay(graph.root) && !inputContainsLocalFilePath(runtimeInput);
     if (canDeferCompilerManifest) {
       recordCliTrace({
@@ -12379,6 +12511,7 @@ async function handleFileBackedRun(options) {
     name: playName,
     sourceCode: bundleResult.sourceCode,
     sourceFiles: bundleResult.sourceFiles,
+    description: bundleResult.playDescription ?? void 0,
     runtimeArtifact: bundleResult.artifact,
     ...compilerManifest ? { compilerManifest } : {},
     packagedFileUploads,
@@ -12678,7 +12811,7 @@ async function handleRunGet(args) {
   return 0;
 }
 async function handleRunsList(args) {
-  const usage = "Usage: deepline runs list --play <play-name> [--status <status>] [--json]";
+  const usage = "Usage: deepline runs list [--play <play-name>] [--status <status>] [--json]";
   let playName = null;
   let statusFilter = null;
   for (let index = 0; index < args.length; index += 1) {
@@ -12695,28 +12828,32 @@ async function handleRunsList(args) {
       continue;
     }
   }
-  if (!playName) {
+  if (!playName && !statusFilter) {
     console.error(usage);
     return 1;
   }
   const client2 = new DeeplineClient();
   const runs = (await client2.runs.list({
-    play: playName,
+    ...playName ? { play: playName } : {},
     ...statusFilter ? { status: statusFilter } : {}
   })).map((run) => ({
     runId: run.workflowId,
     workflowId: run.workflowId,
     temporalRunId: run.runId,
+    parentRunId: run.parentRunId ?? null,
+    rootRunId: run.rootRunId ?? null,
     status: String(run.status ?? "").toLowerCase(),
-    startedAt: run.startTime,
-    finishedAt: run.closeTime,
+    startedAt: run.startTime ?? run.startedAt ?? null,
+    finishedAt: run.closeTime ?? run.finishedAt ?? null,
     executionTime: run.executionTime,
     billingTotalCredits: run.billingTotalCredits,
     billingMaxCreditsPerRun: run.billingMaxCreditsPerRun,
-    playName: run.memo?.playName ?? playName
+    playName: run.playName ?? run.memo?.playName ?? playName ?? null
   }));
-  const lines = runs.length === 0 ? [`No runs found for ${playName}.`] : runs.map(
-    (run) => `${run.runId} ${run.status} ${formatTimestamp(run.startedAt)} ${typeof run.billingTotalCredits === "number" && Number.isFinite(run.billingTotalCredits) ? `${formatCreditAmount(run.billingTotalCredits)} credits` : "\u2014"}`
+  const lines = runs.length === 0 ? [
+    playName ? `No runs found for ${playName}.` : `No runs found for status ${statusFilter}.`
+  ] : runs.map(
+    (run) => `${run.runId} ${run.status} ${formatTimestamp(run.startedAt)} ${typeof run.billingTotalCredits === "number" && Number.isFinite(run.billingTotalCredits) ? `${formatCreditAmount(run.billingTotalCredits)} credits` : "\u2014"}${run.parentRunId ? ` parent=${run.parentRunId}` : ""}`
   );
   printCommandEnvelope(
     {
@@ -12902,6 +13039,31 @@ async function handleRunStop(args) {
   );
   return 0;
 }
+async function handleRunStopAll(args) {
+  let reason;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--reason" && args[index + 1]) {
+      reason = args[++index];
+    }
+  }
+  const client2 = new DeeplineClient();
+  const result = await client2.runs.stopAll({ reason });
+  const lines = [
+    `Stopped ${result.stopped} active run${result.stopped === 1 ? "" : "s"}`,
+    ...result.partial ? ["partial: active runs may remain; rerun stop-all"] : [],
+    ...result.failed > 0 ? [`failed stops: ${result.failed}`] : [],
+    ...result.skipped > 0 ? [`skipped: ${result.skipped}`] : []
+  ];
+  printCommandEnvelope(
+    {
+      ...result,
+      render: { sections: [{ title: "workspace stop-all", lines }] }
+    },
+    { json: argsWantJson(args) }
+  );
+  return result.failed > 0 || result.partial ? 1 : 0;
+}
 async function handleRunExport(args) {
   const usage = "Usage: deepline runs export <run-id> [--dataset result.rows] --out output.csv [--metadata-out export.json] [--json]";
   let runId;
@@ -13161,6 +13323,9 @@ function printPlayDescription(play) {
   if (play.displayName && play.displayName !== play.name) {
     console.log(`  Display name: ${play.displayName}`);
   }
+  if (play.description) {
+    console.log(`  Description: ${play.description}`);
+  }
   if (play.aliases.length > 0) {
     console.log(`  Aliases: ${play.aliases.join(", ")}`);
   }
@@ -13213,6 +13378,9 @@ function printCompactPlaySearchResult(play) {
   if (play.displayName && play.displayName !== play.name) {
     console.log(`  Display name: ${play.displayName}`);
   }
+  if (play.description) {
+    console.log(`  Description: ${play.description}`);
+  }
   if (aliases) {
     console.log(`  Aliases: ${aliases}`);
   }
@@ -13526,6 +13694,7 @@ async function handlePlayPublish(args) {
         { targetKind: "file" },
         () => collectBundledPlayGraph(resolve7(playName))
       );
+      assertBundledPlayGraphDescriptions(graph);
       await traceCliSpan(
         "cli.play_publish_compile_manifests",
         { targetKind: "file", nodeCount: graph.nodes.size },
@@ -13552,6 +13721,7 @@ async function handlePlayPublish(args) {
         name: rootPlayName,
         sourceCode: graph.root.sourceCode,
         sourceFiles: graph.root.sourceFiles,
+        description: graph.root.playDescription ?? void 0,
         artifact: graph.root.artifact,
         compilerManifest: requireCompilerManifest(graph.root),
         publish: true
@@ -13930,7 +14100,9 @@ Examples:
 `
   );
   addPublishHelp(
-    play.command("publish <target>").description("Promote a saved play revision or publish a local play file.")
+    play.command("publish <target>").description(
+      "Promote a saved play revision or publish a local play file."
+    )
   ).option("--latest", "Promote the newest saved revision").option("--revision-id <id>", "Revision to promote").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (target, options) => {
     process.exitCode = await handlePlayPublish([
       target,
@@ -13940,9 +14112,7 @@ Examples:
     ]);
   });
   addPublishHelp(
-    play.command("set-live <target>").description(
-      "Promote a saved revision or publish a local play file."
-    )
+    play.command("set-live <target>").description("Promote a saved revision or publish a local play file.")
   ).option("--latest", "Promote the newest saved revision").option("--revision-id <id>", "Revision to promote").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (target, options) => {
     process.exitCode = await handlePlayPublish([
       target,
@@ -13983,7 +14153,9 @@ Examples:
   deepline runs tail play/my-play/run/20260501t000000-000
   deepline runs logs play/my-play/run/20260501t000000-000 --out run.log --json
   deepline runs list --play my-play --status failed --json
+  deepline runs list --status running --json
   deepline runs stop play/my-play/run/20260501t000000-000 --reason "stale lock" --json
+  deepline runs stop-all --reason "unjam workspace" --json
   deepline runs export play/my-play/run/20260501t000000-000 --out output.csv
 `
   );
@@ -14017,16 +14189,32 @@ Notes:
 Examples:
   deepline runs list --play my-play
   deepline runs list --play my-play --status failed --compact --json
+  deepline runs list --status running --compact --json
 `
-  ).requiredOption("--play <name>", "Play name to filter runs").option("--status <status>", "Filter by run status").option("--compact", "Drop verbose fields from JSON output").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
+  ).option("--play <name>", "Play name to filter runs").option("--status <status>", "Filter by run status").option("--compact", "Drop verbose fields from JSON output").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
     process.exitCode = await handleRunsList([
-      "--play",
-      options.play,
+      ...options.play ? ["--play", options.play] : [],
       ...options.status ? ["--status", options.status] : [],
       ...options.compact ? ["--compact"] : [],
       ...options.json ? ["--json"] : []
     ]);
   });
+  runs.command("stop-all").description("Stop active play runs in the current workspace.").addHelpText(
+    "after",
+    `
+Notes:
+  Stops all active runs visible to this workspace, including child runs created by ctx.runPlay.
+
+Examples:
+  deepline runs stop-all --reason "unjam workspace"
+  deepline runs stop-all --json
+`
+  ).option("--reason <text>", "Reason to include with each stop request").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
+    process.exitCode = await handleRunStopAll([
+      ...options.reason ? ["--reason", options.reason] : [],
+      ...options.json ? ["--json"] : []
+    ]);
+  });
   runs.command("tail <runId>").description("Read the canonical live stream for a play run.").addHelpText(
     "after",
     `
@@ -14982,7 +15170,7 @@ function compileEnrichConfigToPlaySource(config, options = {}) {
     ...metadataColumnSource ? [metadataColumnSource] : [],
     `    .run({ key: (row, index) => __dlStableRowKey(row, index + rowStart) });`,
     `  return { rows: enriched, count: await enriched.count() };`,
-    `});`
+    `}, { description: ${stringLiteral("Read a CSV file, run the configured Deepline enrich commands, and return enriched rows.")} });`
   ];
   const helpers = idiomaticGetters ? selectUsedHelpers(helperSource(), body.join("\n")) : helperSource();
   return [
@@ -20288,6 +20476,8 @@ export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
     rows: enrichedData,
     count: await enrichedData.count(),
   };
+}, {
+  description: ${JSON.stringify(`Seed ${input2.toolId} rows into a Deepline workflow-ready dataset.`)},
 });
 `;
   writeFileSync12(scriptPath, script, { encoding: "utf-8", mode: 384 });
@@ -22210,6 +22400,16 @@ function isLegacyNoopInvocation() {
   const command = process.argv.slice(2)[0];
   return command === "session" || command === "backend";
 }
+function compatibilityCommandPath(command) {
+  const names = [];
+  let current = command;
+  while (current?.parent) {
+    const name = current.name();
+    if (name) names.unshift(name);
+    current = current.parent;
+  }
+  return names.join(" ");
+}
 function topLevelCommandKnown(program, commandName) {
   const normalized = commandName.trim();
   if (!normalized || normalized.startsWith("-")) {
@@ -22234,6 +22434,8 @@ async function runPlayRunnerHealthCheck() {
         "    .withColumn('echo', (row) => ({ ok: true, id: row.id }))",
         "    .run({ key: 'id' });",
         "  return { ok: true, rows, source: 'deepline health --play-runner' };",
+        "}, {",
+        "  description: 'Run a local Deepline play health check with a tiny dataset.',",
         "});",
         ""
       ].join("\n"),
@@ -22445,11 +22647,12 @@ Exit codes:
       progress?.phase("checking sdk compatibility");
     }
     const baseUrl = autoDetectBaseUrl().replace(/\/$/, "");
+    const compatibilityCommand = compatibilityCommandPath(actionCommand) || actionCommand.name();
     const compatibility = await traceCliSpan(
       "cli.sdk_compatibility",
-      { baseUrl, command: actionCommand.name() },
+      { baseUrl, command: compatibilityCommand },
       () => checkSdkCompatibility(baseUrl, {
-        command: actionCommand.name()
+        command: compatibilityCommand
       })
     );
     if (compatibility.error) {