deepline 0.3.122 → 0.3.123

package/README.md

@@ -46,4 +46,37 @@ Once setup is complete, tell your agent what you want to do:
 deepline doctor --json
 ```
 
+## Operate runs safely
+
+```bash
+deepline runs get play/my-play/run/20260706t233844-689-b0379871
+deepline runs stop-all --dry-run
+deepline runs stop-all --reason "incident cleanup"
+deepline runs rerun play/my-play/run/20260706t233844-689-b0379871 --idempotency-key incident-42
+```
+
+`runs get` shows status, current activity, and next steps. `stop-all --dry-run`
+lists what would be stopped (workspace-scoped, child runs included) and never
+cancels anything. A real `stop-all` reports a run as stopped only when the
+scheduler confirmed it and exits nonzero on partial or failed stops. `runs
+rerun` always sends an `Idempotency-Key`; reuse an explicit key to repeat an
+ambiguous result without starting a second rerun (`deduplicated: true` in
+`--json`). From code:
+
+```ts
+import { DeeplineClient } from 'deepline';
+
+const client = new DeeplineClient();
+const runId = 'play/my-play/run/20260706t233844-689-b0379871';
+const preview = await client.runs.stopAll({ dryRun: true });
+const rerun = await client.runs.rerun(runId, {
+  idempotencyKey: 'incident-42',
+});
+console.log(preview.candidateCount, rerun.deduplicated);
+```
+
+Webhook delivery retries use the existing
+`POST /api/v2/plays/webhook-deliveries/:receiptId` path; there is no separate
+trigger retry, deliveries, health, or debug command.
+
 Need help? Visit [code.deepline.com](https://code.deepline.com).

package/dist/bundling-sources/sdk/src/client.ts

@@ -76,6 +76,10 @@ import type {
   PlayDescription,
   StopPlayRunResult,
   StopAllPlayRunsResult,
+  StopAllPlayRunsDryRunResult,
+  StopAllPlayRunsStopResult,
+  RerunOptions,
+  RerunPlayRunResult,
   ClearPlayHistoryRequest,
   ClearPlayHistoryResult,
   PublishPlayVersionRequest,
@@ -95,6 +99,7 @@ import type {
   DeeplineAgentModelDescription,
   InferenceQuote,
 } from './types.js';
+import { isStopAllPlayRunsDryRunResult } from './types.js';
 import type { MonitorDefinition } from './monitors.js';
 import type { MonitorFleetDefinition } from './monitor-fleets.js';
 import type { PlayStagedFileRef } from './plays/local-file-discovery.js';
@@ -785,13 +790,7 @@ export type RunsNamespace = {
     replayedFromRunId: string | null;
   }>;
   /** Start a fresh run from a prior run's retained input and pinned revision. */
-  rerun: (runId: string) => Promise<{
-    runId: string;
-    replayedFromRunId: string;
-    revisionId: string | null;
-    status: string;
-    next: { inspect: string; input: string };
-  }>;
+  rerun: (runId: string, options?: RerunOptions) => Promise<RerunPlayRunResult>;
   /** List runs for one play, optionally filtered by status. */
   list: (options: RunsListOptions) => Promise<PlayRunListItem[]>;
   /** Read one run page with total, offset, limit and completeness metadata. */
@@ -814,8 +813,27 @@ export type RunsNamespace = {
     runId: string,
     options?: { reason?: string },
   ) => Promise<StopPlayRunResult>;
-  /** Stop active runs across the current workspace. */
-  stopAll: (options?: { reason?: string }) => Promise<StopAllPlayRunsResult>;
+  /**
+   * Stop active runs across the current workspace, or with `dryRun: true`
+   * enumerate the exact candidates without cancelling anything.
+   */
+  stopAll: {
+    (
+      options: StopAllRunsOptions & { dryRun: true },
+    ): Promise<StopAllPlayRunsDryRunResult>;
+    (
+      options?: StopAllRunsOptions & { dryRun?: false },
+    ): Promise<StopAllPlayRunsStopResult>;
+    (options?: StopAllRunsOptions): Promise<StopAllPlayRunsResult>;
+  };
+};
+
+/** Options for {@link RunsNamespace.stopAll} / {@link DeeplineClient.stopAllRuns}. */
+export type StopAllRunsOptions = {
+  /** Enumerate the candidate runs without cancelling or mutating anything. */
+  dryRun?: boolean;
+  /** Reason recorded with each stop request. Ignored by a dry run. */
+  reason?: string;
 };
 
 /** Current mutable customer database namespace exposed as `client.db`. */
@@ -2513,10 +2531,11 @@ export class DeeplineClient {
       tail: (runId, options) => this.tailRun(runId, options),
       logs: (runId, options) => this.getRunLogs(runId, options),
       input: (runId) => this.getRunInput(runId),
-      rerun: (runId) => this.rerun(runId),
+      rerun: (runId, options) => this.rerun(runId, options),
       exportDatasetRows: (input) => this.getPlaySheetRows(input),
       stop: (runId, options) => this.stopRun(runId, options),
-      stopAll: (options) => this.stopAllRuns(options),
+      stopAll: ((options?: StopAllRunsOptions) =>
+        this.stopAllRuns(options)) as RunsNamespace['stopAll'],
     };
     this.db = {
       query: (input) => this.queryDb(input),
@@ -4577,17 +4596,31 @@ export class DeeplineClient {
     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: string): Promise<{
-    runId: string;
-    replayedFromRunId: string;
-    revisionId: string | null;
-    status: string;
-    next: { inspect: string; input: string };
-  }> {
-    return this.http.post(
+  /**
+   * 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: string,
+    options?: RerunOptions,
+  ): Promise<RerunPlayRunResult> {
+    const idempotencyKey = options?.idempotencyKey?.trim();
+    if (options?.idempotencyKey !== undefined && !idempotencyKey) {
+      throw new DeeplineError(
+        'runs.rerun idempotencyKey must not be empty.',
+        undefined,
+        'INVALID_IDEMPOTENCY_KEY',
+      );
+    }
+    return this.http.post<RerunPlayRunResult>(
       `/api/v2/runs/${encodeURIComponent(runId)}/rerun`,
       {},
+      { 'Idempotency-Key': idempotencyKey || globalThis.crypto.randomUUID() },
     );
   }
 
@@ -4771,25 +4804,53 @@ export class DeeplineClient {
     );
   }
 
+  /** Enumerate the runs a stop-all would target without cancelling any. */
+  async stopAllRuns(
+    options: StopAllRunsOptions & { dryRun: true },
+  ): Promise<StopAllPlayRunsDryRunResult>;
+  /** Stop every active run visible to the current workspace. */
+  async stopAllRuns(
+    options?: StopAllRunsOptions & { dryRun?: false },
+  ): Promise<StopAllPlayRunsStopResult>;
+  /** Stop, or with `dryRun: true` only enumerate, active workspace runs. */
+  async stopAllRuns(
+    options?: StopAllRunsOptions,
+  ): Promise<StopAllPlayRunsResult>;
   /**
-   * 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
    * ```
    *
    * 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?: {
-    reason?: string;
-  }): Promise<StopAllPlayRunsResult> {
-    return this.http.post<StopAllPlayRunsResult>(
+  async stopAllRuns(
+    options?: StopAllRunsOptions,
+  ): Promise<StopAllPlayRunsResult> {
+    const dryRun = options?.dryRun === true;
+    const result = await this.http.post<StopAllPlayRunsResult>(
       '/api/v2/runs/stop-all',
-      options?.reason ? { reason: options.reason } : {},
+      {
+        ...(options?.reason ? { reason: options.reason } : {}),
+        ...(dryRun ? { dryRun: true } : {}),
+      },
     );
+    if (dryRun && !isStopAllPlayRunsDryRunResult(result)) {
+      // An older server ignores unknown body fields and would have stopped
+      // runs for real. It cannot un-stop them, so say exactly what happened.
+      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.',
+        undefined,
+        'STOP_ALL_DRY_RUN_UNSUPPORTED',
+      );
+    }
+    return result;
   }
 
   /**

package/dist/bundling-sources/sdk/src/index.ts

@@ -125,11 +125,13 @@ export type {
   RunsLogsResult,
   RunsNamespace,
   RunsTailOptions,
+  StopAllRunsOptions,
   ToolExecution,
 } from './client.js';
 
 // ——— Monitors framework ———
 export { defineMonitor } from './monitors.js';
+export { isStopAllPlayRunsDryRunResult } from './types.js';
 export type { MonitorDefinition, MonitorPayload } from './monitors.js';
 export {
   lintMonitorBatchInput,
@@ -267,6 +269,12 @@ export type {
   DeeplineToolCategory,
   PlayBootstrapFinderKind,
   PlayBootstrapEntityKind,
+  RerunOptions,
+  RerunPlayRunResult,
+  StopAllCandidate,
+  StopAllPlayRunsDryRunResult,
+  StopAllPlayRunsResult,
+  StopAllPlayRunsStopResult,
   StopPlayRunResult,
   ToolSearchOptions,
   ToolSearchResult,

package/dist/bundling-sources/sdk/src/release.ts

@@ -200,7 +200,7 @@ export const 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.122',
+  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: {

package/dist/bundling-sources/sdk/src/types.ts

@@ -958,14 +958,88 @@ export interface StopPlayRunResult {
   error?: string;
 }
 
-export interface StopAllPlayRunsResult {
+/**
+ * Result of an actual workspace stop-all. `stopped` counts only runs whose
+ * scheduler cancellation was confirmed; a run whose cancel failed stays active
+ * and is counted in `failed`.
+ */
+export interface StopAllPlayRunsStopResult {
   stopped: number;
   failed: number;
   skipped: number;
+  /** True when the bounded candidate query may have left active runs behind. */
   partial?: boolean;
   runs: Array<StopPlayRunResult & { status?: string | null }>;
 }
 
+/** Options for {@link DeeplineClient.rerun} / `runs.rerun`. */
+export interface RerunOptions {
+  /**
+   * Caller-chosen key sent as `Idempotency-Key`. The same source run and key
+   * always resolve to the same rerun; omit it to let the SDK generate one key
+   * per invocation.
+   */
+  idempotencyKey?: string;
+}
+
+/** Result of {@link DeeplineClient.rerun} / `runs.rerun`. */
+export interface RerunPlayRunResult {
+  /** The rerun's public play-run id. */
+  runId: string;
+  /** The source run whose retained input and revision were replayed. */
+  replayedFromRunId: string;
+  revisionId: string | null;
+  status: string;
+  /**
+   * True when the server returned an already-admitted rerun for this source
+   * run and idempotency key instead of starting another. Absent on older
+   * servers.
+   */
+  deduplicated?: boolean;
+  next: { inspect: string; input: string };
+}
+
+/** One active run that a workspace stop-all would target. */
+export interface StopAllCandidate {
+  /** Public play-run id. */
+  runId: string;
+  /** Saved play name for the run, when known. */
+  playName: string | null;
+  /** Current durable status (`running`, `queued`, or `waiting`). */
+  status: string | null;
+  /** Parent play-run id when this is a child run; null for root runs. */
+  parentRunId: string | null;
+}
+
+/**
+ * Result of `runs.stopAll({ dryRun: true })`. Nothing was cancelled or
+ * mutated; the list is the exact candidate set the real stop-all would target,
+ * in the same parent-before-child order.
+ */
+export interface StopAllPlayRunsDryRunResult {
+  dryRun: true;
+  scope: 'workspace';
+  includesChildren: true;
+  candidateCount: number;
+  /** True when the bounded query hit its limit and more active runs may exist. */
+  truncated: boolean;
+  runs: StopAllCandidate[];
+}
+
+/**
+ * Discriminated result of {@link DeeplineClient.stopAllRuns}: narrow on
+ * `'dryRun' in result` to distinguish an enumeration from an actual stop.
+ */
+export type StopAllPlayRunsResult =
+  | StopAllPlayRunsStopResult
+  | StopAllPlayRunsDryRunResult;
+
+export function isStopAllPlayRunsDryRunResult(
+  result: StopAllPlayRunsResult,
+): result is StopAllPlayRunsDryRunResult {
+  return 'dryRun' in result && result.dryRun === true;
+}
+
 /**
  * Summary of a single play run, returned by {@link DeeplineClient.listPlayRuns}.
  */

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;