deepline 0.3.121 → 0.3.123

package/dist/bundling-sources/shared_libs/play-runtime/run-identity.ts

@@ -152,6 +152,43 @@ export function buildAsyncPlayRunIdentity(input: {
   };
 }
 
+/**
+ * Build the retry-stable identity for one caller-keyed `runs rerun` request.
+ *
+ * The digest is namespaced (`-rerun-`) so a keyed replay can never collide
+ * with an ordinary entropy-suffixed run, an async child (`-async-`), or a
+ * differently keyed replay of the same source run. Everything else about a
+ * replay (input, revision, artifact, lane) is fixed by the source run, so the
+ * same `sourceRunId + idempotencyKey` always names the same intended Run and
+ * the existing run-ledger admission fence resolves repeats to it.
+ */
+export function buildRerunPlayRunIdentity(input: {
+  playName: string;
+  sourceRunId: string;
+  idempotencyKey: string;
+  /** Fallback ordering timestamp when the source id carries no canonical one. */
+  sourceStartedAtMs?: number | null;
+}): PlayRunIdentity {
+  const digest = sha256Hex(
+    `rerun\0${input.sourceRunId}\0${input.idempotencyKey}`,
+  ).slice(0, 20);
+  const startedAt =
+    canonicalPlayRunStartedAtMs(input.sourceRunId) ??
+    (typeof input.sourceStartedAtMs === 'number' &&
+    Number.isFinite(input.sourceStartedAtMs)
+      ? input.sourceStartedAtMs
+      : 0);
+  const base = buildPlayWorkflowId(input.playName, new Date(startedAt), {
+    unique: false,
+  });
+  const workflowId = `${base}-rerun-${digest}`;
+  return {
+    workflowId,
+    runId: workflowId,
+    workflowFamilyKey: buildPlayWorkflowFamilyKey(input.playName),
+  };
+}
+
 /** Immutable authored request identity, separate from the resolved revision. */
 export function buildAsyncPlayRequestFingerprint(input: {
   key: string;

package/dist/cli/index.js

@@ -3068,7 +3068,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.121",
+  version: "0.3.123",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1
@@ -6242,6 +6242,11 @@ async function* observeRunEvents(options) {
   }
 }
 
+// src/types.ts
+function isStopAllPlayRunsDryRunResult(result) {
+  return "dryRun" in result && result.dryRun === true;
+}
+
 // ../integration-contracts/theirstack/execution-policy.ts
 var THEIRSTACK_SLOW_JOB_SEARCH_PROVIDER_TIMEOUT_MS = 135e3;
 var THEIRSTACK_SLOW_JOB_SEARCH_CLIENT_TIMEOUT_MS = 6e4 + THEIRSTACK_SLOW_JOB_SEARCH_PROVIDER_TIMEOUT_MS + 15e3;
@@ -6946,10 +6951,10 @@ var DeeplineClient = class {
       tail: (runId, options2) => this.tailRun(runId, options2),
       logs: (runId, options2) => this.getRunLogs(runId, options2),
       input: (runId) => this.getRunInput(runId),
-      rerun: (runId) => this.rerun(runId),
+      rerun: (runId, options2) => this.rerun(runId, options2),
       exportDatasetRows: (input2) => this.getPlaySheetRows(input2),
       stop: (runId, options2) => this.stopRun(runId, options2),
-      stopAll: (options2) => this.stopAllRuns(options2)
+      stopAll: ((options2) => this.stopAllRuns(options2))
     };
     this.db = {
       query: (input2) => this.queryDb(input2)
@@ -8465,11 +8470,28 @@ var DeeplineClient = class {
   async getRunInput(runId) {
     return this.http.get(`/api/v2/runs/${encodeURIComponent(runId)}/input`);
   }
-  /** Start a fresh run from a prior run's retained input and pinned revision. */
-  async rerun(runId) {
+  /**
+   * Start a fresh run from a prior run's retained input and pinned revision.
+   *
+   * Every invocation sends an `Idempotency-Key`. When the caller does not
+   * supply one, a fresh key is generated once per call so the transport's own
+   * network retries converge on a single rerun. Pass the same explicit key
+   * across separate invocations to repeat an ambiguous result safely; a
+   * different key intentionally starts another rerun.
+   */
+  async rerun(runId, options) {
+    const idempotencyKey = options?.idempotencyKey?.trim();
+    if (options?.idempotencyKey !== void 0 && !idempotencyKey) {
+      throw new DeeplineError(
+        "runs.rerun idempotencyKey must not be empty.",
+        void 0,
+        "INVALID_IDEMPOTENCY_KEY"
+      );
+    }
     return this.http.post(
       `/api/v2/runs/${encodeURIComponent(runId)}/rerun`,
-      {}
+      {},
+      { "Idempotency-Key": idempotencyKey || globalThis.crypto.randomUUID() }
     );
   }
   /**
@@ -8614,11 +8636,13 @@ var DeeplineClient = class {
     );
   }
   /**
-   * Stop every active run visible to the current workspace.
+   * Stop every active run visible to the current workspace, or with
+   * `dryRun: true` enumerate the exact candidates without cancelling anything.
    *
    * This is the SDK equivalent of:
    *
    * ```bash
+   * deepline runs stop-all --dry-run --json
    * deepline runs stop-all --reason "stale lock" --json
    * ```
    *
@@ -8626,10 +8650,22 @@ var DeeplineClient = class {
    * need to clear the workspace run-slot state without knowing each run id.
    */
   async stopAllRuns(options) {
-    return this.http.post(
+    const dryRun = options?.dryRun === true;
+    const result = await this.http.post(
       "/api/v2/runs/stop-all",
-      options?.reason ? { reason: options.reason } : {}
+      {
+        ...options?.reason ? { reason: options.reason } : {},
+        ...dryRun ? { dryRun: true } : {}
+      }
     );
+    if (dryRun && !isStopAllPlayRunsDryRunResult(result)) {
+      throw new DeeplineError(
+        "This Deepline server does not support runs stop-all --dry-run and performed a real stop-all. Update the server before using --dry-run.",
+        void 0,
+        "STOP_ALL_DRY_RUN_UNSUPPORTED"
+      );
+    }
+    return result;
   }
   /**
    * List one page of callable plays; grep retains exhaustive matching results.
@@ -24441,6 +24477,77 @@ function authoredPackageStackFrames(packaged) {
     (line) => !line.includes("/virtual/deepline-plays/") && !line.includes("/apps/play-runner/") && !line.includes("/shared_libs/play-runtime/") && !line.includes("node:internal")
   ).slice(0, 5);
 }
+function activityTargetLabel(target) {
+  const kind = typeof target.kind === "string" ? target.kind : "target";
+  const label = typeof target.label === "string" ? target.label.trim() : "";
+  if (label) return `${kind} ${label}`;
+  switch (kind) {
+    case "provider":
+      return `provider ${String(target.provider ?? "?")} ${String(target.operation ?? "?")}`;
+    case "dataset":
+      return `dataset ${String(target.tableNamespace ?? "?")} (${String(target.operation ?? "?")})`;
+    case "lease":
+      return `${String(target.resourceKind ?? "resource")} lease ${String(target.resourceLabel ?? "?")}`;
+    case "runner":
+      return `runner ${String(target.backend ?? "?")}`;
+    case "step":
+      return `step ${String(target.stepId ?? "?")}`;
+    case "capacity":
+      return `${String(target.pool ?? "?")} capacity`;
+    default:
+      return kind;
+  }
+}
+function activityIsoTimestamp(value) {
+  return typeof value === "number" || typeof value === "string" ? isoTimestamp(value) : null;
+}
+function buildRunActivityTextLines(run) {
+  const activity = readRecord(run.activity);
+  const observation = readRecord(activity?.observation);
+  const state = readRecord(observation?.state);
+  const target = readRecord(observation?.target);
+  if (!activity || !observation || !state) return [];
+  const kind = typeof state.kind === "string" ? state.kind : "unknown";
+  if (kind === "completed") return [];
+  const summary = typeof activity.summary === "string" && activity.summary.trim() ? activity.summary.trim() : null;
+  const unclassified = activity.classified === false;
+  const lines = [];
+  lines.push(
+    `  activity: ${kind}${summary ? ` \u2014 ${summary}` : ""}${unclassified ? " (unclassified evidence; may be stale)" : ""}`
+  );
+  if (target) lines.push(`  target: ${activityTargetLabel(target)}`);
+  if (typeof observation.stepId === "string" && observation.stepId.trim()) {
+    lines.push(`  step: ${observation.stepId.trim()}`);
+  }
+  const reason = readRecord(state.reason);
+  if (kind === "retrying") {
+    const attempt = typeof state.attempt === "number" ? ` (attempt ${state.attempt})` : "";
+    const why = typeof state.reason === "string" ? ` after ${state.reason}` : "";
+    lines.push(
+      `  next retry: ${activityIsoTimestamp(state.retryAt) ?? "unknown"}${why}${attempt}`
+    );
+  } else if (kind === "scheduled") {
+    lines.push(
+      `  resumes: ${activityIsoTimestamp(state.resumeAt) ?? "unknown"}`
+    );
+  } else if (kind === "waiting" && reason) {
+    if (reason.kind === "external_event") {
+      const deadline = activityIsoTimestamp(reason.deadlineAt);
+      if (deadline) lines.push(`  deadline: ${deadline}`);
+      if (typeof reason.eventKey === "string" && reason.eventKey.trim()) {
+        lines.push(`  event key: ${reason.eventKey.trim()}`);
+      }
+    } else if (reason.kind === "lease") {
+      const expires = activityIsoTimestamp(reason.expiresAt);
+      if (expires) lines.push(`  lease expires: ${expires}`);
+    } else if (reason.kind === "unknown") {
+      lines.push("  wait reason: unknown (legacy producer)");
+    }
+  }
+  const observedAt = activityIsoTimestamp(observation.observedAt);
+  if (observedAt) lines.push(`  observed: ${observedAt}`);
+  return lines;
+}
 function buildRunPackageTextLines(packaged) {
   const run = readRunPackageRun(packaged);
   const runId = typeof run.id === "string" ? run.id : "unknown";
@@ -24491,6 +24598,7 @@ function buildRunPackageTextLines(packaged) {
   if (playName) {
     lines.push(`  play: ${playName}`);
   }
+  lines.push(...buildRunActivityTextLines(run));
   lines.push(...formatPackageValueOutputLines(packaged));
   lines.push(...formatPackageDatasetActionLines(packaged));
   const next = packaged.next && typeof packaged.next === "object" && !Array.isArray(packaged.next) ? packaged.next : {};
@@ -24634,6 +24742,11 @@ function writePlayResult(status, jsonOutput, options) {
     const displayError = formatPlayErrorForDisplay(status, progressError) ?? progressError;
     lines.push(`  error: ${truncateErrorForDisplay(displayError, runId)}`);
   }
+  lines.push(
+    ...buildRunActivityTextLines(
+      readRecord(status.run) ?? {}
+    )
+  );
   if (status.status === "failed") {
     const failedLogEntries = status.failedLogs?.entries ?? [];
     if (failedLogEntries.length > 0) {
@@ -26804,7 +26917,7 @@ function parseRunIdPositional(args, usage) {
       continue;
     }
     if (arg.startsWith("--log-level=")) continue;
-    if ((arg === "--out" || arg === "--reason" || arg === "--dataset") && args[index + 1]) {
+    if ((arg === "--out" || arg === "--reason" || arg === "--dataset" || arg === "--idempotency-key") && args[index + 1]) {
       index += 1;
       continue;
     }
@@ -26839,7 +26952,7 @@ async function handleRunGet(args) {
   return 0;
 }
 async function handleRunsRerun(args) {
-  const usage = "Usage: deepline runs rerun <run-id> [--json]";
+  const usage = "Usage: deepline runs rerun <run-id> [--idempotency-key <key>] [--json]";
   let runId;
   try {
     runId = parseRunIdPositional(args, usage);
@@ -26847,16 +26960,33 @@ async function handleRunsRerun(args) {
     console.error(error instanceof Error ? error.message : usage);
     return 1;
   }
-  const result = await new DeeplineClient().runs.rerun(runId);
+  let idempotencyKey;
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === "--idempotency-key") {
+      const value = args[index + 1];
+      if (!value || value.startsWith("--") || !value.trim()) {
+        console.error("--idempotency-key requires a non-empty value.");
+        return 1;
+      }
+      idempotencyKey = value.trim();
+      index += 1;
+    }
+  }
+  const result = await new DeeplineClient().runs.rerun(runId, {
+    ...idempotencyKey ? { idempotencyKey } : {}
+  });
   if (argsWantJson(args)) {
     printCommandEnvelope(result, { json: true });
   } else {
-    console.log(`
-Rerun started from ${runId}.`);
+    console.log(
+      result.deduplicated === true ? `
+Rerun already exists for ${runId} (matched by idempotency key): ${result.runId}` : `
+Rerun started from ${runId}.`
+    );
     console.log(`  inspect: deepline runs get ${result.runId} --json`);
     console.log(`  original input: deepline runs get ${result.runId} --input`);
     console.log(
-      "  This is a fresh run using the original input and pinned revision. Normal tool receipt reuse still applies."
+      result.deduplicated === true ? "  No new run was started. Use a different --idempotency-key to start another rerun." : "  This is a fresh run using the original input and pinned revision. Normal tool receipt reuse still applies."
     );
   }
   return 0;
@@ -27334,8 +27464,46 @@ async function handleRunStop(args) {
   );
   return 0;
 }
+function padColumn(value, width) {
+  return value.length >= width ? value : value + " ".repeat(width - value.length);
+}
+function buildStopAllDryRunTextLines(result) {
+  const count = result.candidateCount;
+  const lines = [
+    `Dry run: ${count} active run${count === 1 ? "" : "s"} would be stopped`,
+    `Scope: ${result.scope}`,
+    `Includes child runs: ${result.includesChildren ? "yes" : "no"}`
+  ];
+  if (result.runs.length > 0) {
+    const rows = result.runs.map((run) => [
+      run.runId,
+      run.playName ?? "\u2014",
+      run.status ?? "\u2014"
+    ]);
+    const header = ["RUN_ID", "PLAY", "STATUS"];
+    const widths = header.map(
+      (label, column) => Math.max(label.length, ...rows.map((row) => row[column].length))
+    );
+    lines.push("");
+    for (const row of [header, ...rows]) {
+      lines.push(
+        row.map(
+          (cell, column) => column === row.length - 1 ? cell : padColumn(cell, widths[column])
+        ).join("  ")
+      );
+    }
+  }
+  if (result.truncated) {
+    lines.push("");
+    lines.push(
+      `Showing the first ${result.runs.length} matching runs. Results are truncated; no runs were stopped.`
+    );
+  }
+  return lines;
+}
 async function handleRunStopAll(args) {
   let reason;
+  const dryRun = args.includes("--dry-run");
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
     if (arg === "--reason" && args[index + 1]) {
@@ -27343,6 +27511,21 @@ async function handleRunStopAll(args) {
     }
   }
   const client2 = new DeeplineClient();
+  if (dryRun) {
+    const result2 = await client2.runs.stopAll({ dryRun: true, reason });
+    const lines2 = buildStopAllDryRunTextLines(result2);
+    printCommandEnvelope(
+      {
+        ...result2,
+        render: {
+          sections: [{ title: "workspace stop-all (dry run)", lines: lines2 }]
+        }
+      },
+      { json: argsWantJson(args), text: `${lines2.join("\n")}
+` }
+    );
+    return 0;
+  }
   const result = await client2.runs.stopAll({ reason });
   const lines = [
     `Stopped ${result.stopped} active run${result.stopped === 1 ? "" : "s"}`,
@@ -29111,13 +29294,23 @@ Notes:
   The rerun uses the original input and exact saved revision. Normal completed
   tool receipts may be reused; inspect the new run before forcing any external
   side effect.
+  Every call sends an Idempotency-Key. Pass --idempotency-key to reuse the
+  same key across separate invocations (for example after an ambiguous or
+  lost response): the same source run and key always resolve to the same
+  rerun, and the JSON result reports deduplicated: true when nothing new was
+  started. A different key intentionally starts another rerun.
 
 Examples:
   deepline runs rerun play/my-play/webhook/abc --json
+  deepline runs rerun play/my-play/webhook/abc --idempotency-key incident-42 --json
 `
+  ).option(
+    "--idempotency-key <key>",
+    "Reuse this key so repeated calls resolve to one rerun"
   ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (runId, options) => {
     process.exitCode = await handleRunsRerun([
       runId,
+      ...options.idempotencyKey ? ["--idempotency-key", options.idempotencyKey] : [],
       ...options.json ? ["--json"] : []
     ]);
   });
@@ -29148,14 +29341,24 @@ Examples:
     `
 Notes:
   Stops all active runs visible to this workspace, including child runs created by ctx.runPlay.
+  --dry-run lists the exact candidates (same scope, statuses, and order) and
+  never cancels or mutates anything. A real stop-all exits nonzero when any
+  cancellation failed or the candidate list was truncated; failed runs stay
+  active and are reported truthfully.
 
 Examples:
+  deepline runs stop-all --dry-run
+  deepline runs stop-all --dry-run --json
   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) => {
+  ).option("--reason <text>", "Reason to include with each stop request").option(
+    "--dry-run",
+    "List the runs that would be stopped without cancelling anything"
+  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (options) => {
     process.exitCode = await handleRunStopAll([
       ...options.reason ? ["--reason", options.reason] : [],
+      ...options.dryRun ? ["--dry-run"] : [],
       ...options.json ? ["--json"] : []
     ]);
   });