deepline 0.1.122 → 0.1.124

package/dist/cli/index.js

@@ -403,10 +403,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: [
@@ -414,6 +415,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
@@ -2020,7 +2070,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(),
@@ -2085,12 +2136,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,
@@ -2311,6 +2364,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 } : {},
@@ -2349,6 +2403,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 } : {},
@@ -2506,6 +2561,7 @@ var DeeplineClient = class {
       name: input2.name,
       sourceCode: input2.sourceCode,
       sourceFiles: input2.sourceFiles,
+      description: input2.description,
       artifact: input2.artifact,
       compilerManifest,
       publish: false
@@ -2518,6 +2574,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 } : {},
@@ -2572,6 +2629,7 @@ var DeeplineClient = class {
       name,
       sourceCode,
       sourceFiles: options?.sourceFiles,
+      description: options?.description,
       artifact,
       compilerManifest,
       publish: false
@@ -2585,6 +2643,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,
@@ -2884,15 +2943,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()}`
@@ -3199,6 +3264,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.
    *
@@ -8126,6 +8209,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.`)},
 });
 
 `;
@@ -9509,6 +9594,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) => {
@@ -9532,6 +9635,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
@@ -12229,6 +12333,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,
@@ -12255,6 +12379,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 = {
@@ -12312,6 +12437,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({
@@ -12376,6 +12502,7 @@ async function handleFileBackedRun(options) {
     name: playName,
     sourceCode: bundleResult.sourceCode,
     sourceFiles: bundleResult.sourceFiles,
+    description: bundleResult.playDescription ?? void 0,
     runtimeArtifact: bundleResult.artifact,
     ...compilerManifest ? { compilerManifest } : {},
     packagedFileUploads,
@@ -12675,7 +12802,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) {
@@ -12692,28 +12819,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(
     {
@@ -12899,6 +13030,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;
@@ -13158,6 +13314,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(", ")}`);
   }
@@ -13210,6 +13369,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}`);
   }
@@ -13523,6 +13685,7 @@ async function handlePlayPublish(args) {
         { targetKind: "file" },
         () => collectBundledPlayGraph((0, import_node_path10.resolve)(playName))
       );
+      assertBundledPlayGraphDescriptions(graph);
       await traceCliSpan(
         "cli.play_publish_compile_manifests",
         { targetKind: "file", nodeCount: graph.nodes.size },
@@ -13549,6 +13712,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
@@ -13927,7 +14091,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,
@@ -13937,9 +14103,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,
@@ -13980,7 +14144,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
 `
   );
@@ -14014,16 +14180,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",
     `
@@ -14979,7 +15161,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 [
@@ -20272,6 +20454,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.`)},
 });
 `;
   (0, import_node_fs13.writeFileSync)(scriptPath, script, { encoding: "utf-8", mode: 384 });
@@ -22187,6 +22371,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("-")) {
@@ -22211,6 +22405,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"),
@@ -22422,11 +22618,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) {